@carbon/ibm-products 2.2.0 → 2.3.0

package/es/components/EditFullPage/EditFullPage.docs-page.js

@@ -0,0 +1,39 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './EditFullPage.stories';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    altGuidelinesHref: "https://pages.github.ibm.com/cdai-design/pal/patterns/edit/usage#full-page-edit",
+    blocks: [{
+      description: "There are **2** components that make up a Create Full Page component, which can\nbe used in unison to create the desired look, or flow. Please note, to utilize\nthe Create Full Page component, you'll need to have a minimum of two steps. If\nyou are looking for a one step creation flow, consider Create Tearsheet, Create\nSide Panel, or Create Modal."
+    }, {
+      story: stories.editFullPage,
+      description: "This is used when you have one section per step. This can be created by passing\nin the overall `<CreateFullPage />` component and the `<CreateFullPageStep />`\ncomponent with form items as children:",
+      source: {
+        code: "<CreateFullPage {...props}>\n      <CreateFullPageStep\n          title=\"Required title\"\n          subtitle=\"Optional subtitle\"\n          description=\"Optional description\"\n          onNext={() => {'Optional function'}}\n          >\n          <Row>\n            <Column xlg={5} lg={5} md={4} sm={4}>\n              <TextInput\n                id=\"test-1\"\n                invalidText=\"A valid value is required\"\n                labelText=\"Topic name\"\n                placeholder=\"Enter topic name\"\n              />\n            </Column>\n          </Row>\n      </CreateFullPageStep>\n    </CreateFullPage>"
+      }
+    }, {
+      story: stories.editFullPageWithSections,
+      description: "This is used when you have several sections per step. This can be created by\npassing in the overall `<CreateFullPage />` component and the\n`<CreateFullPageStep />` component for the first `section`. All additional\n`sections` must be passed in as children, as shown below:",
+      source: {
+        code: "<CreateFullPageStep\n    title=\"Required title\"\n    subtitle=\"Optional subtitle\"\n    description=\"Optional description\"\n    onNext={() => {'Optional function'}}\n    >\n    <Row>\n      <Column xlg={5} lg={5} md={4} sm={4}>\n        <fieldset className={`#{$pkg-prefix}--create-full-page__step-fieldset`}>\n          <TextInput\n            id=\"test-1\"\n            invalidText=\"A valid value is required\"\n            labelText=\"Topic name\"\n            placeholder=\"Enter topic name\"\n          />\n        </fieldset>\n      </Column>\n    </Row>\n    <span className={`#{$pkg-prefix}--create-full-page__section-divider`} />\n    <h5 className={`#{$pkg-prefix}--create-full-page__step-title`}>Required title</h5>\n    <h6 className={`#{$pkg-prefix}--create-full-page__step-subtitle`}>\n      Optional subtitle\n    </h6>\n    <p className={`#{$pkg-prefix}--create-full-page__step-description`}>\n      Optional description\n    </p>\n    <Row>\n      <Column xlg={5} lg={5} md={4} sm={4}>\n        <fieldset className={`#{$pkg-prefix}--create-full-page__step-fieldset`}>\n          <TextInput\n            id=\"test-2\"\n            invalidText=\"A valid value is required\"\n            labelText=\"Topic name\"\n            placeholder=\"Enter topic name\"\n          />\n        </fieldset>\n      </Column>\n    </Row>\n</CreateFullPageStep>"
+      }
+    }, {
+      title: 'Using custom components',
+      description: "It is possible to use custom components that return `CreateFullPageStep`s in\norder to help reduce the amount of logic in the component that contains the main\n`CreateFullPage`. _It is required that each child of the `CreateFullPage` either\nbe a custom step or a `CreateFullPageStep`_. An example of this could look like\nthe following:",
+      source: {
+        code: "const CreateStepCustom = ({ subtitle, ...rest }) => {\n  return (\n    <CreateFullPageStep\n      {...rest}\n      subtitle={subtitle}\n      title=\"Step 1\"\n      onNext={() => console.log('optional validation check')}\n      onMount={() => console.log('optional onMount fn')}\n      disableSubmit={false}\n    >\n      step content here\n    </CreateFullPageStep>\n  );\n};\n\nconst CreateComponent = () => {\n  return (\n    <CreateFullPage {...createFullPageProps}>\n      <CreateStepCustom subtitle=\"Custom step subtitle\" />\n      <CreateFullPageStep\n        title=\"Topic name\"\n        fieldsetLegendText=\"Topic information\"\n        disableSubmit={!value}\n        subtitle=\"This is the unique name used to recognize your topic\"\n        description=\"It will also be used by your producers and consumers as part of the\n        connection information, so make it something easy to recognize.\"\n      >\n        Content for second step\n      </CreateFullPageStep>\n    </CreateFullPage>\n  );\n};"
+      }
+    }, {
+      title: 'Using dynamic steps',
+      description: "The use of dynamic steps can be utilized in a scenario when the user makes a\ncertain selection on one step that effects which steps will follow it, this is\ncontrolled via the `includeStep` prop. See abbreviated example below:",
+      source: {
+        code: "import { useState } from 'react';\n\nconst CreateFlow = () => {\n  const [shouldIncludeAdditionalStep, setShouldIncludeAdditionalStep] =\n    useState(false);\n  return (\n    <CreateFullPage {...createFullPageProps}>\n      <CreateFullPageStep {...step1Props}>\n        Step 1 content\n        <Checkbox\n          labelText={`Include additional step`}\n          id=\"include-additional-step-checkbox\"\n          onChange={(value) => setShouldIncludeAdditionalStep(value)}\n          checked={shouldIncludeAdditionalStep}\n        />\n      </CreateFullPageStep>\n      <CreateFullPageStep\n        {...step2Props}\n        includeStep={shouldIncludeAdditionalStep}\n      >\n        Dynamic step content\n      </CreateFullPageStep>\n      <CreateFullPageStep {...step3Props}>\n        Final step content\n      </CreateFullPageStep>\n    </CreateFullPage>\n  );\n};"
+      }
+    }, {
+      title: 'Class names',
+      description: "Additionally, to get the preferred styling when including your own children as\nsections, you can utilize the below included class names.\n\n| Class name                                           | Element     | Features                                                   |\n| ---------------------------------------------------- | ----------- | ---------------------------------------------------------- |\n| `#{$pkg-prefix}--create-full-page__step-title`       | title       | `productive-heading-04` & `margin-bottom` of `$spacing-05` |\n| `#{$pkg-prefix}--create-full-page__step-subtitle`    | subtitle    | `productive-heading-01` & `margin-bottom` of `$spacing-03` |\n| `#{$pkg-prefix}--create-full-page__step-description` | description | `body-long-01` & `margin-bottom` of `$spacing-06`          |\n| `#{$pkg-prefix}--create-full-page__step-fieldset`    | fieldset    | `margin-bottom` of `$spacing-05` to all children elements  |\n| `#{$pkg-prefix}--create-full-page__section-divider`  | divider     | Includes a `1px` divider line inside the `main` content    |\n"
+    }]
+  });
+};
+export default DocsPage;

