feat: add contained-list component

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -8639,6 +8639,106 @@ Map {
     "$$typeof": Symbol(react.forward_ref),
     "render": [Function],
   },
+  "unstable_ContainedList" => Object {
+    "ContainedListItem": Object {
+      "propTypes": Object {
+        "action": Object {
+          "type": "node",
+        },
+        "children": Object {
+          "type": "node",
+        },
+        "className": Object {
+          "type": "string",
+        },
+        "disabled": Object {
+          "type": "bool",
+        },
+        "onClick": Object {
+          "type": "func",
+        },
+        "renderIcon": Object {
+          "args": Array [
+            Array [
+              Object {
+                "type": "func",
+              },
+              Object {
+                "type": "object",
+              },
+            ],
+          ],
+          "type": "oneOfType",
+        },
+      },
+    },
+    "propTypes": Object {
+      "action": Object {
+        "type": "node",
+      },
+      "children": Object {
+        "type": "node",
+      },
+      "className": Object {
+        "type": "string",
+      },
+      "kind": Object {
+        "args": Array [
+          Array [
+            "on-page",
+            "disclosed",
+          ],
+        ],
+        "type": "oneOf",
+      },
+      "label": Object {
+        "args": Array [
+          Array [
+            Object {
+              "type": "string",
+            },
+            Object {
+              "type": "node",
+            },
+          ],
+        ],
+        "isRequired": true,
+        "type": "oneOfType",
+      },
+    },
+  },
+  "unstable_ContainedListItem" => Object {
+    "propTypes": Object {
+      "action": Object {
+        "type": "node",
+      },
+      "children": Object {
+        "type": "node",
+      },
+      "className": Object {
+        "type": "string",
+      },
+      "disabled": Object {
+        "type": "bool",
+      },
+      "onClick": Object {
+        "type": "func",
+      },
+      "renderIcon": Object {
+        "args": Array [
+          Array [
+            Object {
+              "type": "func",
+            },
+            Object {
+              "type": "object",
+            },
+          ],
+        ],
+        "type": "oneOfType",
+      },
+    },
+  },
   "unstable_FeatureFlags" => Object {
     "propTypes": Object {
       "children": Object {

packages/react/src/__tests__/index-test.js

@@ -214,6 +214,8 @@ describe('Carbon Components React', () => {
         "TreeView",
         "UnorderedList",
         "VStack",
+        "unstable_ContainedList",
+        "unstable_ContainedListItem",
         "unstable_FeatureFlags",
         "unstable_LayoutDirection",
         "unstable_Menu",

packages/react/src/components/ContainedList/ContainedList.js

@@ -0,0 +1,74 @@
+/**
+ * Copyright IBM Corp. 2022
+ *
+ * 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 classNames from 'classnames';
+import { useId } from '../../internal/useId';
+import { usePrefix } from '../../internal/usePrefix';
+
+const variants = ['on-page', 'disclosed'];
+
+function ContainedList({
+  action,
+  children,
+  className,
+  kind = variants[0],
+  label,
+}) {
+  const labelId = `${useId('contained-list')}-header`;
+  const prefix = usePrefix();
+
+  const classes = classNames(
+    `${prefix}--contained-list`,
+    `${prefix}--contained-list--${kind}`,
+    className
+  );
+
+  return (
+    <div className={classes}>
+      <div className={`${prefix}--contained-list__header`}>
+        <div id={labelId} className={`${prefix}--contained-list__label`}>
+          {label}
+        </div>
+        {action && (
+          <div className={`${prefix}--contained-list__action`}>{action}</div>
+        )}
+      </div>
+      <ul aria-labelledby={labelId}>{children}</ul>
+    </div>
+  );
+}
+
+ContainedList.propTypes = {
+  /**
+   * A slot for a possible interactive element to render.
+   */
+  action: PropTypes.node,
+
+  /**
+   * A collection of ContainedListItems to be rendered in the ContainedList
+   */
+  children: PropTypes.node,
+
+  /**
+   * Additional CSS class names.
+   */
+  className: PropTypes.string,
+
+  /**
+   * The kind of ContainedList you want to display
+   */
+  kind: PropTypes.oneOf(variants),
+
+  /**
+   * A label describing the contained list.
+   */
+  label: PropTypes.oneOfType([PropTypes.string, PropTypes.node]).isRequired,
+};
+
+export default ContainedList;

packages/react/src/components/ContainedList/ContainedListItem/ContainedListItem.js

@@ -0,0 +1,96 @@
+/**
+ * Copyright IBM Corp. 2022
+ *
+ * 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 classNames from 'classnames';
+import { usePrefix } from '../../../internal/usePrefix';
+
+function ContainedListItem({
+  action,
+  children,
+  className,
+  disabled = false,
+  onClick,
+  renderIcon: IconElement,
+}) {
+  const prefix = usePrefix();
+
+  const isClickable = onClick !== undefined;
+
+  const classes = classNames(`${prefix}--contained-list-item`, className, {
+    [`${prefix}--contained-list-item--clickable`]: isClickable,
+    [`${prefix}--contained-list-item--with-icon`]: IconElement,
+    [`${prefix}--contained-list-item--with-action`]: action,
+  });
+
+  const content = (
+    <>
+      {IconElement && (
+        <div className={`${prefix}--contained-list-item__icon`}>
+          <IconElement />
+        </div>
+      )}
+      <div>{children}</div>
+    </>
+  );
+
+  return (
+    <li className={classes}>
+      {isClickable ? (
+        <button
+          className={`${prefix}--contained-list-item__content`}
+          type="button"
+          disabled={disabled}
+          onClick={onClick}>
+          {content}
+        </button>
+      ) : (
+        <div className={`${prefix}--contained-list-item__content`}>
+          {content}
+        </div>
+      )}
+      {action && (
+        <div className={`${prefix}--contained-list-item__action`}>{action}</div>
+      )}
+    </li>
+  );
+}
+
+ContainedListItem.propTypes = {
+  /**
+   * A slot for a possible interactive element to render within the item.
+   */
+  action: PropTypes.node,
+
+  /**
+   * The content of this item. Must not contain any interactive elements. Use props.action to include those.
+   */
+  children: PropTypes.node,
+
+  /**
+   * Additional CSS class names.
+   */
+  className: PropTypes.string,
+
+  /**
+   * Whether this item is disabled.
+   */
+  disabled: PropTypes.bool,
+
+  /**
+   * Provide an optional function to be called when the item is clicked.
+   */
+  onClick: PropTypes.func,
+
+  /**
+   * Provide an optional icon to render in front of the item's content.
+   */
+  renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+};
+
+export default ContainedListItem;

packages/react/src/components/ContainedList/ContainedListItem/index.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright IBM Corp. 2022
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export default from './ContainedListItem';