chore: Add more Tailorings docs (#2368)

* chore(docs): Move docs higher up

* chore(docs): Add more docs related to Tailorings

.jsdoc.json

@@ -4,7 +4,7 @@
         "dictionaries": ["jsdoc"]
     },
     "source": {
-        "include": ["src/", "src/docs/README.md"]
+        "include": ["src/", "README.md"]
     },
     "plugins": [
         "plugins/markdown",
@@ -13,8 +13,9 @@
     ],
     "opts": {
         "destination": "./docs/",
+        "template": "node_modules/better-docs",
         "recurse": true,
-        "template": "node_modules/better-docs"
+        "tutorials": "./src/docs/"
     },
     "templates": {
         "cleverLinks": true,

package.json

@@ -187,6 +187,6 @@
     "bump:patternfly": "npm update @patternfly/react-core @patternfly/react-table @patternfly/react-charts @patternfly/react-tokens @patternfly/react-icons --save",
     "coverage": "bash coverage.sh && npm run coverage:clean",
     "postinstall": "ts-patch install",
-    "docs": "jsdoc -r -u src/Frameworks/AsyncTableTools/docs --configure .jsdoc.json"
+    "docs": "jsdoc --configure .jsdoc.json"
   }
 }

src/PresentationalComponents/RulesTable/RulesTableRest.js

@@ -8,23 +8,54 @@ import buildFilterConfig from './Filters';
 import defaultColumns from './Columns';
 import { List } from 'react-content-loader';
 
