@carbon/ibm-products 2.1.2 → 2.1.3

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/Tearsheet/TearsheetShell.js

@@ -55,7 +55,13 @@ export var tearsheetHasCloseIcon = function tearsheetHasCloseIcon(actions, hasCl
   return hasCloseIcon !== null && hasCloseIcon !== void 0 ? hasCloseIcon : tearsheetIsPassive(actions);
 };
 
-// TearSheetShell is used internally by TearSheet and TearSheetNarrow
+/**
+ *  TearSheetShell is used internally by TearSheet and TearSheetNarrow
+ *
+ * The component is not public.
+ *
+ * See the canvas tab for the component API details.
+ * */
 export var TearsheetShell = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var actions = _ref.actions,
     children = _ref.children,

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

@@ -0,0 +1,14 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './Toolbar.stories';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    blocks: [{
+      story: stories._Toolbar
+    }, {
+      story: stories.vertical,
+      description: "A toolbar orientation for floating the toolbar on the canvas."
+    }]
+  });
+};
+export default DocsPage;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './UserProfileImage.stories';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    blocks: [{
+      story: stories.Default
+    }, {
+      story: stories.WithGroupIcon,
+      description: "By passing in icon prop with a value of `group`, the avatar will display the group icon"
+    }, {
+      story: stories.WithInitials,
+      description: "When passing a display name to the component, the display name will be distilled down to the first and last initials of the display name. `Thomas Watson` and `Thomas J. Watson` will both display `TW` as the initials."
+    }]
+  });
+};
+export default DocsPage;

package/es/components/UserProfileImage/UserProfileImage.js

@@ -33,7 +33,7 @@ var defaults = {
   tooltipAlignment: 'bottom'
 };
 /**
- * This is a user profile image component which displays an image, or initials or icon for a user.
+ * The user profile avatar allows for an image of the user to be displayed by passing in the image prop. By default the component will display a user icon on a blue background.
  */
 export var UserProfileImage = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var backgroundColor = _ref.backgroundColor,

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