package/es/components/EditFullPage/EditFullPage.js

@@ -41,7 +41,8 @@ var componentName = 'EditFullPage';
 // };
 
 /**
- * TODO: A description of the component.
+ * Use when settings on a page need to always be shown in edit mode, or when the context of the page is needed to make several changes.
+ * See usage guidance for further details.
  */
 export var EditFullPage = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var children = _ref.children,

package/es/components/EditSidePanel/EditSidePanel.js

@@ -38,7 +38,7 @@ var defaults = {
 };
 
 /**
- * TODO: A description of the component.
+ * Use with medium complexity edits if the user needs page context.
  */
 export var EditSidePanel = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var children = _ref.children,

package/es/components/EditTearsheet/EditTearsheet.docs-page.js

@@ -0,0 +1,25 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './EditTearsheet.stories';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    altGuidelinesHref: "https://pages.github.ibm.com/cdai-design/pal/patterns/edit/usage#tearsheet-edit",
+    blocks: [{
+      story: stories.multiFormEditTearsheet,
+      description: "This is used when you have one section per step. This can be created by passing\nin the overall `<EditTearsheet />` component and the `<EditTearsheetForm />`\ncomponent with form items as children:",
+      source: {
+        code: "<EditTearsheet {...props}>\n  <EditTearsheetForm\n    title=\"Required title\"\n    subtitle=\"Optional subtitle\"\n    description=\"Optional description\"\n    onNext={() => {\n      'Optional function';\n    }}\n  >\n    <TextInput\n      id=\"test-1\"\n      invalidText=\"A valid value is required\"\n      labelText=\"Topic name\"\n      placeholder=\"Enter topic name\"\n    />\n  </EditTearsheetForm>\n</EditTearsheet>"
+      }
+    }, {
+      title: 'Using custom components',
+      description: "It is possible to use custom components that return `EditTearsheetForms` in\norder to help reduce the amount of logic in the component that contains the main\n`EditTearsheet`. _It is required that each child of the `EditTearsheet` either\nbe a custom step or a `EditTearsheetForm`_. An example of this could look like\nthe following:",
+      source: {
+        code: "const CreateFormCustom = ({ subtitle, ...rest }) => {\n  return (\n    <EditTearsheetForm {...rest} subtitle={subtitle} title=\"Form 1\">\n      form content here\n    </EditTearsheetForm>\n  );\n};\n\nconst CreateComponent = () => {\n  return (\n    <EditTearsheet {...EditTearsheetProps}>\n      <CreateFormCustom subtitle=\"Custom form subtitle\" />\n      <EditTearsheetForm\n        title=\"Topic name\"\n        fieldsetLegendText=\"Topic information\"\n        subtitle=\"This is the unique name used to recognize your topic\"\n        description=\"It will also be used by your producers and consumers as part of the\n        connection information, so make it something easy to recognize.\"\n      >\n        Content for second form\n      </EditTearsheetForm>\n    </EditTearsheet>\n  );\n};"
+      }
+    }, {
+      title: "Class names",
+      description: "Additionally, to get the preferred styling when including your own children as\nsections, you can utilize the below included class names.\n\n| Class name                                            | Element     | Features                                                   |\n| ----------------------------------------------------- | ----------- | ---------------------------------------------------------- |\n| `#{$pkg-prefix}--create-tearsheet__form--title`       | title       | `productive-heading-04` & `margin-bottom` of `$spacing-05` |\n| `#{$pkg-prefix}--create-tearsheet__form--subtitle`    | subtitle    | `productive-heading-01` & `margin-bottom` of `$spacing-03` |\n| `#{$pkg-prefix}--create-tearsheet__form--description` | description | `body-long-01` & `margin-bottom` of `$spacing-06`          |\n| `#{$pkg-prefix}--create-tearsheet__form--fieldset`    | fieldset    | `margin-bottom` of `$spacing-05` to all children elements  |\n"
+    }]
+  });
+};
+export default DocsPage;

