@sproutsocial/seeds-react-tree 0.3.1

package/src/Common/useTreeState.ts

@@ -0,0 +1,107 @@
+import { useCallback, useMemo, useState } from "react";
+import type { TreeSelectableNodes, TreeSelectionMode } from "./types";
+
+type UseTreeStateOptions = {
+  selectionMode: TreeSelectionMode;
+  selectableNodes: TreeSelectableNodes;
+  defaultExpanded?: ReadonlyArray<string>;
+  expanded?: ReadonlyArray<string>;
+  onExpandedChange?: (expanded: string[]) => void;
+  defaultSelected?: ReadonlyArray<string>;
+  selected?: ReadonlyArray<string>;
+  onSelectionChange?: (selected: string[]) => void;
+};
+
+export function useTreeState(opts: UseTreeStateOptions) {
+  const {
+    selectionMode,
+    selectableNodes,
+    defaultExpanded,
+    expanded: expandedProp,
+    onExpandedChange,
+    defaultSelected,
+    selected: selectedProp,
+    onSelectionChange,
+  } = opts;
+
+  const [uncontrolledExpanded, setUncontrolledExpanded] = useState<Set<string>>(
+    () => new Set(defaultExpanded ?? [])
+  );
+  const [uncontrolledSelected, setUncontrolledSelected] = useState<Set<string>>(
+    () => new Set(defaultSelected ?? [])
+  );
+
+  const expanded = useMemo(
+    () => (expandedProp ? new Set(expandedProp) : uncontrolledExpanded),
+    [expandedProp, uncontrolledExpanded]
+  );
+
+  const selected = useMemo(
+    () => (selectedProp ? new Set(selectedProp) : uncontrolledSelected),
+    [selectedProp, uncontrolledSelected]
+  );
+
+  const toggleExpanded = useCallback(
+    (id: string, next?: boolean) => {
+      const current = expandedProp
+        ? new Set(expandedProp)
+        : uncontrolledExpanded;
+      const willOpen = next ?? !current.has(id);
+      const updated = new Set(current);
+      if (willOpen) {
+        updated.add(id);
+      } else {
+        updated.delete(id);
+      }
+      if (!expandedProp) {
+        setUncontrolledExpanded(updated);
+      }
+      onExpandedChange?.(Array.from(updated));
+    },
+    [expandedProp, uncontrolledExpanded, onExpandedChange]
+  );
+
+  const toggleSelected = useCallback(
+    (id: string, hasChildren: boolean) => {
+      if (selectionMode === "none") return;
+      if (selectableNodes === "leaves" && hasChildren) return;
+
+      const current = selectedProp
+        ? new Set(selectedProp)
+        : uncontrolledSelected;
+      const updated = new Set<string>();
+
+      if (selectionMode === "single") {
+        if (!current.has(id)) {
+          updated.add(id);
+        }
+      } else {
+        current.forEach((v) => updated.add(v));
+        if (updated.has(id)) {
+          updated.delete(id);
+        } else {
+          updated.add(id);
+        }
+      }
+
+      if (!selectedProp) {
+        setUncontrolledSelected(updated);
+      }
+      onSelectionChange?.(Array.from(updated));
+    },
+    [
+      selectionMode,
+      selectableNodes,
+      selectedProp,
+      uncontrolledSelected,
+      onSelectionChange,
+    ]
+  );
+
+  return {
+    expanded,
+    toggleExpanded,
+    selected,
+    toggleSelected,
+  };
+}

package/src/Tree.stories.tsx