@@ -0,0 +1,52 @@
+import React from 'react';
+import { StoryDocsPage } from '../../global/js/utils/StoryDocsPage';
+import * as stories from './WebTerminal.stories';
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/React.createElement(StoryDocsPage, {
+    blocks: [{
+      description: "To get started using the WebTerminal, you have to first wrap your\n              application with the `<WebTerminalProvider>`\n              component. This will allow all the WebTerminal components to be\n              used with the `useWebTerminal()` custom hook.\n          ",
+      title: 'Getting Started',
+      source: {
+        code: "import { WebTerminalProvider } from '@carbon/ibm-products';\n\nconst App = () => {\n  return (\n    <WebTerminalProvider>\n      ...\n    <WebTerminalProvider>\n  )\n};"
+      }
+    }, {
+      title: 'useWebTerminal()',
+      source: {
+        code: "const { open, openWebTerminal, closeWebTerminal, toggleWebTerminal } =\n  useWebTerminal();"
+      }
+    }, {
+      description: "The `useWebTerminal()` hook returns an object with 4 properties:\n1. Read the `open` state (true or false)\n2. `openWebTerminal` sets the `open` state to true\n3. `closeWebTerminal` sets the `open` state to false\n4. `toggleWebTerminal` toggles between true and false\n\nExample:\n",
+      source: {
+        code: "const MyComponent = () => {\n  const { open, openWebTerminal, closeWebTerminal, toggleWebTerminal } =\n    useWebTerminal();\n\n  return (\n    <div>\n      <button onClick={() => openWebTerminal()}>Open web terminal</button>\n      <button onClick={() => closeWebTerminal()}>Close web terminal</button>\n      <button onClick={() => toggleWebTerminal()}>Toggle web terminal</button>\n      <p>The web terminal is now {open}</p>\n\n      <WebTerminal>...</WebTerminal>\n    </div>\n  );\n};"
+      }
+    }, {
+      subTitle: 'Passing in your own terminal.',
+      description: "The `WebTerminal` is wrapper component for your own\nterminal component that you may have been using for your product.\nSimply pass your own terminal component as children.\n            "
+    }, {
+      subTitle: 'Optional wrapper component.',
+      description: "Optionally you can import `WebTerminalContentWrapper` to have\n              content adjust their width based off the `WebTerminal` width when\n              it is opened.",
+      source: {
+        code: "<WebTerminalContentWrapper>\n  content\n</WebTerminalContentWrapper>\n\n<WebTerminal>\n  ...\n</WebTerminal>"
+      }
+    }, {
+      description: 'The default web terminal is one which opens and the terminal loads. Then if the user desires to dismiss it they can click the close icon on the top right corner of the component.',
+      story: stories.Default
+    }, {
+      story: stories.WithDocumentationLinks
+    }, {
+      subTitle: 'Help users with helpful documentation links',
+      description: "Optionally you can pass documentation links to help point your users to useful\ndocumentation for your terminal, or kubernetes commands etc.\n\nThe documentation links should reflect the same props as `OverflowMenuItem` from\ncarbon.\n\nLearn more:\nhttps://react.carbondesignsystem.com/?path=/docs/components-overflowmenu--default\n",
+      source: {
+        code: "const documentationLinks = [\n  {\n    itemText: 'BX/ICP docs',\n    href: '#',\n    onClick: () => console.log('clicked'),\n  },\n  {\n    itemText: 'Kubernetes docs',\n    href: '#',\n    onClick: () => console.log('clicked'),\n  },\n  {\n    itemText: 'Docker docs',\n    href: '#',\n    onClick: () => console.log('clicked'),\n  },\n  {\n    itemText: 'Helm docs',\n    href: '#',\n    onClick: () => console.log('clicked'),\n  },\n];"
+      }
+    }, {
+      story: stories.WithActions
+    }, {
+      description: "Optionally you can add actions to the web terminal header bar. To add actions\nyou need to pass in an array of actions with objects for each object.",
+      source: {
+        code: "<WebTerminal\n  actions={[\n    {\n      renderIcon: Code32,\n      onClick: () => {},\n      iconDescription: 'Create new deployment',\n    },\n  ]}\n>\n  ...\n</WebTerminal>"
+      }
+    }]
+  });
+};
+export default DocsPage;

package/es/components/WebTerminal/WebTerminal.js

@@ -39,6 +39,10 @@ var defaults = {
   documentationLinksIconDescription: 'Show documentation links',
   isInitiallyOpen: false
 };