package/es/components/EditTearsheet/EditTearsheet.js

@@ -33,6 +33,10 @@ var defaults = {
   verticalPosition: 'normal',
   influencerWidth: 'narrow'
 };
+
+/**
+ * Use Tearsheet with medium to complex edits. See usage guidance for further information.
+ */
 export var EditTearsheet = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var cancelButtonText = _ref.cancelButtonText,
     children = _ref.children,

package/es/components/EditTearsheetNarrow/EditTearsheetNarrow.js

@@ -41,7 +41,7 @@ var componentName = 'EditTearsheetNarrow';
 // };
 
 /**
- * TODO: A description of the component.
+ * Use a narrow tearsheet as an alternative to a modal when there is scrolling. See usage guidance for further information.
  */
 export var EditTearsheetNarrow = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var children = _ref.children,

package/es/components/EditUpdateCards/EditUpdateCards.js

@@ -44,9 +44,10 @@ var componentName = 'EditUpdateCards';
 // };
 
 /**
- * TODO: A description of the component.
+ Editable cards allow a user to view, modify, and save the content contained within the card.
+ These cards are generally used in instances where a user needs to make changes to a resource instances
+ (ex. configuration details), account plan, etc. Editable cards allow a user to edit something within context.
  */
-
 export var EditUpdateCards = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var actionIcons = _ref.actionIcons,
     actionsPlacement = _ref.actionsPlacement,

package/es/components/EmptyStates/EmptyState.js

@@ -32,6 +32,10 @@ export var defaults = {
   position: 'top',
   size: 'lg'
 };
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var EmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/EmptyStates/ErrorEmptyState/ErrorEmptyState.js

@@ -27,6 +27,10 @@ import { defaults } from '../EmptyState';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--empty-state");
 var componentName = 'ErrorEmptyState';
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var ErrorEmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/EmptyStates/NoDataEmptyState/NoDataEmptyState.js