@@ -0,0 +1,231 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tree } from "./Tree";
+import { TreeItem } from "./TreeItem";
+import {
+  checkboxIndicator,
+  radioIndicator,
+  SelectionReadout,
+} from "./storyData";
+
+const meta: Meta<typeof Tree> = {
+  title: "Really Under Development/Tree",
+  component: Tree,
+};
+
+export default meta;
+type Story = StoryObj<typeof Tree>;
+
+const Wrapper = ({ children }: { children: React.ReactNode }) => (
+  <div style={{ width: 400 }}>{children}</div>
+);
+
+export const Basic: Story = {
+  name: "Basic",
+  render: () => (
+    <Wrapper>
+      <Tree aria-label="File explorer" defaultExpanded={["src", "components"]}>
+        <TreeItem id="src" label="src">
+          <TreeItem id="components" label="components">
+            <TreeItem id="Button.tsx" label="Button.tsx" />
+            <TreeItem id="Modal.tsx" label="Modal.tsx" />
+            <TreeItem id="Tree.tsx" label="Tree.tsx" />
+          </TreeItem>
+          <TreeItem id="hooks" label="hooks">
+            <TreeItem id="useTree.ts" label="useTree.ts" />
+            <TreeItem id="useKey.ts" label="useKey.ts" />
+          </TreeItem>
+          <TreeItem id="index.ts" label="index.ts" />
+        </TreeItem>
+        <TreeItem id="package.json" label="package.json" />
+        <TreeItem id="tsconfig.json" label="tsconfig.json" />
+      </Tree>
+    </Wrapper>
+  ),
+};
+
+export const SingleSelection: Story = {
+  name: "Single selection (radio indicator)",
+  render: () => (
+    <Wrapper>
+      <Tree
+        aria-label="Pick a file"
+        selectionMode="single"
+        renderSelectionIndicator={radioIndicator}
+        defaultExpanded={["src", "components"]}
+        defaultSelected={["Button.tsx"]}
+      >
+        <TreeItem id="src" label="src">
+          <TreeItem id="components" label="components">
+            <TreeItem id="Button.tsx" label="Button.tsx" />
+            <TreeItem id="Modal.tsx" label="Modal.tsx" />
+            <TreeItem id="Tree.tsx" label="Tree.tsx" />
+          </TreeItem>
+          <TreeItem id="index.ts" label="index.ts" />
+        </TreeItem>
+      </Tree>
+    </Wrapper>
+  ),
+};
+
+export const MultipleSelection: Story = {
+  name: "Multiple selection (checkbox indicator)",
+  render: () => (
+    <Wrapper>
+      <Tree
+        aria-label="Pick files"
+        selectionMode="multiple"
+        renderSelectionIndicator={checkboxIndicator}
+        defaultExpanded={["src", "components"]}
+        defaultSelected={["Button.tsx", "Tree.tsx"]}
+      >
+        <TreeItem id="src" label="src">
+          <TreeItem id="components" label="components">
+            <TreeItem id="Button.tsx" label="Button.tsx" />
+            <TreeItem id="Modal.tsx" label="Modal.tsx" />
+            <TreeItem id="Tree.tsx" label="Tree.tsx" />
+          </TreeItem>
+          <TreeItem id="index.ts" label="index.ts" />
+        </TreeItem>
+      </Tree>
+    </Wrapper>
+  ),
+};
+
+export const LeavesOnlySelectable: Story = {
+  name: "Selectable nodes: leaves only",
+  render: () => (
+    <Wrapper>
+      <Tree
+        aria-label="Pick a file"
+        selectionMode="single"
+        selectableNodes="leaves"
+        renderSelectionIndicator={radioIndicator}
+        defaultExpanded={["src", "components"]}
+      >
+        <TreeItem id="src" label="src">
+          <TreeItem id="components" label="components">
+            <TreeItem id="Button.tsx" label="Button.tsx" />
+            <TreeItem id="Modal.tsx" label="Modal.tsx" />
+            <TreeItem id="Tree.tsx" label="Tree.tsx" />
+          </TreeItem>
+          <TreeItem id="index.ts" label="index.ts" />
+        </TreeItem>
+      </Tree>
+    </Wrapper>
+  ),
+};
+
+export const ControlledExpansion: Story = {
+  name: "Controlled expansion",
+  render: () => {
+    const [expanded, setExpanded] = React.useState<string[]>(["src"]);
+    return (
+      <Wrapper>
+        <div style={{ display: "flex", gap: 8, marginBottom: 12 }}>
+          <button onClick={() => setExpanded(["src", "components", "hooks"])}>
+            Expand all
+          </button>
+          <button onClick={() => setExpanded([])}>Collapse all</button>
+        </div>
+        <Tree
+          aria-label="Controlled tree"
+          expanded={expanded}
+          onExpandedChange={setExpanded}
+        >
+          <TreeItem id="src" label="src">
+            <TreeItem id="components" label="components">
+              <TreeItem id="Button.tsx" label="Button.tsx" />
+              <TreeItem id="Modal.tsx" label="Modal.tsx" />
+            </TreeItem>
+            <TreeItem id="hooks" label="hooks">
+              <TreeItem id="useTree.ts" label="useTree.ts" />
+            </TreeItem>
+          </TreeItem>
+        </Tree>
+      </Wrapper>
+    );
+  },
+};
+
+export const WithSelectionDisplay: Story = {
+  name: "With selection display",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>(["Button.tsx"]);
+    return (
+      <Wrapper>
+        <Tree
+          aria-label="Pick a file"
+          selectionMode="single"
+          renderSelectionIndicator={radioIndicator}
+          defaultExpanded={["src", "components"]}
+          selected={selected}
+          onSelectionChange={setSelected}
+        >
+          <TreeItem id="src" label="src">
+            <TreeItem id="components" label="components">
+              <TreeItem id="Button.tsx" label="Button.tsx" />
+              <TreeItem id="Modal.tsx" label="Modal.tsx" />
+              <TreeItem id="Tree.tsx" label="Tree.tsx" />
+            </TreeItem>
+            <TreeItem id="hooks" label="hooks">
+              <TreeItem id="useTree.ts" label="useTree.ts" />
+              <TreeItem id="useKey.ts" label="useKey.ts" />
+            </TreeItem>
+            <TreeItem id="index.ts" label="index.ts" />
+          </TreeItem>
+        </Tree>
+        <SelectionReadout selected={selected} />
+      </Wrapper>
+    );
+  },
+};
+
+export const MultiSelectionDisplay: Story = {
+  name: "With selection display (multi-select)",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([]);
+    return (
+      <Wrapper>
+        <Tree
+          aria-label="Pick files"
+          selectionMode="multiple"
+          renderSelectionIndicator={checkboxIndicator}
+          defaultExpanded={["src", "components"]}
+          selected={selected}
+          onSelectionChange={setSelected}
+        >
+          <TreeItem id="src" label="src">
+            <TreeItem id="components" label="components">
+              <TreeItem id="Button.tsx" label="Button.tsx" />
+              <TreeItem id="Modal.tsx" label="Modal.tsx" />
+              <TreeItem id="Tree.tsx" label="Tree.tsx" />
+            </TreeItem>
+            <TreeItem id="index.ts" label="index.ts" />
+          </TreeItem>
+        </Tree>
+        <SelectionReadout selected={selected} />
+      </Wrapper>
+    );
+  },
+};
+
+export const DisabledItems: Story = {
+  name: "Disabled items",
+  render: () => (
+    <Wrapper>
+      <Tree
+        aria-label="Tree with disabled items"
+        selectionMode="single"
+        renderSelectionIndicator={radioIndicator}
+        defaultExpanded={["src"]}
+      >
+        <TreeItem id="src" label="src">
+          <TreeItem id="Button.tsx" label="Button.tsx" />
+          <TreeItem id="Modal.tsx" label="Modal.tsx" disabled />
+          <TreeItem id="Tree.tsx" label="Tree.tsx" />
+        </TreeItem>
+      </Tree>
+    </Wrapper>
+  ),
+};

