[Tree] Documentation #1806 (#2498)

* Finetune tree usage tab

* tree documentation changes, trying to get the tree example with renderer working

* lit virtualizer import

* documentation changes, partially working examples, still not ready code part

* Code part changes, added missing figma options table to the usage tab, some other improvements

* Usage and code part improved

* Accessibility part, some other improvements, removing new status from old docs

* Some changes after review

* tree documentation improvements after review, added missing tree wrapper example

* Update usage.md

* Background set on the sl-tree

* node background changed to transparent

* Update usage.md

Co-authored-by: Daniëlle Rameau <111998351+DanielleRameau@users.noreply.github.com>

* Update usage.md

* Update usage.md

---------

Co-authored-by: arecuenco-dsgn <alvarorecuenco@icloud.com>
Co-authored-by: Daniëlle Rameau <111998351+DanielleRameau@users.noreply.github.com>

Author: 3 people

packages/angular/stories/wrappers.stories.ts

@@ -1,4 +1,7 @@
+import { faFileLines, faFolder, faFolderOpen, faPen, faTrash } from '@fortawesome/pro-regular-svg-icons';
 import { Dialog as DialogElement } from '@sl-design-system/dialog';
+import { Icon as SlIcon } from '@sl-design-system/icon';
+import { FlatTreeDataSource } from '@sl-design-system/tree';
 import { type Meta, type StoryObj, moduleMetadata } from '@storybook/angular';
 import { AccordionItemComponent } from '../src/accordion/accordion-item.component';
 import { AccordionComponent } from '../src/accordion/accordion.component';
@@ -28,6 +31,7 @@ import { TabComponent } from '../src/tabs/tab.component';
 import { TextAreaComponent } from '../src/text-area/text-area.component';
 import { TextFieldComponent } from '../src/text-field/text-field.component';
 import { TooltipComponent } from '../src/tooltip/tooltip.component';
+import { TreeComponent } from '../src/tree/tree.component';
 
 export default {
   title: 'Wrappers',
@@ -61,12 +65,15 @@ export default {
         TabPanelComponent,
         TextFieldComponent,
         TextAreaComponent,
-        TooltipComponent
+        TooltipComponent,
+        TreeComponent
       ]
     })
   ]
 } as Meta;
 
+SlIcon.register(faFileLines, faFolder, faFolderOpen, faPen, faTrash);
+
 export const Accordion: StoryObj = {
   render: () => ({
     template: `
@@ -287,3 +294,52 @@ export const Tooltip: StoryObj = {
     `
   })
 };