@@ -27,6 +27,10 @@ import { defaults } from '../EmptyState';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--empty-state");
 var componentName = 'NoDataEmptyState';
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var NoDataEmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/EmptyStates/NoTagsEmptyState/NoTagsEmptyState.js

@@ -27,6 +27,10 @@ import { defaults } from '../EmptyState';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--empty-state");
 var componentName = 'NoTagsEmptyState';
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var NoTagsEmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/EmptyStates/NotFoundEmptyState/NotFoundEmptyState.js

@@ -27,6 +27,10 @@ import { defaults } from '../EmptyState';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--empty-state");
 var componentName = 'NotFoundEmptyState';
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var NotFoundEmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/EmptyStates/NotificationsEmptyState/NotificationsEmptyState.js

@@ -27,6 +27,10 @@ import { defaults } from '../EmptyState';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--empty-state");
 var componentName = 'NotificationsEmptyState';
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var NotificationsEmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/EmptyStates/UnauthorizedEmptyState/UnauthorizedEmptyState.js

@@ -27,6 +27,10 @@ import { defaults } from '../EmptyState';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--empty-state");
 var componentName = 'UnauthorizedEmptyState';
+
+/**
+ * The `EmptyState` component follows the Carbon guidelines for empty states with some added specifications around illustration usage. For additional usage guidelines and documentation please refer to the links above.
+ */
 export var UnauthorizedEmptyState = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var action = _ref.action,
     className = _ref.className,

package/es/components/ExampleComponent/ExampleComponent.docs-page.js

@@ -0,0 +1,22 @@
+/**
+ * Copyright IBM Corp. 2023, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './ExampleComponent.stories';
+
+/**
+ * OPTIONAL: required only to customize default docs page
+ */
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    blocks: [{
+      description: 'Here it is in use.',
+      story: stories.exampleComponent
+    }]
+  });
+};
+export default DocsPage;

package/es/components/ExportModal/ExportModal.js

@@ -28,6 +28,10 @@ var defaults = {
   preformattedExtensions: Object.freeze([]),
   validExtensions: Object.freeze([])
 };
+
+/**
+ * Modal dialog version of the export pattern
+ */
 export var ExportModal = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var body = _ref.body,
     className = _ref.className,

package/es/components/HTTPErrors/HTTPError403/HTTPError403.js

@@ -22,6 +22,12 @@ import { pkg } from '../../../settings';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--http-errors");
 var componentName = 'HTTPError403';
+
+/**
+ * HTTP errors are used in an attempt to access something that isn’t available or
+the user doesn’t have permission for. This HTTPError component is generic so you
+can use it when you receive an error code that isn't provided.
+ */
 export var HTTPError403 = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var className = _ref.className,
     description = _ref.description,

package/es/components/HTTPErrors/HTTPError404/HTTPError404.js

@@ -22,6 +22,12 @@ import { pkg } from '../../../settings';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--http-errors");
 var componentName = 'HTTPError404';
+
+/**
+ * HTTP errors are used in an attempt to access something that isn’t available or
+the user doesn’t have permission for. This HTTPError component is generic so you
+can use it when you receive an error code that isn't provided.
+ */
 export var HTTPError404 = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var className = _ref.className,
     description = _ref.description,

package/es/components/HTTPErrors/HTTPErrorOther/HTTPErrorOther.js

@@ -22,6 +22,12 @@ import { pkg } from '../../../settings';
 // The block part of our conventional BEM class names (blockClass__E--M).
 var blockClass = "".concat(pkg.prefix, "--http-errors");
 var componentName = 'HTTPErrorOther';
+
+/**
+ * HTTP errors are used in an attempt to access something that isn’t available or
+the user doesn’t have permission for. This HTTPError component is generic so you
+can use it when you receive an error code that isn't provided.
+ */
 export var HTTPErrorOther = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var className = _ref.className,
     description = _ref.description,

package/es/components/ImportModal/ImportModal.docs-page.js