+
+/**
+ * The `WebTerminal` is prompted by the user and is persistent until dismissed. The purpose of a web terminal is to provide users with the ability to type commands manually instead of using the GUI.
+ */
 export var WebTerminal = /*#__PURE__*/React.forwardRef(function (_ref, ref) {
   var _ref3;
   var _ref$actions = _ref.actions,

package/es/global/js/utils/StoryDocsPage.js

@@ -0,0 +1,218 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
+/**
+ * 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 PropTypes from 'prop-types';
+import { Title, Description, Source, Controls, Canvas, Stories, AnchorMdx, useOf } from '@storybook/blocks';
+import { paramCase } from 'change-case';
+import { codeSandboxHref, stackblitzHref, storyDocsPageInfo } from './story-helper';
+export var CustomBlocks = function CustomBlocks(_ref) {
+  var blocks = _ref.blocks;
+  return blocks.map(function (block, index) {
+    var source = _objectSpread({}, block === null || block === void 0 ? void 0 : block.source);
+    if (source.code && !source.language) {
+      source.language = 'jsx';
+    }
+    return /*#__PURE__*/React.createElement("div", {
+      key: "block-index--".concat(index)
+    }, block.title && /*#__PURE__*/React.createElement("h3", {
+      id: paramCase(block.title)
+    }, block.title), block.subTitle && /*#__PURE__*/React.createElement("h4", null, block.subTitle), block.description && typeof block.description === 'string' ? /*#__PURE__*/React.createElement(Description, null, block.description) : block.description, block.story && /*#__PURE__*/React.createElement(Canvas, {
+      of: block.story
+    }), block.source && /*#__PURE__*/React.createElement(Source, source));
+  });
+};
+
+/**
+ * This function checks blocks against stories and then
+ * - Adds title if no alternative is supplied
+ * - Adds blocks for unreferenced stories if omitUnreferencedStories is false
+ */
+var processBlocks = function processBlocks(blocks, stories, omitUnreferencedStories) {
+  var blocksWithStoryTitles = blocks ? _toConsumableArray(blocks) : [];
+  var restOfStories = [];
+  var storyKeys = Object.keys(stories);
+  storyKeys.forEach(function (sk) {
+    var story = stories[sk].moduleExport;
+    var storyName = stories[sk].name;
+    var matchingBlock = blocksWithStoryTitles.find(function (block) {
+      return block.story === story;
+    });
+    if (matchingBlock) {
+      var _matchingBlock$title;
+      matchingBlock.title = (_matchingBlock$title = matchingBlock.title) !== null && _matchingBlock$title !== void 0 ? _matchingBlock$title : storyName;
+    } else if (!omitUnreferencedStories) {
+      restOfStories.push({
+        story: story,
+        title: storyName
+      });
+    }
+  });
+  if (!omitUnreferencedStories) {
+    return blocksWithStoryTitles.concat(restOfStories);
+  }
+  return blocksWithStoryTitles;
+};
+
+/**
+ * Calling with no parameters will produce the default output.
+ * Customize by providing alternative values and/or blocks defining sections
+ * @param {*} param0
+ * @returns
+ */
+export var StoryDocsPage = function StoryDocsPage(_ref2) {
+  var _csfFile$meta, _csfFile$meta$paramet, _processedBlocks$filt;
+  var altTitle = _ref2.altTitle,
+    altDescription = _ref2.altDescription,
+    altGuidelinesHref = _ref2.altGuidelinesHref,
+    blocks = _ref2.blocks,
+    omitCodedExample = _ref2.omitCodedExample,
+    omitUnreferencedStories = _ref2.omitUnreferencedStories;
+  var _useOf = useOf('meta', ['meta']),
+    csfFile = _useOf.csfFile;
+  var storyInfo = storyDocsPageInfo(csfFile);
+  var guidelinesHref = altGuidelinesHref !== null && altGuidelinesHref !== void 0 ? altGuidelinesHref : storyInfo.guidelinesHref;
+  var isFullScreen = (csfFile === null || csfFile === void 0 ? void 0 : (_csfFile$meta = csfFile.meta) === null || _csfFile$meta === void 0 ? void 0 : (_csfFile$meta$paramet = _csfFile$meta.parameters) === null || _csfFile$meta$paramet === void 0 ? void 0 : _csfFile$meta$paramet.layout) === 'fullscreen' || false;
+  var storyHelperClass = isFullScreen ? 'c4p--story-docs-page--fullscreen' : '';
+  var processedBlocks = processBlocks(blocks, csfFile.stories, omitUnreferencedStories);
+  console.log(processBlocks);
+  var storyCount = (_processedBlocks$filt = processedBlocks === null || processedBlocks === void 0 ? void 0 : processedBlocks.filter(function (block) {
+    return !!block.story;
+  }).length) !== null && _processedBlocks$filt !== void 0 ? _processedBlocks$filt : 0;
+  return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement(Title, null, altTitle !== null && altTitle !== void 0 ? altTitle : storyInfo.title), guidelinesHref ? guidelinesHref && Array.isArray(guidelinesHref) ? guidelinesHref.map(function (_ref3, index) {
+    var href = _ref3.href,
+      label = _ref3.label;
+    return /*#__PURE__*/React.createElement(React.Fragment, null, index > 0 && ' | ', /*#__PURE__*/React.createElement(AnchorMdx, {
+      key: href,
+      href: href
+    }, label));
+  }) : /*#__PURE__*/React.createElement(AnchorMdx, {
+    href: guidelinesHref
+  }, altTitle ? "".concat(altTitle, " usage guidelines") : storyInfo.guidelinesLinkLabel) : null, /*#__PURE__*/React.createElement("h2", {
+    style: {
+      marginTop: guidelinesHref ? '16px' : ''
+    }
+  }, "Table of contents"), /*#__PURE__*/React.createElement("ul", null, ['Overview', 'Coded examples', 'Example usage', 'Component API'].map(function (item) {
+    return /*#__PURE__*/React.createElement("li", {
+      key: item
+    }, /*#__PURE__*/React.createElement(AnchorMdx, {
+      href: "#".concat(paramCase(item))
+    }, item), processedBlocks && item === 'Example usage' ? /*#__PURE__*/React.createElement("ul", null, processedBlocks.map(function (block) {
+      return block !== null && block !== void 0 && block.title ? /*#__PURE__*/React.createElement("li", {
+        key: block.title
+      }, /*#__PURE__*/React.createElement(AnchorMdx, {
+        href: "#".concat(paramCase(block.title))
+      }, block.title)) : null;
+    })) : null);
+  })), /*#__PURE__*/React.createElement("h2", {
+    id: "overview"
+  }, "Overview"), /*#__PURE__*/React.createElement(Description, null, altDescription), !omitCodedExample && storyInfo.expectCodedExample ? /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("h2", {
+    id: "coded-examples"
+  }, "Coded examples"), /*#__PURE__*/React.createElement("p", null, "Coded examples can be edited and are a great way to try out a component."), /*#__PURE__*/React.createElement("ul", null, /*#__PURE__*/React.createElement("li", {
+    key: "codesandbox"
+  }, /*#__PURE__*/React.createElement(AnchorMdx, {
+    href: codeSandboxHref(storyInfo.title)
+  }, /*#__PURE__*/React.createElement("svg", {
+    viewBox: "0 0 24 24",
+    xmlns: "http://www.w3.org/2000/svg",
+    style: {
+      height: '16px',
+      width: '16px',
+      color: 'black',
+      boxShadow: '0 0 0 2px white',
+      marginRight: '8px',
+      verticalAlign: '-2px'
+    }
+  }, /*#__PURE__*/React.createElement("path", {
+    fillRule: "evenodd",
+    clipRule: "evenodd",
+    d: "M0 0h23.987v24H0V0Zm21.533 2.455v19.09H2.453V2.456h19.08Z",
+    fill: "currentColor"
+  })), "CodeSandbox")), /*#__PURE__*/React.createElement("li", {
+    key: "stackblitz"
+  }, /*#__PURE__*/React.createElement(AnchorMdx, {
+    href: stackblitzHref(storyInfo.title)
+  }, /*#__PURE__*/React.createElement("img", {
+    src: "https://c.staticblitz.com/assets/favicon_sb-861fe1b85c0dc928750c62de15fed96fc75e57ee366bd937bad17a3938917b3f.svg",
+    alt: "Stackblitz logo",
+    style: {
+      verticalAlign: '-2px',
+      marginRight: '8px'
+    }
+  }), "Stackblitz")))) : null, /*#__PURE__*/React.createElement("h2", {
+    id: "example-usage"
+  }, "Example usage"), /*#__PURE__*/React.createElement("div", {
+    className: storyHelperClass
+  }, processedBlocks ? /*#__PURE__*/React.createElement(CustomBlocks, {
+    blocks: processedBlocks
+  }) : /*#__PURE__*/React.createElement(Stories, null)), /*#__PURE__*/React.createElement("h2", {
+    id: "component-api"
+  }, "Component API"), storyCount > 1 && /*#__PURE__*/React.createElement("p", null, "NOTE: Changing the controls below affects the default/primary example shown on the docs page."), /*#__PURE__*/React.createElement(Controls, null));
+};
+StoryDocsPage.propTypes = {
+  /**
+   * Uses doc block from the component where possible.
+   *
+   * Note: use `export default { component: ExampleComponent }` in the story if the main component is wrapped by some
+   * additional code. This will allow the doc block to pass through.
+   *
+   * If passed as string treated as markdown.
+   */
+  altDescription: PropTypes.node,
+  /**
+   * location if any of guidelines on the PAL site, constructed by default
+   */
+  altGuidelinesHref: PropTypes.oneOfType(PropTypes.string, PropTypes.arrayOf(PropTypes.shape({
+    href: PropTypes.string,
+    label: PropTypes.string
+  }))),
+  /**
+   * Uses component name by default
+   */
+  altTitle: PropTypes.string,
+  /**
+   * Array with content sections
+   */
+  blocks: PropTypes.arrayOf(PropTypes.shape({
+    /**
+     * Optional title story name used by default<h3>
+     */
+    title: PropTypes.string,
+    /**
+     * Optional subTitle a <h4>
+     */
+    subTitle: PropTypes.string,
+    /**
+     * Optional description, strings treated as markdown.
+     */
+    description: PropTypes.node,
+    /**
+     * Story imported from story file
+     */
+    story: PropTypes.func,
+    /**
+     * Some source code
+     * default language `jsx`
+     */
+    source: PropTypes.shape({
+      language: PropTypes.oneOf('javascript', 'css', 'jsx'),
+      code: PropTypes.string
+    })
+  })),
+  /**
+   * Set to true if no published example exists (all components and patterns should have an example)
+   */
+  omitCodedExample: PropTypes.bool,
+  /**
+   * Stories unreferenced in blocks included by default
+   */
+  omitUnreferencedStories: PropTypes.bool
+};