+
+export const Tree: StoryObj = {
+  render: () => {
+    type Item = { id: number; expandable: boolean; level: number; name: string };
+
+    const flatData: Item[] = [
+      { id: 0, expandable: true, level: 0, name: 'Mathematics' },
+      { id: 1, expandable: true, level: 1, name: 'Algebra' },
+      { id: 2, expandable: false, level: 2, name: 'Lesson 1 - Linear equations.md' },
+      { id: 3, expandable: false, level: 2, name: 'Lesson 2 - Quadratic equations.md' },
+      { id: 4, expandable: true, level: 1, name: 'Geometry' },
+      { id: 5, expandable: false, level: 2, name: 'Lesson 1 - Triangles.md' },
+      { id: 6, expandable: false, level: 2, name: 'Lesson 2 - Circles.md' },
+      { id: 21, expandable: false, level: 1, name: 'Lesson 20 - Statistics and probability.md' },
+      { id: 7, expandable: true, level: 0, name: 'Science' },
+      { id: 8, expandable: true, level: 1, name: 'Physics' },
+      { id: 9, expandable: false, level: 2, name: 'Lesson 1 - Motion.md' },
+      { id: 10, expandable: false, level: 2, name: 'Lesson 2 - Forces.md' },
+      { id: 11, expandable: true, level: 1, name: 'Chemistry' },
+      { id: 12, expandable: false, level: 2, name: 'Lesson 1 - Atoms.md' },
+      { id: 13, expandable: false, level: 2, name: 'Lesson 2 - Reactions.md' },
+      { id: 14, expandable: true, level: 0, name: 'History' },
+      { id: 15, expandable: true, level: 1, name: 'Ancient Civilizations' },
+      { id: 16, expandable: false, level: 2, name: 'Egypt.md' },
+      { id: 17, expandable: false, level: 2, name: 'Rome.md' },
+      { id: 18, expandable: true, level: 1, name: 'Modern History' },
+      { id: 19, expandable: false, level: 2, name: 'World War I.md' },
+      { id: 20, expandable: false, level: 2, name: 'World War II.md' }
+    ];
+
+    const dataSource = new FlatTreeDataSource<Item>(flatData, {
+      getIcon: ({ name }: Item, expanded: boolean) =>
+        name.includes('.') ? 'far-file-lines' : `far-folder${expanded ? '-open' : ''}`,
+      getId: (item: Item) => item.id,
+      getLabel: ({ name }: Item) => name,
+      getLevel: ({ level }: Item) => level,
+      isExpandable: ({ expandable }: Item) => expandable,
+      isExpanded: ({ name }: Item) => ['tree', 'src'].includes(name),
+      selects: 'multiple'
+    });
+
+    return {
+      props: { dataSource },
+      template: `
+        <sl-tree [dataSource]="dataSource" aria-label="Subjects structure"></sl-tree>
+      `
+    };
+  }
+};

packages/components/tree/src/tree-node.scss

@@ -1,5 +1,5 @@
 :host {
-  --_bg-color: var(--sl-elevation-surface-base-default);
+  --_bg-color: transparent;
   --_bg-mix-color: var(--sl-color-background-neutral-interactive-plain);
   --_bg-opacity: var(--sl-opacity-interactive-plain-idle);
 

packages/components/tree/src/tree.scss

@@ -1,4 +1,5 @@
 :host {
+  background: var(--sl-elevation-surface-base-default);
   display: flex;
   scroll-padding-block: var(--sl-size-100);
 }

packages/components/tree/src/tree.ts

@@ -69,7 +69,10 @@ export class Tree<T = any> extends ObserveAttributesMixin(ScopedElementsMixin(Li
     return this.#dataSource;
   }
 
-  /** The model for the tree. */
+  /**
+   *  The model for the tree.
+   *  @type {TreeDataSource<T> | undefined}
+   *  */
   @property({ attribute: false })
   set dataSource(dataSource: TreeDataSource<T> | undefined) {
     if (this.#dataSource) {
@@ -88,7 +91,7 @@ export class Tree<T = any> extends ObserveAttributesMixin(ScopedElementsMixin(Li
    * Use this if you want to wait until lit-virtualizer has finished the rendering
    * the tree nodes. This can be useful in unit tests for example.
    */
-  get layoutComplete() {
+  get layoutComplete(): Promise<void> {
     return this.#virtualizer?.layoutComplete ?? Promise.resolve();
   }
 
@@ -175,6 +178,10 @@ export class Tree<T = any> extends ObserveAttributesMixin(ScopedElementsMixin(Li
     `;
   }
 
+  /**
+   * @internal
+   * Renders a single tree item as a virtualized row.
+   */
   renderItem(item: TreeDataSourceNode<T>): TemplateResult {
     const icon = item.expanded ? item.expandedIcon : item.icon;
 
@@ -217,6 +224,7 @@ export class Tree<T = any> extends ObserveAttributesMixin(ScopedElementsMixin(Li
     `;
   }
 
+  /** @internal */
   scrollToNode(node: TreeDataSourceNode<T>, options?: ScrollIntoViewOptions): void {
     const index = this.dataSource?.items.indexOf(node) ?? -1;
     if (index !== -1) {