@@ -0,0 +1,18 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import { useOf } from '@storybook/blocks';
+import { storyDocsGuidelines } from '../../global/js/utils/story-helper';
+var DocsPage = function DocsPage() {
+  var _useOf = useOf('meta', ['meta']),
+    csfFile = _useOf.csfFile;
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    altGuidelinesHref: [storyDocsGuidelines(csfFile), {
+      href: 'https://www.carbondesignsystem.com/components/modal/usage',
+      label: 'Carbon Modal usage guidelines'
+    }, {
+      href: 'https://react.carbondesignsystem.com/?path=/docs/modal--default',
+      label: 'Carbon Modal documentation'
+    }]
+  });
+};
+export default DocsPage;

package/es/components/ImportModal/ImportModal.js

@@ -179,6 +179,13 @@ export var ImportModal = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var inputHandler = function inputHandler(evt) {
     setImportUrl(evt.target.value);
   };
+  var onCloseHandler = function onCloseHandler() {
+    setFiles([]);
+    setImportUrl('');
+    if (onClose) {
+      onClose();
+    }
+  };
   var numberOfFiles = files.length;
   var numberOfValidFiles = files.filter(function (f) {
     return !f.invalid;
@@ -190,13 +197,13 @@ export var ImportModal = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var blockClass = "".concat(pkg.prefix, "--import-modal");
   return /*#__PURE__*/React.createElement(ComposedModal, _extends({}, rest, _objectSpread({
     open: open,
-    ref: ref,
-    onClose: onClose
+    ref: ref
   }, getDevtoolsProps(componentName)), {
     "aria-label": title,
     className: cx(blockClass, className),
     size: "sm",
-    preventCloseOnClickOutside: true
+    preventCloseOnClickOutside: true,
+    onClose: onCloseHandler
   }), /*#__PURE__*/React.createElement(ModalHeader, {
     className: "".concat(blockClass, "__header"),
     title: title
@@ -259,7 +266,7 @@ export var ImportModal = /*#__PURE__*/forwardRef(function (_ref, ref) {
   }, /*#__PURE__*/React.createElement(Button, {
     type: "button",
     kind: "secondary",
-    onClick: onClose
+    onClick: onCloseHandler
   }, secondaryButtonText), /*#__PURE__*/React.createElement(Button, {
     type: "submit",
     kind: "primary",
@@ -362,11 +369,11 @@ ImportModal.propTypes = {
   /**
    * Specify a handler for "submitting" modal. Access the imported file via `file => {}`
    */
-  onRequestSubmit: PropTypes.func,
+  onRequestSubmit: PropTypes.func.isRequired,
   /**
    * Specify whether the Modal is currently open
    */
-  open: PropTypes.bool,
+  open: PropTypes.bool.isRequired,
   /**
    * Specify the text for the primary button
    */

package/es/components/MultiAddSelect/MultiAddSelect.docs-page.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    altGuidelinesHref: "https://pages.github.ibm.com/cdai-design/pal/patterns/add-and-select/usage",
+    blocks: [{
+      title: 'Structuring items',
+      description: "The `items` object has a lot of customization potential and can greatly effect\nthe way the component is displayed and how you interact with it.\n\nLet's walk through an example.",
+      source: {
+        code: "items: {\n  modifiers: { // adds a modifier dropdown inside the items\n    label: PropTypes.string, // label for the dropdown\n    options: PropTypes.array, // list of options / values for the dropdown\n  },\n  sortBy: ['title'], // designates which properties should be used to sort the column when using a hierarchy\n  entries: [ // the actual list of items / entries\n    {\n      id: '1', // required unique id for the entry\n      value: '1', // required value of the entry\n      title: 'item 1', // required title to display\n      subtitle: 'item 1 subtitle', // subtitle to display\n      children: { // designates if entry has children. if the children prop is found a hierarchy list will be used\n        sortBy: ['title', 'size'],\n        filterBy: 'fileType', // designates which property should be used to filter the column of items\n        entries: [\n          {\n            id: '1-1',\n            value: 'file1.pdf',\n            title: 'file1.pdf',\n            fileType: 'pdf',\n            size: '100',\n            icon: Document16, // designates if an icon should be displayed. While similar to avatar icon, both have different displays.\n            tag: 'business',\n            avatar: { // designates if an avatar should be displayed\n              alt: 'alt text',\n              icon: <Icon />,\n              src: 'avatar.png',\n            },\n          },\n        ],\n      },\n    },\n  ],\n}"
+      }
+    }, {
+      description: "The properties that have been commented on like `id`, `value`, and `icon` have\nspecific use within the component and are generally required. Other properties\nlike `fileType` and `size` do not and will simply show up as details in the\nsidebar when selected."
+    }]
+  });
+};
+export default DocsPage;

package/es/components/MultiAddSelect/MultiAddSelect.js

@@ -12,6 +12,10 @@ import { AddSelect } from '../AddSelect';
 import { getDevtoolsProps } from '../../global/js/utils/devtools';
 import { pkg } from '../../settings';
 var componentName = 'MultiAddSelect';
+
+/**
+ * Used to add or select multiple or more items from larger lists or hierarchies.
+ */
 export var MultiAddSelect = /*#__PURE__*/forwardRef(function (props, ref) {
   return /*#__PURE__*/React.createElement(AddSelect, _extends({}, props, {
     multi: true,

package/es/components/NotificationsPanel/preview-components/UnreadNotificationBell.js

@@ -15,34 +15,19 @@ var UnreadNotificationBell = function UnreadNotificationBell() {
     xmlns: "http://www.w3.org/2000/svg",
     xmlnsXlink: "http://www.w3.org/1999/xlink"
   }, /*#__PURE__*/React.createElement("title", null, "Unread notification bell"), /*#__PURE__*/React.createElement("g", {
-    id: "Page-1",
-    stroke: "none",
-    strokeWidth: "1",
-    fill: "none",
-    fillRule: "evenodd"
-  }, /*#__PURE__*/React.createElement("g", {
     id: "Group",
     transform: "translate(-1.000000, 0.000000)"
-  }, /*#__PURE__*/React.createElement("g", {
-    id: "notification"
   }, /*#__PURE__*/React.createElement("path", {
     d: "M17.9419375,12.058125 L16.25,10.3661875 L16.25,8.125 C16.245845,4.91692673 13.816599,2.23147626 10.625,1.90675 L10.625,0.625 L9.375,0.625 L9.375,1.90675 C6.183401,2.23147626 3.754155,4.91692673 3.75,8.125 L3.75,10.3661875 L2.0580625,12.058125 C1.94086706,12.1753182 1.875,12.3342622 1.875,12.5 L1.875,14.375 C1.875,14.720178 2.15482203,15 2.5,15 L6.875,15 L6.875,15.4855 C6.84694527,17.1272367 8.05869477,18.5271305 9.6875,18.7346875 C10.5660567,18.8218694 11.4405518,18.5337871 12.0952737,17.9415019 C12.7499955,17.3492167 13.1239886,16.5078712 13.125,15.625 L13.125,15 L17.5,15 C17.845178,15 18.125,14.720178 18.125,14.375 L18.125,12.5 C18.125,12.3342622 18.0591329,12.1753182 17.9419375,12.058125 Z M11.875,15.625 C11.875,16.6605339 11.0355339,17.5 10,17.5 C8.96446609,17.5 8.125,16.6605339 8.125,15.625 L8.125,15 L11.875,15 L11.875,15.625 Z M16.875,13.75 L3.125,13.75 L3.125,12.7588125 L4.816875,11.066875 C4.93409336,10.949692 4.9999646,10.7907468 5,10.625 L5,8.125 C5,5.36357625 7.23857625,3.125 10,3.125 C12.7614237,3.125 15,5.36357625 15,8.125 L15,10.625 C15.0000354,10.7907468 15.0659066,10.949692 15.183125,11.066875 L16.875,12.7588125 L16.875,13.75 Z",
     id: "Shape",
-    fill: "#FFFFFF",
     fillRule: "nonzero"
-  }), /*#__PURE__*/React.createElement("rect", {
-    id: "_Transparent_Rectangle_",
-    x: "0",
-    y: "0",
-    width: "20",
-    height: "20"
-  })), /*#__PURE__*/React.createElement("circle", {
+  }), /*#__PURE__*/React.createElement("circle", {
     id: "Oval",
     stroke: "#161616",
     fill: "#DA1E28",
     cx: "15",
     cy: "4.375",
     r: "2.5"
-  }))));
+  })));
 };
 export { UnreadNotificationBell };

package/es/components/PageHeader/PageHeader.js

@@ -314,12 +314,8 @@ export var PageHeader = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
       utilSetCollapsed(collapseHeader, metrics.headerOffset, metrics.headerTopValue);
     }
   }, [collapseHeader, metrics.headerOffset, metrics.headerTopValue]);
-  useResizeObserver(sizingContainerRef, {
-    callback: handleResizeActionBarColumn
-  });
-  useResizeObserver(headerRef, {
-    callback: handleResize
-  });
+  useResizeObserver(sizingContainerRef, handleResizeActionBarColumn);
+  useResizeObserver(headerRef, handleResize);
 
   // Determine what form of title to display in the breadcrumb
   var breadcrumbItemForTitle = utilGetBreadcrumbItemForTitle(blockClass, collapseTitle, title);

package/es/components/PageHeader/PageHeaderUtils.js

@@ -65,11 +65,11 @@ export var utilCheckUpdateVerticalSpace = function utilCheckUpdateVerticalSpace(
     var scrollableContainer = scrollableAncestor(headerRef.current);
 
     /* istanbul ignore next */
-    var scrollableContainerTop = scrollableContainer ? scrollableContainer.scrollTop - scrollableContainer.offsetTop : 0;
+    var scrollableContainerTop = scrollableContainer ? scrollableContainer.scrollTop - scrollableContainer.getBoundingClientRect().top : 0;
 
     // The header offset calculation is either going to work out at 0 if we have no gap between scrolling container
     // top and the measuring ref top, or the difference between. It does not change on scroll or resize.
-    update.headerOffset = scrollableContainerTop + offsetTopMeasuringRef.current.getBoundingClientRect().top;
+    update.headerOffset = (offsetTopMeasuringRef.current ? offsetTopMeasuringRef.current.getBoundingClientRect().top : 0) + scrollableContainerTop;
 
     /* istanbul ignore next */
     update.breadcrumbRowHeight = breadcrumbRowEl ? breadcrumbRowEl.clientHeight : 0;

package/es/components/RemoveModal/RemoveModal.docs-page.js

@@ -0,0 +1,18 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import { useOf } from '@storybook/blocks';
+import { storyDocsGuidelines } from '../../global/js/utils/story-helper';
+var DocsPage = function DocsPage() {
+  var _useOf = useOf('meta', ['meta']),
+    csfFile = _useOf.csfFile;
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    altGuidelinesHref: [storyDocsGuidelines(csfFile), {
+      href: 'https://www.carbondesignsystem.com/components/modal/usage',
+      label: 'Carbon Modal usage guidelines'
+    }, {
+      href: 'https://react.carbondesignsystem.com/?path=/docs/modal--default',
+      label: 'Carbon Modal documentation'
+    }]
+  });
+};
+export default DocsPage;

package/es/components/RemoveModal/RemoveModal.js

@@ -21,6 +21,12 @@ import uuidv4 from '../../global/js/utils/uuidv4';
 import { pkg } from '../../settings';
 import { usePreviousValue } from '../../global/js/hooks';
 var componentName = 'RemoveModal';
+
+/**
+The `RemoveModal` covers what is known as high impact and medium impact deleting.
+Enabling `textConfirmation` enables what would be considered the high impact state of the modal.
+For additional information on differentiating between delete / remove and low / medium / high impact please refer to the usage guidelines.
+ */
 export var RemoveModal = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var body = _ref.body,
     className = _ref.className,

package/es/components/SidePanel/SidePanel.js

@@ -444,9 +444,7 @@ export var SidePanel = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
     }, title));
   };
   var contentRef = ref || sidePanelRef;
