RecursiveList (carbon-design-system#717)

* feat(recursive-list): add RecursiveList

* feat(recursive-list): rename items prop to children

* docs(recursive-list): add full examples

* test(recursive-list): add types test

* refactor(recursive-list): remove superfluous nested prop

* docs(recursive-list): update docs

* fix(recursive-list): remove nested prop from type test

* fix(recursive-list): explicitly type restProps

COMPONENT_INDEX.md

@@ -1,6 +1,6 @@
 # Component Index
 
-> 168 components exported from [email protected].
+> 169 components exported from [email protected].
 
 ## Components
 
@@ -107,6 +107,7 @@
 - [`RadioButtonGroup`](#radiobuttongroup)
 - [`RadioButtonSkeleton`](#radiobuttonskeleton)
 - [`RadioTile`](#radiotile)
+- [`RecursiveList`](#recursivelist)
 - [`Row`](#row)
 - [`Search`](#search)
 - [`SearchSkeleton`](#searchskeleton)
@@ -3031,6 +3032,33 @@ None.
 | mouseenter | forwarded | --     |
 | mouseleave | forwarded | --     |
 
+## `RecursiveList`
+
+### Types
+
+```ts
+export interface RecursiveListNode {
+  text?: string;
+  href?: string;
+  html?: string;
+}
+```
+
+### Props
+
+| Prop name | Kind             | Reactive | Type                                                                        | Default value            | Description                        |
+| :-------- | :--------------- | :------- | :-------------------------------------------------------------------------- | ------------------------ | ---------------------------------- |
+| children  | <code>let</code> | No       | <code>Array<RecursiveListNode & { children?: RecursiveListNode[]; }></code> | <code>[]</code>          | Specify the children to render     |
+| type      | <code>let</code> | No       | <code>"unordered" &#124; "ordered" &#124; "ordered-native"</code>           | <code>"unordered"</code> | Specify the type of list to render |
+
+### Slots
+
+None.
+
+### Events
+
+None.
+
 ## `Row`
 
 ### Props

docs/src/COMPONENT_API.json

@@ -1,5 +1,5 @@
 {
-  "total": 168,
+  "total": 169,
   "components": [
     {
       "moduleName": "Accordion",
@@ -7865,6 +7865,42 @@
       "typedefs": [],
       "rest_props": { "type": "Element", "name": "label" }
     },
+    {
+      "moduleName": "RecursiveList",
+      "filePath": "src/RecursiveList/RecursiveList.svelte",
+      "props": [
+        {
+          "name": "children",
+          "kind": "let",
+          "description": "Specify the children to render",
+          "type": "Array<RecursiveListNode & { children?: RecursiveListNode[]; }>",
+          "value": "[]",
+          "isFunction": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "type",
+          "kind": "let",
+          "description": "Specify the type of list to render",
+          "type": "\"unordered\" | \"ordered\" | \"ordered-native\"",
+          "value": "\"unordered\"",
+          "isFunction": false,
+          "constant": false,
+          "reactive": false
+        }
+      ],
+      "slots": [],
+      "events": [],
+      "typedefs": [
+        {
+          "type": "{ text?: string; href?: string; html?: string; }",
+          "name": "RecursiveListNode",
+          "ts": "interface RecursiveListNode { text?: string; href?: string; html?: string; }"
+        }
+      ],
+      "rest_props": { "type": "Element", "name": "ul | ol" }
+    },
     {
       "moduleName": "Row",
       "filePath": "src/Grid/Row.svelte",

docs/src/pages/_layout.svelte

@@ -20,7 +20,7 @@
   import Footer from "../components/Footer.svelte";
 
   const deprecated = ["ToggleSmall", "Icon"];
-  const new_components = ["ProgressBar"];
+  const new_components = ["ProgressBar", "RecursiveList"];
 
   let isOpen = false;
   let isSideNavOpen = true;

docs/src/pages/components/OrderedList.svx

@@ -3,10 +3,16 @@ components: ["OrderedList", "ListItem"]
 ---
 
 <script>
-  import { OrderedList, ListItem, Link } from "carbon-components-svelte";
+  import { InlineNotification, OrderedList, ListItem, Link } from "carbon-components-svelte";
   import Preview from "../../components/Preview.svelte";
 </script>
 
+<InlineNotification svx-ignore title="Tip:" kind="info" hideCloseButton>
+  <div class="body-short-01">
+    To render data formatted as a tree structure, use the <Link href="/components/RecursiveList#ordered">RecursiveList</Link> component.
+  </div>
+</InlineNotification>
+
 ### Default
 
 <OrderedList>

docs/src/pages/components/RecursiveList.svx

@@ -0,0 +1,34 @@
+<script>
+  import { InlineNotification, RecursiveList } from "carbon-components-svelte";
+  import Preview from "../../components/Preview.svelte";
+</script>
+
+This component uses the [svelte:self API](https://svelte.dev/docs#svelte_self) to render the [UnorderedList](/components/UnorderedList) and [OrderedList](/components/OrderedList) components with data formatted as a tree structure. This is especially useful when the depth of the tree is unknown.
+
+A child node can render text (`text`), a link (`href`), HTML content (`html`), and other `children`.
+
+<InlineNotification svx-ignore title="Warning:" kind="warning" hideCloseButton>
+  <div class="body-short-01">
+    HTML content provided via the <code>html</code> prop is not sanitized.
+  </div>
+</InlineNotification>
+
+### Unordered
+
+The `children` prop accepts an array of child nodes.
+
+By default, the list type is unordered.
+
+<FileSource src="/framed/RecursiveList/RecursiveList" />
+
+### Ordered
+
+Set `type` to `"ordered"` to use the ordered list variant.
+
+<FileSource src="/framed/RecursiveList/RecursiveListOrdered" />
+
+### Ordered (native styles)
+
+Set `type` to `"ordered-native"` to use the native styles for an ordered list.
+
+<FileSource src="/framed/RecursiveList/RecursiveListOrderedNative" />

docs/src/pages/components/UnorderedList.svx

@@ -3,10 +3,16 @@ components: ["UnorderedList", "ListItem"]
 ---
 
 <script>
-  import { UnorderedList, ListItem, Link } from "carbon-components-svelte";
+  import { InlineNotification, UnorderedList, ListItem, Link } from "carbon-components-svelte";
   import Preview from "../../components/Preview.svelte";
 </script>
 
+<InlineNotification svx-ignore title="Tip:" kind="info" hideCloseButton>
+  <div class="body-short-01">
+    To render data formatted as a tree structure, use the <Link href="/components/RecursiveList#unordered">RecursiveList</Link> component.
+  </div>
+</InlineNotification>
+
 ### Default
 
 <UnorderedList>

docs/src/pages/framed/RecursiveList/RecursiveList.svelte

@@ -0,0 +1,32 @@
+<script>
+  import { RecursiveList } from "carbon-components-svelte";
+
+  const children = [
+    {
+      text: "Item 1",
+      children: [
+        {
+          text: "Item 1a",
+          children: [{ html: "<h5>HTML content</h5>" }],
+        },
+      ],
+    },
+    {
+      text: "Item 2",
+      children: [
+        {
+          href: "https://svelte.dev/",
+        },
+        {
+          href: "https://svelte.dev/",
+          text: "Link with custom text",
+        },
+      ],
+    },
+    {
+      text: "Item 3",
+    },
+  ];
+</script>
+
+<RecursiveList children="{children}" />

docs/src/pages/framed/RecursiveList/RecursiveListOrdered.svelte

@@ -0,0 +1,32 @@
+<script>
+  import { RecursiveList } from "carbon-components-svelte";
+
+  const children = [
+    {
+      text: "Item 1",
+      children: [
+        {
+          text: "Item 1a",
+          children: [{ html: "<h5>HTML content</h5>" }],
+        },
+      ],
+    },
+    {
+      text: "Item 2",
+      children: [
+        {
+          href: "https://svelte.dev/",
+        },
+        {
+          href: "https://svelte.dev/",
+          text: "Link with custom text",
+        },
+      ],
+    },
+    {
+      text: "Item 3",
+    },
+  ];
+</script>
+
+<RecursiveList type="ordered" children="{children}" />

docs/src/pages/framed/RecursiveList/RecursiveListOrderedNative.svelte

@@ -0,0 +1,32 @@
+<script>
+  import { RecursiveList } from "carbon-components-svelte";
+
+  const children = [
+    {
+      text: "Item 1",
+      children: [
+        {
+          text: "Item 1a",
+          children: [{ html: "<h5>HTML content</h5>" }],
+        },
+      ],
+    },
+    {
+      text: "Item 2",
+      children: [
+        {
+          href: "https://svelte.dev/",
+        },
+        {
+          href: "https://svelte.dev/",
+          text: "Link with custom text",
+        },
+      ],
+    },
+    {
+      text: "Item 3",
+    },
+  ];
+</script>
+
+<RecursiveList type="ordered-native" children="{children}" />

src/RecursiveList/RecursiveList.svelte

@@ -0,0 +1,38 @@
+<script>
+  /**
+   * @typedef {{ text?: string; href?: string; html?: string; }} RecursiveListNode
+   * @restProps {ul | ol}
+   */
+
+  /**
+   * Specify the children to render
+   * @type {Array<RecursiveListNode & { children?: RecursiveListNode[]; }>}
+   */
+  export let children = [];
+
+  /**
+   * Specify the type of list to render
+   * @type {"unordered" | "ordered" | "ordered-native"}
+   */
+  export let type = "unordered";
+
+  import UnorderedList from "../UnorderedList/UnorderedList.svelte";
+  import OrderedList from "../OrderedList/OrderedList.svelte";
+  import RecursiveListItem from "./RecursiveListItem.svelte";
+</script>
+
+<svelte:component
+  this="{type === 'unordered' ? UnorderedList : OrderedList}"
+  native="{type === 'ordered-native'}"
+  {...$$restProps}
+>
+  {#each children as child}
+    {#if Array.isArray(child.children)}
+      <RecursiveListItem {...child}>
+        <svelte:self {...child} type="{type}" nested />
+      </RecursiveListItem>
+    {:else}
+      <RecursiveListItem {...child} />
+    {/if}
+  {/each}
+</svelte:component>

src/RecursiveList/RecursiveListItem.svelte

@@ -0,0 +1,19 @@
+<script>
+  /** Specify the text to render*/
+  export let text = "";
+
+  /** Specify a link href */
+  export let href = "";
+
+  /** Specify HTML to render using `@html` */
+  export let html = "";
+
+  import ListItem from "../ListItem/ListItem.svelte";
+</script>
+
+<ListItem>
+  {#if text && !href}{text}{/if}
+  {#if href}<a class:bx--link="{true}" href="{href}">{text || href}</a>{/if}
+  {#if !text && html}{@html html}{/if}
+  <slot />
+</ListItem>

src/RecursiveList/index.js

@@ -0,0 +1 @@
+export { default as RecursiveList } from "./RecursiveList.svelte";

src/index.js

@@ -93,6 +93,7 @@ export {
 } from "./ProgressIndicator";
 export { RadioButton, RadioButtonSkeleton } from "./RadioButton";
 export { RadioButtonGroup } from "./RadioButtonGroup";
+export { RecursiveList } from "./RecursiveList";
 export { Search, SearchSkeleton } from "./Search";
 export { Select, SelectSkeleton, SelectItem, SelectItemGroup } from "./Select";
 export { SkeletonPlaceholder } from "./SkeletonPlaceholder";

tests/ProgressBar.test.svelte

@@ -1,4 +1,4 @@
-<script>
+<script lang="ts">
   import { ProgressBar } from "../types";
 </script>
 

tests/RecursiveList.test.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+  import { RecursiveList } from "../types";
+
+  const children = [
+    {
+      text: "Item 1",
+      children: [
+        {
+          text: "Item 1a",
+          children: [{ html: "<h5>HTML content</h5>" }],
+        },
+      ],
+    },
+    {
+      text: "Item 2",
+      children: [
+        {
+          href: "https://svelte.dev/",
+        },
+        {
+          href: "https://svelte.dev/",
+          text: "Link with custom text",
+        },
+      ],
+    },
+    {
+      text: "Item 3",
+    },
+  ];
+</script>
+
+<RecursiveList type="ordered" children="{children}" />