package/src/Tree.tsx

@@ -0,0 +1,181 @@
+import * as React from "react";
+import {
+  TreeContext,
+  TreeItemContext,
+  type TreeContextValue,
+} from "./Common/treeContext";
+import { useTreeState } from "./Common/useTreeState";
+import type {
+  TreeSelectableNodes,
+  TreeSelectionIndicator,
+  TreeSelectionMode,
+} from "./Common/types";
+import { TreeRoot } from "./TreeStyles";
+
+export type TreeProps = {
+  children: React.ReactNode;
+  /** Accessible name for the tree. One of `aria-label` / `aria-labelledby` is required. */
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+
+  selectionMode?: TreeSelectionMode;
+  selectableNodes?: TreeSelectableNodes;
+
+  defaultExpanded?: ReadonlyArray<string>;
+  expanded?: ReadonlyArray<string>;
+  onExpandedChange?: (expanded: string[]) => void;
+
+  defaultSelected?: ReadonlyArray<string>;
+  selected?: ReadonlyArray<string>;
+  onSelectionChange?: (selected: string[]) => void;
+
+  /**
+   * Optional render function for a per-item selection indicator (e.g. radio or
+   * checkbox). Returns null/undefined for no indicator.
+   */
+  renderSelectionIndicator?: TreeSelectionIndicator;
+
+  /** Item id to receive focus first; defaults to the first treeitem in DOM order. */
+  defaultFocusedId?: string;
+  /**
+   * Controlled focused id. When set, the host owns which item is "active" —
+   * the roving tabindex target in DOM-focus mode, or the `aria-activedescendant`
+   * target in `manageDomFocus={false}` mode.
+   */
+  focusedId?: string | null;
+  onFocusedIdChange?: (id: string | null) => void;
+
+  /**
+   * When `false`, Tree does not put treeitems in the tab order and does not
+   * call `.focus()` on them. Used by `TreeCombobox` so DOM focus can stay on
+   * its input while `focusedId` drives `aria-activedescendant`. Defaults to
+   * `true`.
+   */
+  manageDomFocus?: boolean;
+
+  className?: string;
+  id?: string;
+};
+
+export const Tree = React.forwardRef<HTMLUListElement, TreeProps>(function Tree(
+  props,
+  forwardedRef
+) {
+  const {
+    children,
+    selectionMode = "none",
+    selectableNodes = "all",
+    defaultExpanded,
+    expanded: expandedProp,
+    onExpandedChange,
+    defaultSelected,
+    selected: selectedProp,
+    onSelectionChange,
+    renderSelectionIndicator,
+    defaultFocusedId,
+    focusedId: focusedIdProp,
+    onFocusedIdChange,
+    manageDomFocus = true,
+    className,
+    id,
+  } = props;
+
+  const ariaLabel = props["aria-label"];
+  const ariaLabelledBy = props["aria-labelledby"];
+
+  const innerRef = React.useRef<HTMLUListElement>(null);
+  React.useImperativeHandle(forwardedRef, () => innerRef.current!, []);
+
+  const { expanded, toggleExpanded, selected, toggleSelected } = useTreeState({
+    selectionMode,
+    selectableNodes,
+    defaultExpanded,
+    expanded: expandedProp,
+    onExpandedChange,
+    defaultSelected,
+    selected: selectedProp,
+    onSelectionChange,
+  });
+
+  const isFocusedControlled = focusedIdProp !== undefined;
+  const [internalFocusedId, setInternalFocusedId] = React.useState<
+    string | null
+  >(defaultFocusedId ?? null);
+  const focusedId = isFocusedControlled
+    ? focusedIdProp ?? null
+    : internalFocusedId;
+
+  const setFocusedId = React.useCallback(
+    (nextId: string | null) => {
+      if (!isFocusedControlled) setInternalFocusedId(nextId);
+      onFocusedIdChange?.(nextId);
+    },
+    [isFocusedControlled, onFocusedIdChange]
+  );
+
+  const [hasFocused, setHasFocused] = React.useState(false);
+
+  // If the focused id points at an item that no longer exists in the DOM
+  // (e.g. it was filtered out by a wrapper), reset it to the first visible
+  // item so the tree always has a tabbable target. Without this, Tab into
+  // the tree lands nowhere and the user has to click to recover.
+  React.useLayoutEffect(() => {
+    const root = innerRef.current;
+    if (!root || focusedId === null) return;
+    const stillExists = root.querySelector(
+      `[role="treeitem"][data-treeitem-id="${CSS.escape(focusedId)}"]`
+    );
+    if (stillExists) return;
+    const firstVisible = root.querySelector<HTMLElement>('[role="treeitem"]');
+    setFocusedId(firstVisible?.dataset.treeitemId ?? null);
+  });
+
+  const ctxValue = React.useMemo<TreeContextValue>(
+    () => ({
+      focusedId,
+      setFocusedId,
+      expanded,
+      toggleExpanded,
+      selected,
+      toggleSelected,
+      selectionMode,
+      selectableNodes,
+      renderSelectionIndicator,
+      rootRef: innerRef,
+      hasFocused,
+      setHasFocused,
+      manageDomFocus,
+    }),
+    [
+      focusedId,
+      setFocusedId,
+      expanded,
+      toggleExpanded,
+      selected,
+      toggleSelected,
+      selectionMode,
+      selectableNodes,
+      renderSelectionIndicator,
+      hasFocused,
+      manageDomFocus,
+    ]
+  );
+
+  return (
+    <TreeContext.Provider value={ctxValue}>
+      <TreeItemContext.Provider value={{ level: 1 }}>
+        <TreeRoot
+          ref={innerRef}
+          role="tree"
+          id={id}
+          className={className}
+          aria-label={ariaLabel}
+          aria-labelledby={ariaLabelledBy}
+          aria-multiselectable={selectionMode === "multiple" ? true : undefined}
+        >
+          {children}
+        </TreeRoot>
+      </TreeItemContext.Provider>
+    </TreeContext.Provider>
+  );
+});