-  useResizeObserver(contentRef, {
-    callback: handleResize
-  });
+  useResizeObserver(contentRef, handleResize);
   return /*#__PURE__*/React.createElement(AnimatePresence, null, open && /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement(motion.div, _extends({}, getDevtoolsProps(componentName), rest, {
     id: "".concat(blockClass, "-outer"),
     className: mainPanelClassNames,

package/es/components/SingleAddSelect/SingleAddSelect.docs-page.js

@@ -0,0 +1,15 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    altGuidelinesHref: "https://pages.github.ibm.com/cdai-design/pal/patterns/add-and-select/usage",
+    blocks: [{
+      title: 'Structuring items',
+      description: "The `items` object has a lot of customization potential and can greatly effect\nthe way the component is displayed and how you interact with it..\n\nLet's walk through an example.",
+      source: {
+        code: "items: {\n  entries: [ // the actual list of items / entries\n    {\n      id: '1', // required unique id for the entry\n      value: '1', // required value of the entry\n      title: 'item 1', // required title to display\n      subtitle: 'item 1 subtitle', // subtitle to display\n      children: { // designates if entry has children. if the children prop is found a hierarchy list will be used\n        entries: [\n          {\n            id: '1-1',\n            value: 'file1.pdf',\n            title: 'file1.pdf',\n          },\n        ],\n      },\n    },\n  ],\n}"
+      }
+    }]
+  });
+};
+export default DocsPage;

package/es/components/SingleAddSelect/SingleAddSelect.js

@@ -13,6 +13,10 @@ import { getDevtoolsProps } from '../../global/js/utils/devtools';
 import { pkg } from '../../settings';
 import { prepareProps } from '../../global/js/utils/props-helper';
 var componentName = 'SingleAddSelect';
+
+/**
+ * Used to add or select one or more items from larger lists or hierarchies.
+ */
 export var SingleAddSelect = /*#__PURE__*/forwardRef(function (props, ref) {
   // remove multi add select specific props
   var validProps = prepareProps(props, ['columnInputPlaceholder', 'globalFilters', 'globalFiltersIconDescription', 'globalFiltersPlaceholderText', 'globalFiltersPrimaryButtonText', 'globalFiltersSecondaryButtonText', 'influencerTitle', 'multi', 'noSelectionDescription', 'noSelectionTitle', 'removeIconDescription']);

package/es/components/StatusIcon/StatusIcon.docs-page.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './StatusIcon.stories';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    blocks: [{
+      story: stories.Default
+    }, {
+      title: 'Accessibility',
+      description: "The `StatusIcon` component follows the Carbon guidelines for status icons with\nsome added specifications around illustration usage. For additional usage\nguidelines and documentation please refer to the links above.\n\n_Status icons_ are an important method of communicating severity level\ninformation to users. The shapes and colors, communicate severity that enable\nusers to quickly assess and identify status and respond accordingly."
+    }, {
+      title: 'Sizing',
+      description: "\n| Size    | Pixels  |\n| ------- | ------- |\n| small   | 16 x 16 |\n| medium  | 20 x 20 |\n| large   | 24 x 24 |\n| x-large | 32 x 32 |\n          "
+    }]
+  });
+};
+export default DocsPage;