+/**
+ * A component to show rules of a policy or test result.
+ *
+ *  @param   {object}             [props]                      React component props
+ *  @param   {Array}              props.columns                A set of RulesTable columns
+ *  @param   {Array}              [props.rules]                A set of rules (for the current page to show)
+ *  @param   {number}             [props.total]                The overall total number of rules available to go through
+ *  @param   {object}             [props.ruleTree]             A table tree to show the rules in. If provided it will enable the "table view" toggle
+ *  @param   {string}             [props.policyId]             A policy ID used for remediations and as profile for rules
+ *  @param   {string}             [props.policyName]           A policy name used in the profile of rule items
+ *  @param   {object}             [props.reportTestResult]     A report test result used for the remediatons button
+ *  @param   {boolean}            [props.remediationsEnabled]  Enables the "RemediationButton"
+ *  @param   {boolean}            [props.ansibleSupportFilter] Enables the ansible filter
+ *  @param   {boolean}            [props.selectedFilter]       Enables the "Selected Only" filter
+ *  @param   {Array}              [props.selectedRules]        An array of rule IDs currently selected
+ *  @param   {boolean}            [props.hidePassed]           Enables a default filter to only show failed rules.
+ *  @param   {object}             [props.options ]             AsyncTableTools options
+ *  @param   {boolean}            [props.activeFiltersPassed]  Enable Default filter
+ *  @param   {string}             [props.activeFilters]        Default filter
+ *  @param   {object}             [props.ruleValues]           An object of values to show for certain rule values
+ *  @param   {Array}              [props.valueDefinitions]     An array of value definitons available for rules in the table
+ *  @param   {boolean}            [props.skipValueDefinitions] TODO
+ *  @param   {Function}           [props.onRuleValueReset]     A function called when a rule value is reset
+ *  @param   {React.ReactElement} [props.DedicatedAction]      A dedicated action to show in the table
+ *  @param   {object}             [props.valueOverrides]       An object of rule values // TODO we should make the name of this more consistent
+ *  @param   {Function}           [props.onValueOverrideSave]  A funciton called when a value is saved
+ *  @param   {Function}           [props.onSelect]             A function called when a selection action is performed
+ *  @param   {string}             [props.defaultTableView]     A table view to show by default ("row" or "tree") // TODO we should use the table options directly
+ *
+ *  @returns {React.ReactElement}
+ *
+ *  @category Compliance
+ *
+ */
 const RulesTable = ({
-  system,
   rules,
   ruleTree,
   policyId,
   policyName,
   columns = defaultColumns,
   remediationsEnabled = true,
   ansibleSupportFilter = false,
-  selectedFilter = false,
+  selectedFilter = false, // TODO this is potentially obsolete.
   selectedRules: selectedRulesProp = [],
   hidePassed = false,
   options,
-  activeFiltersPassed = false, // Enable Default filter
-  activeFilters, // Default filter
-  // showFailedCounts = false, // TODO We need systems counts
-  setRuleValues,
+  activeFiltersPassed = false,
+  activeFilters,
   ruleValues,
   valueDefinitions,
   skipValueDefinitions,
@@ -190,24 +221,19 @@ const RulesTable = ({
 };
 
 RulesTable.propTypes = {
-  profileRules: propTypes.array,
-  rules: propTypes.array.isRequired,
+  rules: propTypes.array,
   ruleTree: propTypes.array,
-  policyId: propTypes.string.isRequired,
+  policyId: propTypes.string,
   policyName: propTypes.string,
-  loading: propTypes.bool,
   hidePassed: propTypes.bool,
   activeFiltersPassed: propTypes.bool,
-  system: propTypes.object,
   remediationsEnabled: propTypes.bool,
   ansibleSupportFilter: propTypes.bool,
   selectedRules: propTypes.array,
   selectedFilter: propTypes.bool,
   columns: propTypes.array,
   options: propTypes.object,
   activeFilters: propTypes.object,
-  showFailedCounts: propTypes.number,
-  setRuleValues: propTypes.func,
   ruleValues: propTypes.object,
   onRuleValueReset: propTypes.func,
   DedicatedAction: propTypes.node,

src/PresentationalComponents/Tailorings/Tailorings.js

@@ -16,11 +16,13 @@ import NoTailorings from './NoTailorings';
 // TODO defaultTab  defaultTab={getDefaultTab(tailorings, defaultTab)}
 
 /**
- * This component is used to show either the tailorings with rules of a specific policy,
- * or the rules of a specific security guide and it's rules for a set of minor OS versions
+ * This component is used to show either a specific policy an it's tailorings,
+ * or a specific security guide and specific profiles,
+ * or a specific policy with it's existing tailorings and the default ruleset from the security guide for a specified set of minor OS versions.
  *
- *  @param   {object}             [props]
+ *  @param   {object}             [props]                                React component props
  *  @param   {object}             [props.policy]                         A policy object from the API
+ *  @param   {string}             [props.policy.id]                      The id used to fetch the tailorings associated with it
  *  @param   {string}             [props.profiles]                       An array of objects containing osMajorVersion, osMinorVersion, securityGuideId, profileId props for showing additional tabs.
  *  @param   {string}             [props.defaultTab]                     TODO
  *  @param   {Array}              [props.columns]                        An array of RulesTable columns
@@ -30,112 +32,17 @@ import NoTailorings from './NoTailorings';
  *  @param   {Function}           [props.onSelect]                       Callback function called when any selection is made
  *  @param   {object}             [props.preselected]                    An object containing the preselection of rules for each tab
  *  @param   {boolean}            [props.enableSecurityGuideRulesToggle] Will enable the "Only Selected" toggle. When a policy with tailorings is shown and the toggle is enabled it will request rule data from the tailoring, with it disabled it will load rule data from the security guide. If a profile is provided it will load rules either from the profile, if the toggle is enabled, otherwise from the security guide.
+ *  @param   {object}             [props.selectedVersionCounts]          An object containing minor version as a key and count as a value. Helps to render the system count badge in tab headers.
+ *  @param   {object}             [props.valueOverrides]                 **deprecated** It should be calles "ruleValues"
  *  @param                        [props.rulesPageLink]
  *
- *  @param   {object}             props.selectedVersionCounts            An object containing minor version as a key and count as a value. Helps to render the system count badge in tab headers.
- *  @param                        props.valueOverrides
  *  @returns {React.ReactElement}
  *
  *  @category Compliance
+ *  @tutorial how-to-use-tailorings
  *
- *
- *  @example
- *
- *  // Will show the tailorings of a policy
- *
- *  <Tailorings
- *   ouiaId="RHELVersions"
- *   columns={[
- *     Columns.Name,
- *     Columns.Severity,
- *     Columns.Remediation,
- *   ]}
- *   policy={policy}
- * />
- *
- *  // Will show the tailorings of a policy and an additional tabs for other OS minor version to show
- *
- *  <Tailorings
- *   ouiaId="RHELVersions"
- *   columns={[
- *     Columns.Name,
- *     Columns.Severity,
- *     Columns.Remediation,
- *   ]}
- *   policy={policy}
- *   profiles={[
- *    {
- *      osMajorVersion: 9,
- *      osMinorVersion: 1,
- *      securityGuideId: 'XYZ-ABC',
- *      profileId: 'XYZ-ABC',
- *    },
- *    {
- *      osMajorVersion: 9,
- *      osMinorVersion: 2,
- *      securityGuideId: 'XYZ-ABC',
- *      profileId: 'XYZ-ABC',
- *    },
- *  ]}
- * />
- *
- *  // Will show tabs with rules from the security guide and the specified OS minor versions
- *
- *  <Tailorings
- *   ouiaId="RHELVersions"
- *   columns={[
- *     Columns.Name,
- *     Columns.Severity,
- *     Columns.Remediation,
- *   ]}
- *   profiles={[
- *    {
- *      osMajorVersion: 9,
- *      osMinorVersion: 1,
- *      securityGuideId: 'XYZ-ABC',
- *      profileId: 'XYZ-ABC',
- *    },
- *    {
- *      osMajorVersion: 9,
- *      osMinorVersion: 2,
- *      securityGuideId: 'XYZ-ABC',
- *      profileId: 'XYZ-ABC',
- *    },
- *  ]}
- * />
- *
- *  // Will show tabs with rules from the security guide and the specified OS minor versions
- *  // and preselect rules with the IDs provided in preselected. The key can also be a tailorings ID
- *
- *  <Tailorings
- *   ouiaId="RHELVersions"
- *   columns={[
- *     Columns.Name,
- *     Columns.Severity,
- *     Columns.Remediation,
- *   ]}
- *   profiles={[
- *    {
- *      osMajorVersion: 9,
- *      osMinorVersion: 1,
- *      securityGuideId: 'XYZ-ABC',
- *      profileId: 'XYZ-ABC',
- *    },
- *    {
- *      osMajorVersion: 9,
- *      osMinorVersion: 2,
- *      securityGuideId: 'XYZ-ABC',
- *      profileId: 'XYZ-ABC',
- *    },
- *  ]}
- *  preselected={{
- *    "2": ['RULE_ID1', 'RULE_ID2']
- *    "1": ['RULE_ID11', 'RULE_ID5']
- *  }}
- * />
- *
- *
- */ const Tailorings = ({
+ */
+const Tailorings = ({
   policy,
   profiles,
   defaultTab,
@@ -170,6 +77,7 @@ import NoTailorings from './NoTailorings';
       ...profile,
       os_major_version: profile.osMajorVersion,
       os_minor_version: profile.osMinorVersion,
+      // TODO this cam be done smarter. We can pass the properties for the tab directly here
       isSecurityGuide: true,
     })) || []),
   ];
@@ -242,7 +150,7 @@ import NoTailorings from './NoTailorings';
                       preselected?.[tab.id] ||
                       preselected?.[tab.os_minor_version],
                     rulesPageLink: rulesPageLink,
-                    valueOverrides,
+                    ruleValues: valueOverrides,
                   }}
                 />
               </Tab>
@@ -258,8 +166,17 @@ import NoTailorings from './NoTailorings';
 
 Tailorings.propTypes = {
   columns: propTypes.arrayOf(propTypes.object),
-  policy: propTypes.object,
-  profiles: propTypes.array,
+  policy: propTypes.shape({
+    id: propTypes.string,
+  }),
+  profiles: propTypes.arrayOf(
+    propTypes.shape({
+      osMajorVersion: propTypes.string,
+      osMinorVersion: propTypes.string,
+      securityGuideId: propTypes.string,
+      profileId: propTypes.string,
+    })
+  ),
   defaultTab: propTypes.shape({
     id: propTypes.string,
     osMinorVersion: propTypes.string,

src/PresentationalComponents/Tailorings/components/TailoringTab.js

@@ -10,13 +10,46 @@ import { buildTreeTable, skips } from '../helpers';
 import TabHeader from './TabHeader';
 import SecurityGuideRulesToggle from './SecurityGuideRulesToggle';
 
+/**
+ * This component is used to show either the tailorings with rules of a specific policy,
+ * or the rules of a specific security guide and it's rules for a set of minor OS versions
+ *
+ *  @param   {object}             [props]                                React component props
+ *  @param   {object}             [props.policy]                         A policy object from the API
+ *  @param   {string}             [props.policy.id]                      The id used to fetch
+ *  @param   {object}             [props.tailoring]                      A tailoring object from the API
+ *  @param   {string}             [props.tailoring.id]                   A tailorings ID used to fetch the associated rules, rule groups, and value definitions for
+ *  @param   {string}             [props.securityGuideId]                The ID for a security guide that the profile should be queried with
+ *  @param   {string}             [props.profileId]                      The ID for a specific profile the rules should fetched for
+ *  @param   {string}             [props.osMajorVersion]                 A specific major OS version the profile should be queried with
+ *  @param   {string}             [props.osMinorVersion]                 A specific minor OS versions that the profile should be for
+ *  @param   {object}             [ props.ruleValues]                    An object to provide custom values for rules
+ *  @param   {Array}              [props.columns]                        A set of RulesTable columns the table should show
+ *  @param   {boolean}            [props.enableSecurityGuideRulesToggle] This enabled the "Selected Only" toggle to appear and allows fetching the security guide rule set for the matching profile
+ *  @param                        [props.systemCount]
+ *  @param                        [props.rulesPageLink]
+ *  @param   {object}             props.rulesTableProps                  React component props to be passed on to the RulesTable component in the tab
+ *  @param                        props.resetLink
+ *  @param   {Function}           [props.setRuleValues]                  A callback called when a custom rule value is saved
+ *  @param   {Function}           [props.onRuleValueReset]               A callback called when values for a rule are reset
+ *  @param   {Function}           [props.onValueOverrideSave]            **deprecated** We should be using setRuleValues instead
+ *  @param   {Function}           [props.onSelect]                       A callback called when a selection is made
+ *  @param   {object}             [props.preselected]                    An array of rule IDs to select
+ *
+ *  @returns {React.ReactElement}
+ *
+ *  @category Compliance
+ *  @tutorial how-to-use-tailorings
+ *
+ */
 const TailoringTab = ({
   policy,
   tailoring,
   securityGuideId: securityGuideIdProp,
   osMajorVersion,
   osMinorVersion,
   profileId,
+  ruleValues,
   columns,
   systemCount,
   rulesTableProps,
@@ -28,7 +61,6 @@ const TailoringTab = ({
   onSelect,
   preselected,
   enableSecurityGuideRulesToggle,
-  valueOverrides,
 }) => {
   const tableState = useFullTableState();
   const openRuleGroups = tableState?.tableState?.['open-items'];
@@ -144,14 +176,16 @@ const TailoringTab = ({
         columns={columns}
         setRuleValues={setRuleValues}
         // TODO Doublecheck if we should set default profile value_override values when creating a policy
+        // TODO in order to be clean this needs to change and we need to merge overrides passed in with the ones from tailoring
         ruleValues={tailoring?.value_overrides || {}}
         valueDefinitions={{
           data: valueDefinitions?.data,
           loading:
             shouldSkip.securityGuide.valueDefinitions === false &&
             valueDefinitions === undefined,
         }}
-        valueOverrides={valueOverrides}
+        // TODO follow up on above, this and everything related within the details row can go
+        valueOverrides={ruleValues}
         onRuleValueReset={onRuleValueReset}
         onValueOverrideSave={onValueSave}
         onSelect={onSelect ? onSelectRule : undefined}
@@ -172,26 +206,31 @@ const TailoringTab = ({
 };
 
 TailoringTab.propTypes = {
-  policy: propTypes.object,
-  tailoring: propTypes.object,
+  policy: propTypes.shape({
+    id: propTypes.string,
+  }),
+  tailoring: propTypes.shape({
+    id: propTypes.string,
+    profile_id: propTypes.string,
+    security_guide_id: propTypes.string,
+    value_overrides: propTypes.array,
+  }),
   securityGuideId: propTypes.string,
   profileId: propTypes.string,
   osMajorVersion: propTypes.string,
   osMinorVersion: propTypes.string,
+  ruleValues: propTypes.object,
   columns: propTypes.array,
   onSelect: propTypes.func,
   systemCount: propTypes.number,
-  selectedRuleRefIds: propTypes.array,
   rulesTableProps: propTypes.object,
   resetLink: propTypes.bool,
   rulesPageLink: propTypes.bool,
   setRuleValues: propTypes.func,
-  ruleValues: propTypes.array,
   onRuleValueReset: propTypes.func,
   onValueOverrideSave: propTypes.func,
   preselected: propTypes.object,
   enableSecurityGuideRulesToggle: propTypes.bool,
-  valueOverrides: propTypes.object,
 };
 
 const TailoringTabProvider = (props) => (