package/src/TreeCombobox.stories.tsx

@@ -0,0 +1,100 @@
+import React from "react";
+import styled from "styled-components";
+import type { Meta, StoryObj } from "@storybook/react";
+import { TreeCombobox } from "./TreeCombobox";
+import {
+  collections,
+  fileTree,
+  radioIndicator,
+  checkboxIndicator,
+  SelectionReadout,
+} from "./storyData";
+
+const meta: Meta<typeof TreeCombobox> = {
+  title: "Really Under Development/Tree/TreeCombobox",
+  component: TreeCombobox,
+};
+
+export default meta;
+type Story = StoryObj<typeof TreeCombobox>;
+
+const Card = styled.div`
+  width: 480px;
+  padding: ${({ theme }) => theme.space[400]};
+  border-radius: ${({ theme }) => theme.radii[500]};
+  border: 1px solid ${({ theme }) => theme.colors.container.border.base};
+  background: ${({ theme }) => theme.colors.container.background.base};
+`;
+
+export const Basic: Story = {
+  name: "Basic",
+  render: () => (
+    <Card>
+      <TreeCombobox
+        aria-label="File search"
+        items={fileTree}
+        placeholder="Search files..."
+      />
+    </Card>
+  ),
+};
+
+export const SingleSelect: Story = {
+  name: "Single select",
+  render: () => (
+    <Card>
+      <TreeCombobox
+        aria-label="Pick a collection"
+        items={collections}
+        placeholder="Search collections..."
+        selectionMode="single"
+        renderSelectionIndicator={radioIndicator}
+        defaultExpanded={["customer-care"]}
+        defaultSelected={["questions"]}
+      />
+    </Card>
+  ),
+};
+
+export const WithSelectionDisplay: Story = {
+  name: "With selection display",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>(["questions"]);
+    return (
+      <Card>
+        <TreeCombobox
+          aria-label="Pick a collection"
+          items={collections}
+          placeholder="Search collections..."
+          selectionMode="single"
+          renderSelectionIndicator={radioIndicator}
+          defaultExpanded={["customer-care"]}
+          selected={selected}
+          onSelectionChange={setSelected}
+        />
+        <SelectionReadout selected={selected} />
+      </Card>
+    );
+  },
+};
+
+export const MultiSelect: Story = {
+  name: "Multi-select",
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([]);
+    return (
+      <Card>
+        <TreeCombobox
+          aria-label="Pick files"
+          items={fileTree}
+          selectionMode="multiple"
+          renderSelectionIndicator={checkboxIndicator}
+          placeholder="Search..."
+          selected={selected}
+          onSelectionChange={setSelected}
+        />
+        <SelectionReadout selected={selected} />
+      </Card>
+    );
+  },
+};