package/es/components/StatusIcon/StatusIcon.js

@@ -16,6 +16,16 @@ import { getDevtoolsProps } from '../../global/js/utils/devtools';
 import { pkg } from '../../settings';
 var blockClass = "".concat(pkg.prefix, "--status-icon");
 var componentName = 'StatusIcon';
+
+/**
+The `StatusIcon` component follows the Carbon guidelines for status icons with
+some added specifications around illustration usage. For additional usage
+guidelines and documentation please refer to the links above.
+
+_Status icons_ are an important method of communicating severity level
+information to users. The shapes and colors, communicate severity that enable
+users to quickly assess and identify status and respond accordingly.
+ */
 export var StatusIcon = /*#__PURE__*/forwardRef(function (_ref, ref) {
   var _icons$kind;
   var kind = _ref.kind,

package/es/components/TagSet/TagSet.js

@@ -156,7 +156,8 @@ export var TagSet = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
     if (sizingTags.length > 0) {
       var spaceAvailable = tagSetRef.current.offsetWidth;
       for (var i in sizingTags) {
-        var tagWidth = sizingTags[i].offsetWidth;
+        var _sizingTags$i;
+        var tagWidth = ((_sizingTags$i = sizingTags[i]) === null || _sizingTags$i === void 0 ? void 0 : _sizingTags$i.offsetWidth) || 0;
         if (spaceAvailable >= tagWidth) {
           spaceAvailable -= tagWidth;
           willFit += 1;
@@ -198,12 +199,8 @@ export var TagSet = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var handleModalClose = function handleModalClose() {
     setShowAllModalOpen(false);
   };
-  useResizeObserver(sizingContainerRef, {
-    callback: handleSizerTagsResize
-  });
-  useResizeObserver(tagSetRef, {
-    callback: handleResize
-  });
+  useResizeObserver(sizingContainerRef, handleSizerTagsResize);
+  useResizeObserver(tagSetRef, handleResize);
   return /*#__PURE__*/React.createElement("div", _extends({}, rest, {
     className: cx([blockClass, className]),
     ref: tagSetRef