@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/components/tree/tree.stories.tsx

@@ -0,0 +1,424 @@
+import {
+  createOnDropHandler,
+  dragAndDropFeature,
+  hotkeysCoreFeature,
+  type ItemInstance,
+  keyboardDragAndDropFeature,
+  searchFeature,
+  selectionFeature,
+  syncDataLoaderFeature,
+} from "@headless-tree/core";
+import { useTree } from "@headless-tree/react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  FileTextIcon,
+  FolderIcon,
+  FolderOpenIcon,
+  MoreHorizontalIcon,
+} from "lucide-react";
+import { type ComponentType, useState } from "react";
+
+import { Input } from "../input/input";
+import { Menu } from "../menu/menu";
+import { TreeDragLine, TreeItem, TreeItemLabel, TreeRoot } from "./tree";
+
+interface Item {
+  name: string;
+  children?: string[];
+}
+
+const items: Record<string, Item> = {
+  root: { name: "root", children: ["docs", "src", "tests"] },
+  docs: { name: "docs", children: ["readme", "api"] },
+  readme: { name: "README.md" },
+  api: { name: "API.md" },
+  src: { name: "src", children: ["components", "lib"] },
+  components: { name: "components", children: ["button", "tree"] },
+  button: { name: "button.tsx" },
+  tree: { name: "tree.tsx" },
+  lib: { name: "lib", children: ["utils"] },
+  utils: { name: "utils.ts" },
+  tests: { name: "tests", children: ["spec"] },
+  spec: { name: "tree.test.tsx" },
+};
+
+const baseConfig = {
+  rootItemId: "root",
+  getItemName: (item: ItemInstance<Item>) => item.getItemData().name,
+  isItemFolder: (item: ItemInstance<Item>) =>
+    (item.getItemData().children?.length ?? 0) > 0,
+  dataLoader: {
+    getItem: (itemId: string) => items[itemId],
+    getChildren: (itemId: string) => items[itemId]?.children ?? [],
+  },
+  initialState: { expandedItems: ["src", "components", "docs"] },
+};
+
+/**
+ * Accessible hierarchical tree built on top of
+ * [@headless-tree](https://headless-tree.lukasbach.com/). The consumer creates
+ * a tree instance with `useTree(config)`, registers the features they need,
+ * and iterates `tree.getItems()` to render rows.
+ *
+ * Setup:
+ *
+ * ```tsx
+ * const tree = useTree<Item>({
+ *   rootItemId: "root",
+ *   getItemName: (item) => item.getItemData().name,
+ *   isItemFolder: (item) => (item.getItemData().children?.length ?? 0) > 0,
+ *   dataLoader: {
+ *     getItem: (itemId) => items[itemId],
+ *     getChildren: (itemId) => items[itemId]?.children ?? [],
+ *   },
+ *   features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+ * });
+ *
+ * <TreeRoot tree={tree}>
+ *   {tree.getItems().map((item) => (
+ *     <TreeItem
+ *       key={item.getId()}
+ *       item={item}
+ *       leafIcon={<FileIcon />}
+ *       parentIcon={(isExpanded) =>
+ *         isExpanded ? <FolderOpenIcon /> : <FolderIcon />
+ *       }
+ *     />
+ *   ))}
+ * </TreeRoot>
+ * ```
+ *
+ * Features (from `@headless-tree/core` — register only what you use):
+ * - `syncDataLoaderFeature` — sync data via `dataLoader.getItem` /
+ *   `dataLoader.getChildren`.
+ * - `asyncDataLoaderFeature` — returns Promises; children load on expand.
+ * - `selectionFeature` — single/multi selection, exposes `item.isSelected()`.
+ * - `hotkeysCoreFeature` — Arrow keys to navigate, Enter to activate, Space to
+ *   select, Right/Left to expand/collapse.
+ * - `dragAndDropFeature` — drag/drop with `onDrop`. Pair with `TreeDragLine`.
+ * - `keyboardDragAndDropFeature` — keyboard-driven reorder.
+ * - `searchFeature` — drive with `tree.setSearch(value)`; matches expose
+ *   `item.isMatchingSearch()`.
+ * - `expandAllFeature` — `tree.expandAll()` / `tree.collapseAll()`.
+ * - `propMemoizationFeature` — memoizes `getProps()` (large trees).
+ *
+ * Key behaviors:
+ * - The consumer owns the tree instance, the data shape (`T`), and the
+ *   iteration. There is no `items` composite prop — that pattern doesn't fit
+ *   the breadth of real tree use cases.
+ * - `TreeItem` accepts `leafIcon` / `parentIcon` to render an icon before the
+ *   item's name without writing a custom label per row. `parentIcon` defaults
+ *   to a rotating chevron — pass your own `ReactNode` (use CSS via
+ *   `in-data-[expanded=true]:…` for state-driven styles) or a function
+ *   `(isExpanded) => ReactNode` to swap elements based on state. Pass
+ *   `parentIcon={null}` to opt out of the default. `leafIcon` defaults to no
+ *   icon. When `children` are provided, the icon props are ignored — children
+ *   take over the entire row.
+ * - `TreeItem` is the `<button>` row. It handles focus, selection, indent
+ *   (via the `--tree-indent` CSS variable on `TreeRoot`, default `20px`) and
+ *   exposes state through data attributes: `data-folder`, `data-expanded`,
+ *   `data-selected`, `data-drag-target`, `data-search-match`, `data-focused`.
+ * - `TreeItemLabel` is the visual zone (background, hover, selected,
+ *   search-match). It defaults to `item.getItemName()` when no children are
+ *   provided. It renders no toggle icon on its own — the icon comes from
+ *   `TreeItem`'s `leafIcon` / `parentIcon`, or from custom children.
+ * - `TreeDragLine` is optional; only render it when `dragAndDropFeature` is
+ *   registered. It positions itself absolutely inside `TreeRoot`.
+ * - State binding (`expandedItems`, `selectedItems`, etc.) is controlled via
+ *   `state` + `setState` on the `useTree` config, or left to internal state
+ *   with `initialState`.
+ *
+ * Reference: [headless-tree docs](https://headless-tree.lukasbach.com/docs/)
+ */
+const meta: Meta<typeof TreeRoot> = {
+  title: "Components/Tree",
+  component: TreeRoot,
+  parameters: { layout: "centered" },
+  subcomponents: {
+    TreeRoot: TreeRoot as ComponentType<unknown>,
+    TreeItem: TreeItem as ComponentType<unknown>,
+    TreeItemLabel: TreeItemLabel as ComponentType<unknown>,
+    TreeDragLine: TreeDragLine as ComponentType<unknown>,
+  },
+  argTypes: {
+    children: { control: false },
+    tree: { control: false },
+    render: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TreeRoot>;
+
+export const Default: Story = {
+  render: () => {
+    const tree = useTree<Item>({
+      ...baseConfig,
+      features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+    });
+
+    return (
+      <TreeRoot tree={tree} className="w-72">
+        {tree.getItems().map((item) => (
+          <TreeItem key={item.getId()} item={item} />
+        ))}
+      </TreeRoot>
+    );
+  },
+};
+
+/**
+ * Most real trees show distinct icons for folders and files. The function form
+ * of `parentIcon` swaps between open and closed folder icons based on the
+ * current expanded state.
+ */
+export const WithIcons: Story = {
+  render: () => {
+    const tree = useTree<Item>({
+      ...baseConfig,
+      features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+    });
+
+    return (
+      <TreeRoot tree={tree} className="w-72">
+        {tree.getItems().map((item) => (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            leafIcon={<FileTextIcon className="size-4 text-muted-foreground" />}
+            parentIcon={(isExpanded) =>
+              isExpanded ? (
+                <FolderOpenIcon className="size-4 text-muted-foreground" />
+              ) : (
+                <FolderIcon className="size-4 text-muted-foreground" />
+              )
+            }
+          />
+        ))}
+      </TreeRoot>
+    );
+  },
+};
+
+/**
+ * `selectionFeature` is multi-select by default. Click to select a single
+ * item, `Shift`-click for a range, `Ctrl`/`Cmd`-click to toggle. Read the
+ * current selection via `tree.getSelectedItems()`.
+ */
+export const MultipleSelection: Story = {
+  render: () => {
+    const tree = useTree<Item>({
+      ...baseConfig,
+      features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+    });
+
+    const selected = tree.getSelectedItems();
+
+    return (
+      <div className="flex w-72 flex-col gap-3">
+        <div className="flex items-center justify-between text-sm">
+          <span className="text-muted-foreground">
+            {selected.length} selected
+          </span>
+          {selected.length > 0 && (
+            <button
+              type="button"
+              onClick={() => tree.setSelectedItems([])}
+              className="text-muted-foreground underline-offset-2 hover:underline"
+            >
+              Clear
+            </button>
+          )}
+        </div>
+        <TreeRoot tree={tree}>
+          {tree.getItems().map((item) => (
+            <TreeItem
+              key={item.getId()}
+              item={item}
+              leafIcon={
+                <FileTextIcon className="size-4 text-muted-foreground" />
+              }
+              parentIcon={
+                <FolderIcon className="size-4 text-muted-foreground" />
+              }
+            />
+          ))}
+        </TreeRoot>
+      </div>
+    );
+  },
+};
+
+/**
+ * Drop the `leafIcon` / `parentIcon` shorthand and pass `children` directly to
+ * place action triggers **outside** `TreeItemLabel`. Wrap the trigger in a
+ * `stopPropagation` container so clicks on the menu don't activate the row.
+ *
+ * Note: `TreeItem` renders as `<button>` (headless-tree requires it for
+ * focus/keyboard), so the nested `Menu` trigger must be a non-button element
+ * (e.g. a `<span role="button">`) to keep the HTML valid.
+ */
+export const WithActions: Story = {
+  render: () => {
+    const tree = useTree<Item>({
+      ...baseConfig,
+      features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+    });
+
+    return (
+      <TreeRoot tree={tree} className="w-80">
+        {tree.getItems().map((item) => (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            className="group/row flex items-center"
+          >
+            <TreeItemLabel className="flex-1">
+              {item.isFolder() ? (
+                <FolderIcon className="size-4 text-muted-foreground" />
+              ) : (
+                <FileTextIcon className="size-4 text-muted-foreground" />
+              )}
+              {item.getItemName()}
+            </TreeItemLabel>
+            <span
+              onClick={(event) => event.stopPropagation()}
+              onKeyDown={(event) => event.stopPropagation()}
+              className="opacity-0 transition-opacity group-hover/row:opacity-100"
+            >
+              <Menu
+                trigger={
+                  <span
+                    role="button"
+                    tabIndex={-1}
+                    className="flex rounded-sm p-1 hover:bg-accent"
+                  >
+                    <MoreHorizontalIcon className="size-4 text-muted-foreground" />
+                  </span>
+                }
+                items={[
+                  {
+                    type: "item",
+                    label: "Rename",
+                    onSelect: () => console.log("Rename", item.getItemName()),
+                  },
+                  {
+                    type: "item",
+                    label: "Delete",
+                    onSelect: () => console.log("Delete", item.getItemName()),
+                  },
+                ]}
+              />
+            </span>
+          </TreeItem>
+        ))}
+      </TreeRoot>
+    );
+  },
+};
+
+/**
+ * Drag-and-drop with reordering. `createOnDropHandler` (from
+ * `@headless-tree/core`) writes the reordered child ids back to your data
+ * source — set `children` on the parent item and the tree rebuilds itself.
+ * `TreeDragLine` renders the visual indicator and must live inside `TreeRoot`
+ * (it positions absolutely against the root).
+ *
+ * Features needed: `dragAndDropFeature` (mouse) and
+ * `keyboardDragAndDropFeature` (keyboard accessibility).
+ *
+ * Reference: [headless-tree drag-and-drop docs](https://headless-tree.lukasbach.com/dnd/overview)
+ */
+export const DragAndDrop: Story = {
+  render: () => {
+    const [data] = useState(() => structuredClone(items));
+
+    const tree = useTree<Item>({
+      ...baseConfig,
+      dataLoader: {
+        getItem: (itemId: string) => data[itemId],
+        getChildren: (itemId: string) => data[itemId]?.children ?? [],
+      },
+      canReorder: true,
+      onDrop: createOnDropHandler<Item>((parent, newChildrenIds) => {
+        const node = data[parent.getId()];
+        if (node) node.children = newChildrenIds;
+      }),
+      features: [
+        syncDataLoaderFeature,
+        selectionFeature,
+        hotkeysCoreFeature,
+        dragAndDropFeature,
+        keyboardDragAndDropFeature,
+      ],
+    });
+
+    return (
+      <TreeRoot tree={tree} className="relative w-72">
+        {tree.getItems().map((item) => (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            leafIcon={<FileTextIcon className="size-4 text-muted-foreground" />}
+            parentIcon={(isExpanded) =>
+              isExpanded ? (
+                <FolderOpenIcon className="size-4 text-muted-foreground" />
+              ) : (
+                <FolderIcon className="size-4 text-muted-foreground" />
+              )
+            }
+          />
+        ))}
+        <TreeDragLine />
+      </TreeRoot>
+    );
+  },
+};
+
+/**
+ * Drive the search through `tree.setSearch(value)` and read the current
+ * query via `tree.getSearchValue()`. Matching rows expose
+ * `item.isMatchingSearch()` and receive `data-search-match="true"` on
+ * `TreeItem`, which `TreeItemLabel` styles automatically.
+ */
+export const Search: Story = {
+  render: () => {
+    const tree = useTree<Item>({
+      ...baseConfig,
+      initialState: {
+        expandedItems: ["docs", "src", "components", "lib", "tests"],
+        search: "tree",
+      },
+      features: [
+        syncDataLoaderFeature,
+        selectionFeature,
+        hotkeysCoreFeature,
+        searchFeature,
+      ],
+    });
+
+    return (
+      <div className="flex w-72 flex-col gap-3">
+        <Input
+          placeholder="Search…"
+          value={tree.getSearchValue()}
+          onChange={(value) => tree.setSearch(value || null)}
+        />
+        <TreeRoot tree={tree}>
+          {tree.getItems().map((item) => (
+            <TreeItem
+              key={item.getId()}
+              item={item}
+              leafIcon={
+                <FileTextIcon className="size-4 text-muted-foreground" />
+              }
+              parentIcon={
+                <FolderIcon className="size-4 text-muted-foreground" />
+              }
+            />
+          ))}
+        </TreeRoot>
+      </div>
+    );
+  },
+};