package/es/global/js/utils/story-helper.js

@@ -1,3 +1,5 @@
+import _toArray from "@babel/runtime/helpers/toArray";
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 //
 // Copyright IBM Corp. 2021, 2021
 //
@@ -10,6 +12,7 @@ import PropTypes from 'prop-types';
 import { sanitize } from '@storybook/csf';
 import pkg from '../package-settings';
 import { getPathForComponent } from '../../../../../core/story-structure';
+import { paramCase } from 'change-case';
 
 /**
  * A helper function to return the structured story title for a component.
@@ -64,12 +67,14 @@ export var prepareStory = function prepareStory(template, options) {
  * The link URL is based on the example directory name and the standard codesandbox URL for package examples.
  */
 var packagePath = 'github/carbon-design-system/ibm-products/tree/main/examples/carbon-for-ibm-products';
+export var codeSandboxHref = function codeSandboxHref(exampleDirectory) {
+  return "https://codesandbox.io/p/sandbox/".concat(packagePath, "/").concat(exampleDirectory, "?file=%2Fsrc%2FExample%2FExample.jsx");
+};
 export var CodesandboxLink = function CodesandboxLink(_ref) {
   var exampleDirectory = _ref.exampleDirectory;
-  // const stackblitz = `https://stackblitz.com/${packagePath}/${dir}?file=src%2FExample%2FExample.jsx`;
-  var codesandbox = "https://codesandbox.io/p/sandbox/".concat(packagePath, "/").concat(exampleDirectory, "?file=%2Fsrc%2FExample%2FExample.jsx");
+  var href = codeSandboxHref(exampleDirectory);
   return /*#__PURE__*/React.createElement("a", {
-    href: codesandbox
+    href: href
   }, /*#__PURE__*/React.createElement("img", {
     alt: "Edit on CodeSandbox",
     src: "https://codesandbox.io/static/img/play-codesandbox.svg"
@@ -81,11 +86,14 @@ CodesandboxLink.propTypes = {
    */
   exampleDirectory: PropTypes.string
 };
+export var stackblitzHref = function stackblitzHref(exampleDirectory) {
+  return "https://stackblitz.com/".concat(packagePath, "/").concat(exampleDirectory, "?file=src%2FExample%2FExample.jsx");
+};
 export var StackblitzLink = function StackblitzLink(_ref2) {
   var exampleDirectory = _ref2.exampleDirectory;
-  var stackblitz = "https://stackblitz.com/".concat(packagePath, "/").concat(exampleDirectory, "?file=src%2FExample%2FExample.jsx");
+  var href = stackblitzHref(exampleDirectory);
   return /*#__PURE__*/React.createElement("a", {
-    href: stackblitz
+    href: href
   }, /*#__PURE__*/React.createElement("img", {
     alt: "Edit on Stackblitz",
     src: "https://c.staticblitz.com/assets/favicon_sb-861fe1b85c0dc928750c62de15fed96fc75e57ee366bd937bad17a3938917b3f.svg"
@@ -97,6 +105,100 @@ StackblitzLink.propTypes = {
    */
   exampleDirectory: PropTypes.string
 };
+export var palUsageHref = function palUsageHref(csfFile) {
+  var _csfFile$meta;
+  var title = csfFile === null || csfFile === void 0 ? void 0 : (_csfFile$meta = csfFile.meta) === null || _csfFile$meta === void 0 ? void 0 : _csfFile$meta.title;
+  var _title$split = title.split('/'),
+    _title$split2 = _slicedToArray(_title$split, 3),
+    _pkg = _title$split2[0],
+    kind = _title$split2[1],
+    section = _title$split2[2];
+  if (/components|patterns/i.test(kind) && name) {
+    return "https://pages.github.ibm.com/cdai-design/pal/".concat(kind, "s/").concat(paramCase(section), "/usage");
+  }
+};
+export var storyDocsPageTitle = function storyDocsPageTitle(csfFile) {
+  var _csfFile$meta2;
+  var title = csfFile === null || csfFile === void 0 ? void 0 : (_csfFile$meta2 = csfFile.meta) === null || _csfFile$meta2 === void 0 ? void 0 : _csfFile$meta2.title;
+  var _title$split3 = title.split('/'),
+    _title$split4 = _toArray(_title$split3),
+    _pkg = _title$split4[0],
+    kind = _title$split4[1],
+    a = _title$split4[2],
+    b = _title$split4[3],
+    rest = _title$split4.slice(4);
+  var component;
+  if (/components|patterns/i.test(kind)) {
+    // components and patterns have an additional level
+    component = b;
+  } else {
+    component = a;
+  }
+  var name = component.split('#')[0]; // canary always written as Example#canary};
+
+  if (name) {
+    if (rest.length > 0) {
+      return "".concat(name, " (").concat(rest.join(' '), ")");
+    } else {
+      return name;
+    }
+  }
+  console.error('Error: unable to parse title from metadata.');
+  return title;
+};
+export var storyDocsPageInfo = function storyDocsPageInfo(csfFile) {
+  var _csfFile$meta3;
+  var title = csfFile === null || csfFile === void 0 ? void 0 : (_csfFile$meta3 = csfFile.meta) === null || _csfFile$meta3 === void 0 ? void 0 : _csfFile$meta3.title;
+  var _title$split5 = title.split('/'),
+    _title$split6 = _toArray(_title$split5),
+    pkg = _title$split6[0],
+    kind = _title$split6[1],
+    a = _title$split6[2],
+    b = _title$split6[3],
+    rest = _title$split6.slice(4);
+  var result = {
+    package: pkg,
+    kind: kind,
+    expectCodedExample: false
+  };
+  var component;
+  if (/components|patterns/i.test(kind)) {
+    result.expectCodedExample = true;
+    // components and patterns have an additional level
+    component = b;
+    result.section = a;
+    result.guidelinesHref = "https://pages.github.ibm.com/cdai-design/pal/".concat(kind, "s/").concat(paramCase(result.section), "/usage");
+  } else {
+    component = a;
+  }
+  var nameSplit = component.split('#'); // canary always written as Example#canary};
+  var name = nameSplit[0];
+  if (nameSplit.length > 1 && nameSplit[1] === 'canary') {
+    result.canary = true;
+  }
+  if (name) {
+    if (rest.length > 0) {
+      result.component = result.title = "".concat(name, " (").concat(rest.join(' '), ")");
+    } else {
+      result.component = name;
+      result.title = name;
+    }
+  } else {
+    console.error('Error: unable to parse title from metadata.');
+    result.title = title;
+  }
+  if (result.guidelinesHref) {
+    result.guidelinesLinkLabel = "".concat(result.title, " usage guidelines");
+  }
+  return result;
+};
+export var storyDocsGuidelines = function storyDocsGuidelines(csfFile) {
+  var storyInfo = storyDocsPageInfo(csfFile);
+  return {
+    href: storyInfo.guidelinesHref,
+    label: storyInfo.guidelinesLinkLabel
+  };
+};
 
 /**
  * A helper function that finds the designated theme on the Storybook canvas.

package/lib/components/APIKeyModal/APIKeyModal.docs-page.js

@@ -0,0 +1,37 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _typeof = require("@babel/runtime/helpers/typeof");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _StoryDocsPage = require("../../global/js/utils/StoryDocsPage");
+var _blocks = require("@storybook/blocks");
+var _storyHelper = require("../../global/js/utils/story-helper");
+var stories = _interopRequireWildcard(require("./APIKeyModal.stories"));
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || _typeof(obj) !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+var DocsPage = function DocsPage() {
+  var _useOf = (0, _blocks.useOf)('meta', ['meta']),
+    csfFile = _useOf.csfFile;
+  return /*#__PURE__*/_react.default.createElement(_StoryDocsPage.StoryDocsPage, {
+    altGuidelinesHref: [(0, _storyHelper.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'
+    }],
+    blocks: [{
+      story: stories.Edit,
+      description: "API key creation / generation is assumed to be the default mode for this modal.\nTo enable key editing you have to set the `edit` prop to true and supply any\nother edit related props with the relevant input."
+    }, {
+      description: "By default generate and edit only supply a name input for your key. If you need additional input you should use custom steps",
+      story: stories.CustomEdit
+    }]
+  });
+};
+var _default = DocsPage;
+exports.default = _default;

package/lib/components/AboutModal/AboutModal.docs-page.js

@@ -0,0 +1,32 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _typeof = require("@babel/runtime/helpers/typeof");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _StoryDocsPage = require("../../global/js/utils/StoryDocsPage");
+var stories = _interopRequireWildcard(require("./AboutModal.stories"));
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || _typeof(obj) !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+var DocsPage = function DocsPage() {
+  return /*#__PURE__*/_react.default.createElement(_StoryDocsPage.StoryDocsPage, {
+    guidelinesHref: "https://pages.github.ibm.com/cdai-design/pal/patterns/about-modal/usage",
+    blocks: [{
+      story: stories.aboutModal
+    }, {
+      story: stories.fullyLoaded
+    }, {
+      title: 'Overriding the Carbon theme',
+      description: 'The design recommendation is to use a dark theme for the AboutModal if the application is currently using a light theme, and vice versa. The theme applied to the AboutModal can easily be customized as follows:',
+      source: {
+        language: 'css',
+        code: ".#{$pkg-prefix}--about-modal {\n  @include carbon--theme(\n    $theme: $carbon--theme--g90\n  );\n}"
+      }
+    }]
+  });
+};
+var _default = DocsPage;
+exports.default = _default;

package/lib/components/AboutModal/AboutModal.js

@@ -39,7 +39,7 @@ var componentName = 'AboutModal';
 // NOTE: the component SCSS is not imported here: it is rolled up separately.
 
 /**
- * The AboutModal component provides a way to communicate product information
+ * The `AboutModal` component provides a way to communicate product information
  * to users. It is triggered by a user’s action, appears on top of the main
  * page content, and is persistent until dismissed. The purpose of this modal
  * should be immediately apparent to the user, with a clear and obvious path