@sproutsocial/seeds-react-tree 0.3.1

package/src/__tests__/Tree.test.tsx

@@ -0,0 +1,199 @@
+import * as React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import { Tree, TreeItem } from "..";
+
+function renderBasicTree(
+  props: Partial<React.ComponentProps<typeof Tree>> = {}
+) {
+  return render(
+    <Tree aria-label="Files" defaultExpanded={["src"]} {...props}>
+      <TreeItem id="src" label="src">
+        <TreeItem id="Button.tsx" label="Button.tsx" />
+        <TreeItem id="Modal.tsx" label="Modal.tsx" />
+      </TreeItem>
+      <TreeItem id="package.json" label="package.json" />
+    </Tree>
+  );
+}
+
+describe("Tree", () => {
+  it("renders WAI-ARIA roles and aria-level on items", () => {
+    renderBasicTree();
+    expect(screen.getByRole("tree", { name: "Files" })).toBeInTheDocument();
+
+    const srcItem = screen.getByRole("treeitem", { name: /src/ });
+    expect(srcItem).toHaveAttribute("aria-level", "1");
+    expect(srcItem).toHaveAttribute("aria-expanded", "true");
+
+    const childItem = screen.getByRole("treeitem", { name: /Button\.tsx/ });
+    expect(childItem).toHaveAttribute("aria-level", "2");
+    expect(childItem).not.toHaveAttribute("aria-expanded");
+  });
+
+  it("hides children of collapsed branches", () => {
+    renderBasicTree({ defaultExpanded: [] });
+    const srcItem = screen.getByRole("treeitem", { name: /src/ });
+    expect(srcItem).toHaveAttribute("aria-expanded", "false");
+    // Group should be hidden — query without checking visibility filter.
+    const childItem = screen.queryByRole("treeitem", {
+      name: /Button\.tsx/,
+      hidden: true,
+    });
+    expect(childItem).toBeInTheDocument();
+  });
+
+  it("uses roving tabindex with the first item tabbable by default", async () => {
+    renderBasicTree();
+    // Wait for the mount-time effect that assigns initial roving target.
+    const srcItem = screen.getByRole("treeitem", { name: /src/ });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(srcItem).toHaveAttribute("tabindex", "0");
+    expect(
+      screen.getByRole("treeitem", { name: /package\.json/ })
+    ).toHaveAttribute("tabindex", "-1");
+  });
+
+  it("ArrowRight expands a collapsed branch", async () => {
+    const { user } = renderBasicTree({ defaultExpanded: [] });
+    const srcItem = screen.getByRole("treeitem", { name: /src/ });
+    srcItem.focus();
+    await user.keyboard("{ArrowRight}");
+    expect(srcItem).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("ArrowLeft collapses an expanded branch", async () => {
+    const { user } = renderBasicTree({ defaultExpanded: ["src"] });
+    const srcItem = screen.getByRole("treeitem", { name: /src/ });
+    srcItem.focus();
+    await user.keyboard("{ArrowLeft}");
+    expect(srcItem).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("ArrowDown moves focus to the next visible item", async () => {
+    const { user } = renderBasicTree();
+    const srcItem = screen.getByRole("treeitem", { name: /src/ });
+    srcItem.focus();
+    await user.keyboard("{ArrowDown}");
+    expect(screen.getByRole("treeitem", { name: /Button\.tsx/ })).toHaveFocus();
+  });
+
+  it("Home/End jump to first/last visible item", async () => {
+    const { user } = renderBasicTree();
+    const last = screen.getByRole("treeitem", { name: /package\.json/ });
+    last.focus();
+    await user.keyboard("{Home}");
+    expect(screen.getByRole("treeitem", { name: /src/ })).toHaveFocus();
+    await user.keyboard("{End}");
+    expect(last).toHaveFocus();
+  });
+
+  it("Enter toggles selection in single-select mode", async () => {
+    const onChange = jest.fn();
+    const { user } = render(
+      <Tree
+        aria-label="Files"
+        selectionMode="single"
+        onSelectionChange={onChange}
+      >
+        <TreeItem id="a" label="A" />
+        <TreeItem id="b" label="B" />
+      </Tree>
+    );
+    const a = screen.getByRole("treeitem", { name: "A" });
+    a.focus();
+    await user.keyboard("{Enter}");
+    expect(onChange).toHaveBeenCalledWith(["a"]);
+    expect(a).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("multi-select uses aria-checked and accumulates selections", async () => {
+    const { user } = render(
+      <Tree aria-label="Files" selectionMode="multiple">
+        <TreeItem id="a" label="A" />
+        <TreeItem id="b" label="B" />
+      </Tree>
+    );
+    const a = screen.getByRole("treeitem", { name: "A" });
+    const b = screen.getByRole("treeitem", { name: "B" });
+    a.focus();
+    await user.keyboard("{Enter}");
+    b.focus();
+    await user.keyboard(" ");
+    expect(a).toHaveAttribute("aria-checked", "true");
+    expect(b).toHaveAttribute("aria-checked", "true");
+  });
+
+  it('selectableNodes="leaves" hides the selection indicator on parents', () => {
+    render(
+      <Tree
+        aria-label="Files"
+        selectionMode="single"
+        selectableNodes="leaves"
+        defaultExpanded={["src"]}
+        renderSelectionIndicator={() => (
+          <span data-testid="indicator">indicator</span>
+        )}
+      >
+        <TreeItem id="src" label="src">
+          <TreeItem id="leaf" label="Leaf" />
+        </TreeItem>
+      </Tree>
+    );
+    // Only the leaf gets an indicator; the parent doesn't.
+    const indicators = screen.getAllByTestId("indicator");
+    expect(indicators).toHaveLength(1);
+    const leaf = screen.getByRole("treeitem", { name: /Leaf/ });
+    expect(leaf).toContainElement(indicators[0]!);
+  });
+
+  it('selectableNodes="leaves" blocks parent selection', async () => {
+    const onChange = jest.fn();
+    const { user } = render(
+      <Tree
+        aria-label="Files"
+        selectionMode="single"
+        selectableNodes="leaves"
+        defaultExpanded={["src"]}
+        onSelectionChange={onChange}
+      >
+        <TreeItem id="src" label="src">
+          <TreeItem id="leaf" label="Leaf" />
+        </TreeItem>
+      </Tree>
+    );
+    const branch = screen.getByRole("treeitem", { name: /src/ });
+    branch.focus();
+    await user.keyboard("{Enter}");
+    expect(onChange).not.toHaveBeenCalled();
+
+    const leaf = screen.getByRole("treeitem", { name: /Leaf/ });
+    leaf.focus();
+    await user.keyboard("{Enter}");
+    expect(onChange).toHaveBeenCalledWith(["leaf"]);
+  });
+
+  it("disabled items are skipped and not selectable", async () => {
+    const onChange = jest.fn();
+    const { user } = render(
+      <Tree
+        aria-label="Files"
+        selectionMode="single"
+        onSelectionChange={onChange}
+      >
+        <TreeItem id="a" label="A" />
+        <TreeItem id="b" label="B" disabled />
+        <TreeItem id="c" label="C" />
+      </Tree>
+    );
+    const a = screen.getByRole("treeitem", { name: "A" });
+    a.focus();
+    await user.keyboard("{ArrowDown}");
+    // B is disabled, so focus skips to C.
+    expect(screen.getByRole("treeitem", { name: "C" })).toHaveFocus();
+  });
+
+  it("passes axe a11y check", async () => {
+    const { runA11yCheck } = renderBasicTree({ selectionMode: "single" });
+    await runA11yCheck();
+  });
+});

package/src/__tests__/TreeCombobox.test.tsx

@@ -0,0 +1,230 @@
+import * as React from "react";
+import { render, screen } from "@sproutsocial/seeds-react-testing-library";
+import { TreeCombobox } from "../TreeCombobox";
+import type { TreeItemData } from "../Common/types";
+
+const data: TreeItemData[] = [
+  {
+    id: "src",
+    label: "src",
+    children: [
+      { id: "Button.tsx", label: "Button.tsx" },
+      { id: "Modal.tsx", label: "Modal.tsx" },
+    ],
+  },
+  {
+    id: "tests",
+    label: "tests",
+    children: [{ id: "Button.test.tsx", label: "Button.test.tsx" }],
+  },
+];
+
+describe("TreeCombobox", () => {
+  it("renders the combobox role with the WAI-ARIA combobox wiring", () => {
+    render(<TreeCombobox aria-label="Files" items={data} />);
+    const input = screen.getByRole("combobox", { name: "Files" });
+    expect(input).toHaveAttribute("aria-autocomplete", "list");
+    expect(input).toHaveAttribute("aria-haspopup", "tree");
+    expect(input).toHaveAttribute("aria-expanded", "true");
+
+    const tree = screen.getByRole("tree", { name: "Files" });
+    expect(input.getAttribute("aria-controls")).toBe(tree.id);
+  });
+
+  it("renders all items when query is empty", () => {
+    render(<TreeCombobox aria-label="Files" items={data} />);
+    expect(screen.getByRole("treeitem", { name: /src/ })).toBeInTheDocument();
+    expect(screen.getByRole("treeitem", { name: /tests/ })).toBeInTheDocument();
+  });
+
+  it("filters items by label and auto-expands ancestors of matches", async () => {
+    const { user } = render(<TreeCombobox aria-label="Files" items={data} />);
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.type(input, "Modal");
+
+    expect(
+      screen.getByRole("treeitem", { name: /Modal\.tsx/ })
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByRole("treeitem", { name: /^Button\.tsx$/ })
+    ).not.toBeInTheDocument();
+
+    const src = screen.getByRole("treeitem", { name: /src/ });
+    expect(src).toHaveAttribute("aria-expanded", "true");
+    expect(
+      screen.queryByRole("treeitem", { name: /^tests$/ })
+    ).not.toBeInTheDocument();
+  });
+
+  it("restores user expansion state when query clears", async () => {
+    const { user } = render(
+      <TreeCombobox aria-label="Files" items={data} defaultExpanded={[]} />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.type(input, "Modal");
+    expect(screen.getByRole("treeitem", { name: /src/ })).toHaveAttribute(
+      "aria-expanded",
+      "true"
+    );
+
+    await user.clear(input);
+    expect(screen.getByRole("treeitem", { name: /src/ })).toHaveAttribute(
+      "aria-expanded",
+      "false"
+    );
+  });
+
+  it("shows the empty state and sets aria-expanded=false when no items match", async () => {
+    const { user } = render(
+      <TreeCombobox aria-label="Files" items={data} emptyText="Nothing here" />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.type(input, "zzzzz");
+    expect(screen.getByText("Nothing here")).toBeInTheDocument();
+    expect(input).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("Escape clears a non-empty query and the active descendant", async () => {
+    const { user } = render(<TreeCombobox aria-label="Files" items={data} />);
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    await user.type(input, "Mod");
+    await user.keyboard("{ArrowDown}");
+    expect(input).toHaveAttribute("aria-activedescendant");
+
+    await user.keyboard("{Escape}");
+    expect(input).toHaveValue("");
+    expect(input).not.toHaveAttribute("aria-activedescendant");
+  });
+
+  it("ArrowDown sets aria-activedescendant to the first visible item; subsequent arrows navigate", async () => {
+    const { user } = render(
+      <TreeCombobox aria-label="Files" items={data} defaultExpanded={["src"]} />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    await user.keyboard("{ArrowDown}");
+    expect(input).toHaveAttribute("aria-activedescendant", "src__item");
+
+    await user.keyboard("{ArrowDown}");
+    expect(input).toHaveAttribute("aria-activedescendant", "Button.tsx__item");
+
+    await user.keyboard("{ArrowUp}");
+    expect(input).toHaveAttribute("aria-activedescendant", "src__item");
+  });
+
+  it("ArrowRight expands a collapsed branch; ArrowLeft collapses an expanded branch", async () => {
+    const { user } = render(
+      <TreeCombobox aria-label="Files" items={data} defaultExpanded={[]} />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    await user.keyboard("{ArrowDown}");
+    expect(screen.getByRole("treeitem", { name: /src/ })).toHaveAttribute(
+      "aria-expanded",
+      "false"
+    );
+
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("treeitem", { name: /src/ })).toHaveAttribute(
+      "aria-expanded",
+      "true"
+    );
+
+    await user.keyboard("{ArrowLeft}");
+    expect(screen.getByRole("treeitem", { name: /src/ })).toHaveAttribute(
+      "aria-expanded",
+      "false"
+    );
+  });
+
+  it("DOM focus stays on the input across arrow keys", async () => {
+    const { user } = render(<TreeCombobox aria-label="Files" items={data} />);
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    await user.keyboard("{ArrowDown}{ArrowDown}{ArrowUp}");
+    expect(input).toHaveFocus();
+  });
+
+  it("treeitems are not in the tab order in combobox mode", () => {
+    render(
+      <TreeCombobox aria-label="Files" items={data} defaultExpanded={["src"]} />
+    );
+    const items = screen.getAllByRole("treeitem");
+    items.forEach((el) => {
+      expect(el).toHaveAttribute("tabindex", "-1");
+    });
+  });
+
+  it("Enter on the active item toggles single-select and fires onSelectionChange", async () => {
+    const onChange = jest.fn();
+    const { user } = render(
+      <TreeCombobox
+        aria-label="Files"
+        items={data}
+        defaultExpanded={["src"]}
+        selectionMode="single"
+        onSelectionChange={onChange}
+      />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    await user.keyboard("{ArrowDown}{ArrowDown}"); // src → Button.tsx
+    await user.keyboard("{Enter}");
+    expect(onChange).toHaveBeenLastCalledWith(["Button.tsx"]);
+  });
+
+  it("Enter on multi-select accumulates selections without closing or clearing the query", async () => {
+    const onChange = jest.fn();
+    const { user } = render(
+      <TreeCombobox
+        aria-label="Files"
+        items={data}
+        defaultExpanded={["src"]}
+        selectionMode="multiple"
+        onSelectionChange={onChange}
+      />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    await user.type(input, "tsx");
+    await user.keyboard("{ArrowDown}{ArrowDown}"); // src → Button.tsx
+    await user.keyboard("{Enter}");
+    expect(onChange).toHaveBeenLastCalledWith(["Button.tsx"]);
+
+    await user.keyboard("{ArrowDown}"); // Modal.tsx
+    await user.keyboard("{Enter}");
+    expect(onChange).toHaveBeenLastCalledWith(
+      expect.arrayContaining(["Button.tsx", "Modal.tsx"])
+    );
+    // Query and active descendant persist after Enter.
+    expect(input).toHaveValue("tsx");
+    expect(input).toHaveAttribute("aria-activedescendant", "Modal.tsx__item");
+  });
+
+  it("clicking a treeitem keeps focus on the input", async () => {
+    const onChange = jest.fn();
+    const { user } = render(
+      <TreeCombobox
+        aria-label="Files"
+        items={data}
+        defaultExpanded={["src"]}
+        selectionMode="single"
+        onSelectionChange={onChange}
+      />
+    );
+    const input = screen.getByRole("combobox", { name: "Files" });
+    await user.click(input);
+    const button = screen.getByRole("treeitem", { name: /Button\.tsx/ });
+    await user.click(button);
+    expect(input).toHaveFocus();
+    expect(onChange).toHaveBeenLastCalledWith(["Button.tsx"]);
+  });
+
+  it("passes axe a11y check", async () => {
+    const { runA11yCheck } = render(
+      <TreeCombobox aria-label="Files" items={data} />
+    );
+    await runA11yCheck();
+  });
+});

package/src/index.ts

@@ -0,0 +1,10 @@
+export { Tree, type TreeProps } from "./Tree";
+export { TreeItem, type TreeItemProps } from "./TreeItem";
+export { TreeCombobox, type TreeComboboxProps } from "./TreeCombobox";
+export type {
+  TreeItemData,
+  TreeSelectionMode,
+  TreeSelectableNodes,
+  TreeSelectionIndicator,
+  TreeSelectionIndicatorState,
+} from "./Common/types";

package/src/storyData.tsx

@@ -0,0 +1,166 @@
+import styled from "styled-components";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import type { TreeItemData, TreeSelectionIndicator } from "./Common/types";
+
+export const collections: TreeItemData[] = [
+  {
+    id: "customer-care",
+    label: "Customer care",
+    icon: <Icon name="headset-outline" size="small" />,
+    children: [
+      { id: "questions", label: "Questions & How-To", icon: <span>❓</span> },
+      { id: "bug-reports", label: "Bug Reports", icon: <span>🐛</span> },
+      {
+        id: "feature-requests",
+        label: "Feature Requests",
+        icon: <span>💡</span>,
+      },
+      {
+        id: "complaints",
+        label: "Complaints & Escalations",
+        icon: <span>😞</span>,
+      },
+    ],
+  },
+  {
+    id: "collection-b",
+    label: "Collection B",
+    icon: <Icon name="headset-outline" size="small" />,
+    children: [
+      { id: "b-1", label: "Topic One", icon: <span>📌</span> },
+      { id: "b-2", label: "Topic Two", icon: <span>📎</span> },
+    ],
+  },
+  {
+    id: "collection-c",
+    label: "Collection C",
+    icon: <Icon name="headset-outline" size="small" />,
+    children: [
+      { id: "c-1", label: "Alpha", icon: <span>🔤</span> },
+      { id: "c-2", label: "Beta", icon: <span>🔣</span> },
+    ],
+  },
+];
+
+export const fileTree: TreeItemData[] = [
+  {
+    id: "src",
+    label: "src",
+    children: [
+      {
+        id: "components",
+        label: "components",
+        children: [
+          { id: "Button.tsx", label: "Button.tsx" },
+          { id: "Modal.tsx", label: "Modal.tsx" },
+          { id: "Tree.tsx", label: "Tree.tsx" },
+        ],
+      },
+      {
+        id: "hooks",
+        label: "hooks",
+        children: [
+          { id: "useTree.ts", label: "useTree.ts" },
+          { id: "useKey.ts", label: "useKey.ts" },
+        ],
+      },
+      { id: "index.ts", label: "index.ts" },
+    ],
+  },
+  {
+    id: "package.json",
+    label: "package.json",
+  },
+  {
+    id: "tsconfig.json",
+    label: "tsconfig.json",
+  },
+];
+
+const RadioOuter = styled.span<{ $selected: boolean; $disabled: boolean }>`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  border: 2px solid
+    ${({ theme, $selected }) =>
+      $selected
+        ? theme.colors.form.border.selected
+        : theme.colors.form.border.base};
+  background: ${({ theme }) => theme.colors.form.background.base};
+  opacity: ${({ $disabled }) => ($disabled ? 0.4 : 1)};
+`;
+
+const RadioInner = styled.span`
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: ${({ theme }) => theme.colors.form.border.selected};
+`;
+
+export const radioIndicator: TreeSelectionIndicator = ({
+  selected,
+  disabled,
+}) => (
+  <RadioOuter $selected={selected} $disabled={disabled}>
+    {selected ? <RadioInner /> : null}
+  </RadioOuter>
+);
+
+const CheckboxOuter = styled.span<{ $selected: boolean; $disabled: boolean }>`
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 18px;
+  height: 18px;
+  border-radius: 4px;
+  border: 2px solid
+    ${({ theme, $selected }) =>
+      $selected
+        ? theme.colors.form.border.selected
+        : theme.colors.form.border.base};
+  background: ${({ theme, $selected }) =>
+    $selected
+      ? theme.colors.form.border.selected
+      : theme.colors.form.background.base};
+  color: ${({ theme }) => theme.colors.text.inverse};
+  opacity: ${({ $disabled }) => ($disabled ? 0.4 : 1)};
+`;
+
+export const checkboxIndicator: TreeSelectionIndicator = ({
+  selected,
+  disabled,
+}) => (
+  <CheckboxOuter $selected={selected} $disabled={disabled}>
+    {selected ? <Icon name="check-outline" size="small" /> : null}
+  </CheckboxOuter>
+);
+
+const ReadoutPanel = styled.div`
+  margin-top: ${({ theme }) => theme.space[400]};
+  padding: ${({ theme }) => theme.space[300]} ${({ theme }) => theme.space[400]};
+  border-radius: ${({ theme }) => theme.radii[400]};
+  background: ${({ theme }) => theme.colors.container.background.base};
+  border: 1px solid ${({ theme }) => theme.colors.container.border.base};
+  font-family: ${({ theme }) => theme.fontFamily};
+  ${({ theme }) => theme.typography[200]}
+  color: ${({ theme }) => theme.colors.text.body};
+`;
+
+const ReadoutLabel = styled.span`
+  font-weight: ${({ theme }) => theme.fontWeights.semibold};
+  margin-right: ${({ theme }) => theme.space[200]};
+`;
+
+export function SelectionReadout({ selected }: { selected: string[] }) {
+  return (
+    <ReadoutPanel aria-live="polite">
+      <ReadoutLabel>Selected:</ReadoutLabel>
+      {selected.length === 0 ? "(none)" : selected.join(", ")}
+    </ReadoutPanel>
+  );
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "@sproutsocial/seeds-tsconfig/react-library.json",
+  "compilerOptions": {
+    "noImplicitAny": false,
+    "noUncheckedIndexedAccess": false,
+    "baseUrl": ".",
+    "types": ["@testing-library/jest-dom"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.stories.tsx", "**/*.stories.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig((options) => ({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  clean: true,
+  legacyOutput: true,
+  dts: options.dts,
+  sourcemap: true,
+  external: ["react", "styled-components", /^@sproutsocial\//],
+  metafile: options.metafile,
+}));