@primitiv-ui/react 0.1.38 → 0.1.39

package/src/Tree/README.md

@@ -1,403 +0,0 @@
-# Tree
-
-A compound component for a **hierarchical tree view** — nested
-collapsible groups of selectable rows, modelled on the WAI-ARIA tree
-pattern.
-
-```tsx
-import { Tree } from "@primitiv-ui/react";
-
-<Tree.Root defaultExpandedValues={["src"]}>
-  <Tree.Item value="readme">readme</Tree.Item>
-  <Tree.Branch value="src">
-    <Tree.BranchControl>
-      <Tree.BranchIndicator>▸</Tree.BranchIndicator>
-      src
-    </Tree.BranchControl>
-    <Tree.BranchContent>
-      <Tree.Item value="index">index.ts</Tree.Item>
-      <Tree.Item value="button">button.tsx</Tree.Item>
-    </Tree.BranchContent>
-  </Tree.Branch>
-</Tree.Root>;
-```
-
-## Authoring model
-
-The tree is authored by **recursive composition** — there is no `data`
-prop. An `Item` is a leaf; a `Branch` is a parent that pairs a
-`<Tree.BranchControl>` (its clickable row) with a `<Tree.BranchContent>`
-(the nested group). Each `BranchContent` renders its children one
-nesting level deeper, so a `Branch` placed inside a `BranchContent`
-automatically reports `aria-level={depth + 1}` and `data-depth={depth}`.
-
-Depth and parent value ride a context — the components don't traverse
-the React tree to figure out where they are.
-
-## Sub-components
-
-| Export                 | Role                  | Notes                                                                                                                                             |
-| ---------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| `Tree.Root`            | State owner           | Owns expansion + selection, the collection, and the roving tabstop. `role="tree"`, `data-selection-mode`, `aria-multiselectable` in multiple mode |
-| `Tree.Item`            | Leaf treeitem         | `role="treeitem"`. Supports `label`, `disabled`, `asChild`                                                                                        |
-| `Tree.Branch`          | Branch treeitem       | `role="treeitem"` containing the control row and (when expanded) the content group. Supports `label`, `disabled`                                  |
-| `Tree.BranchControl`   | Branch row            | The clickable row inside a `Branch`. Click toggles expansion **and** selects. Supports `asChild`                                                  |
-| `Tree.BranchContent`   | Branch group          | `role="group"`. Mount/unmount with the branch, or stay mounted via `forceMount` for CSS animation                                                 |
-| `Tree.BranchIndicator` | Chevron / glyph       | Decorative `aria-hidden` span with `data-state="open"                                                                                             | "closed"`. Supports `asChild` |
-| `Tree.SelectionPath`   | Selection breadcrumbs | Renders one breadcrumb trail per currently-selected value. See [Selection path](#selection-path)                                                  |
-
-## State model
-
-The Root carries two independent state axes — expansion and selection —
-each statically discriminated into controlled and uncontrolled forms.
-Passing both `default*` and the controlled prop is a type error.
-
-### Expansion
-
-```ts
-// Uncontrolled
-<Tree.Root defaultExpandedValues={["src"]} onExpandedChange={(v) => ...}>
-
-// Controlled
-<Tree.Root expandedValues={values} onExpandedChange={setValues}>
-```
-
-`onExpandedChange` fires in both modes.
-
-### Selection
-
-The selection shape depends on `selectionMode`:
-
-```ts
-// Single (default) — selectedValue is `string | null`
-<Tree.Root defaultSelectedValue="readme" onSelectedValueChange={(v) => ...}>
-<Tree.Root selectedValue={v} onSelectedValueChange={setV}>
-
-// Multiple — selectedValues is `string[]`
-<Tree.Root
-  selectionMode="multiple"
-  defaultSelectedValues={["readme", "index"]}
-  onSelectedValuesChange={(v) => ...}
->
-<Tree.Root
-  selectionMode="multiple"
-  selectedValues={v}
-  onSelectedValuesChange={setV}
->
-```
-
-In **multiple** mode:
-
-- Plain click replaces selection with the clicked item.
-- `Ctrl` / `Cmd` + click toggles the item in or out.
-- `Shift` + click selects the contiguous range of visible items
-  between the previous click (the _anchor_) and the clicked item,
-  skipping disabled items. The anchor stays put across Shift+clicks,
-  matching the listbox convention.
-
-In **single** mode modifier keys are ignored — clicks always replace.
-
-## `forceMount` (animating branches in and out)
-
-By default a collapsed branch's content is unmounted. Pass `forceMount`
-to `BranchContent` to keep it in the DOM with `aria-hidden="true"` and
-`data-state="closed"` so CSS transitions can play:
-
-```tsx
-<Tree.Branch value="src">
-  <Tree.BranchControl>src</Tree.BranchControl>
-  <Tree.BranchContent forceMount>
-    <Tree.Item value="index">index.ts</Tree.Item>
-  </Tree.BranchContent>
-</Tree.Branch>
-```
-
-The default form mirrors the rest of the library; `forceMount` mirrors
-`Collapsible.Content`. Choose based on whether your styling needs an
-enter/exit animation.
-
-## Keyboard interaction
-
-The whole tree is a single roving-tabindex widget — exactly one item
-is tabbable at a time. The tabstop follows the last-focused item and
-defaults to the first enabled visible item.
-
-| Key                     | Leaf `Item`             | `Branch`                                                   |
-| ----------------------- | ----------------------- | ---------------------------------------------------------- |
-| `ArrowUp` / `ArrowDown` | Previous / next visible | Previous / next visible                                    |
-| `Home` / `End`          | First / last visible    | First / last visible                                       |
-| `ArrowRight`            | No-op                   | Collapsed: expand. Expanded: focus the first child         |
-| `ArrowLeft`             | Focus the parent branch | Expanded: collapse. Collapsed: focus the parent branch     |
-| `Enter` / `Space`       | Select                  | Toggle expansion **and** select (same as clicking the row) |
-
-Arrow keys skip disabled items. Home / End and direct focus still land
-on them so they remain discoverable.
-
-## ARIA
-
-- The root is `role="tree"` with `aria-multiselectable="true"` in
-  multiple mode.
-- Items and branches are `role="treeitem"` with `aria-level` (1-based),
-  `aria-selected`, and — on branches — `aria-expanded` and
-  `aria-labelledby` pointing at the `BranchControl` (so the branch's
-  accessible name is just the row's content, not all descendant text).
-- The nested content group is `role="group"`.
-- Indicators are `aria-hidden="true"`.
-
-## Styling hooks
-
-The component ships **no CSS**. Style with the data attributes:
-
-| Attribute                        | Where                             | Meaning                                                   |
-| -------------------------------- | --------------------------------- | --------------------------------------------------------- | ------------------------- |
-| `data-selection-mode="single     | multiple"`                        | `Root`                                                    | The active selection mode |
-| `data-depth="N"`                 | `Item`, `Branch`, `BranchContent` | Zero-based nesting depth                                  |
-| `data-leaf=""`                   | `Item`                            | Marks a leaf treeitem                                     |
-| `data-branch=""`                 | `Branch`                          | Marks a branch treeitem                                   |
-| `data-state="open                | closed"`                          | `Branch`, `BranchContent`, indicators                     | Branch expansion state    |
-| `data-selected=""`               | `Item`, `Branch`                  | Set when the treeitem is selected                         |
-| `data-disabled=""`               | `Item`, `Branch`, segments        | Set when the treeitem (or breadcrumb segment) is disabled |
-| `data-tree-selection-path=""`    | `SelectionPath` wrapper           | Identifies the breadcrumb trail container                 |
-| `data-empty=""`                  | `SelectionPath` wrapper           | Set when no item is selected                              |
-| `data-tree-selection-segment=""` | `SelectionPath` segments          | One per crumb in the trail; carries `data-value`          |
-
-Indentation, guide lines, focus rings, and the chevron rotation are
-the consumer's job. The `data-depth` attribute combined with modern
-CSS (`attr(data-depth type(<integer>))` or `[data-depth="N"]`
-selectors) is enough to drive an indented hierarchy without inline
-styles.
-
-> **Browser support note.** Reading a typed attribute through
-> `attr(data-depth type(<integer>))` inside `calc()` requires Chrome
-> 133+ or Safari 18.2+. Firefox does not yet ship the advanced
-> `attr()` syntax — it will fall back to the default value supplied
-> as the second argument (or `0` if omitted). Two cross-browser
-> workarounds:
->
-> **1. Enumerate per-depth rules** — pick a sensible cap for your UI
-> and write one selector per level:
->
-> ```css
-> [role="treeitem"][data-depth="0"] > .row {
->   padding-inline-start: 0.5rem;
-> }
-> [role="treeitem"][data-depth="1"] > .row {
->   padding-inline-start: 1.75rem;
-> }
-> [role="treeitem"][data-depth="2"] > .row {
->   padding-inline-start: 3rem;
-> }
-> /* ...extend as deep as your tree can go */
-> ```
->
-> **2. Set a CSS variable inline from the render layer** — the
-> consumer already knows the depth when authoring the tree
-> recursively, so it can be threaded through as a prop:
->
-> ```tsx
-> function Node({ node, depth }: { node: FileNode; depth: number }) {
->   const indent = { "--tree-indent": depth } as React.CSSProperties;
->   if (node.children) {
->     return (
->       <Tree.Branch value={node.id}>
->         <Tree.BranchControl style={indent}>{node.label}</Tree.BranchControl>
->         <Tree.BranchContent>
->           {node.children.map((child) => (
->             <Node key={child.id} node={child} depth={depth + 1} />
->           ))}
->         </Tree.BranchContent>
->       </Tree.Branch>
->     );
->   }
->   return (
->     <Tree.Item value={node.id} style={indent}>
->       {node.label}
->     </Tree.Item>
->   );
-> }
-> ```
->
-> ```css
-> [role="treeitem"] > .row {
->   padding-inline-start: calc(var(--tree-indent, 0) * 1.25rem + 0.5rem);
-> }
-> ```
-
-## Wrapping Tree in a styled layer
-
-`Tree.Branch` finds its control and content by **inspecting its children before
-rendering them**, so it sees the component you wrote — not what that component
-renders. A styling layer that wraps each part in its own component to attach
-classes is therefore invisible to it, and the branch throws:
-
-```
-A Tree.Branch must contain a <Tree.BranchControl>.
-```
-
-Set `TREE_PART` on the wrapper and it partitions like the part it renders:
-
-```tsx
-import { TREE_PART, Tree } from "@primitiv-ui/react";
-
-function StyledBranchControl(props: TreeBranchControlProps) {
-  return <Tree.BranchControl {...props} className="row" />;
-}
-StyledBranchControl[TREE_PART] = "branch-control";
-
-function StyledBranchContent(props: TreeBranchContentProps) {
-  return <Tree.BranchContent {...props} className="group" />;
-}
-StyledBranchContent[TREE_PART] = "branch-content";
-```
-
-The accepted names are `"branch-control"` and `"branch-content"`
-(`TreePartName`). Only these two parts need it — every other part is found by
-position or context, not by inspection. The one-control and one-content rules
-still apply: two marked controls in a branch is still an error.
-
-This is what the registry `tree` component does; no other primitive in the
-library needs a marker, because none of the others read their children's types.
-
-### Indenting without `attr()`
-
-`useTreeLevel()` returns `{ depth }` — `0` directly under `Tree.Root`, one
-deeper per enclosing `BranchContent`. A styling layer needs the depth as a
-*number* to apply the indent as the **row's own padding**, which is what keeps
-each row's box full-width so a hover or selected band runs edge to edge rather
-than starting at the nested level. Reading `data-depth` back in CSS would need
-`attr(data-depth type(<integer>))` — Chrome 133+ / Safari 18.2+, unsupported in
-Firefox — so the depth is exposed here instead.
-
-```tsx
-function StyledItem(props: TreeItemProps) {
-  const { depth } = useTreeLevel();
-  return (
-    <Tree.Item
-      {...props}
-      style={{ "--depth": depth } as CSSProperties}
-      className="row"
-    />
-  );
-}
-```
-
-```css
-.row {
-  padding-inline-start: calc(var(--depth, 0) * 1.25rem + 0.5rem);
-}
-```
-
-## Selection path
-
-`Tree.Item` and `Tree.Branch` accept an optional `label` prop. It does
-**not** affect what's rendered for the row — the children still do —
-but it is stored alongside the value in Tree's node registry so the
-tree can surface a human-readable breadcrumb trail of the current
-selection.
-
-```tsx
-<Tree.Branch value="src" label="src">
-  <Tree.BranchControl>📁 src</Tree.BranchControl>
-  <Tree.BranchContent>
-    <Tree.Item value="index" label="index.ts">
-      📄 index.ts
-    </Tree.Item>
-  </Tree.BranchContent>
-</Tree.Branch>
-```
-
-### `Tree.SelectionPath`
-
-The out-of-box subcomponent renders one breadcrumb trail per
-currently-selected value, composing the package's `Breadcrumb`
-primitive: a `<nav aria-label="Breadcrumb"><ol>` per path, with
-non-final segments as plain `<li>` text and the leaf as a
-`Breadcrumb.Page` (`aria-current="page"`). Segments without a
-`label` prop fall back to their `value`.
-
-```tsx
-import { Tree } from "@primitiv-ui/react";
-import { ChevronRight } from "@primitiv-ui/icons";
-
-<Tree.Root defaultSelectedValue="index">
-  ...
-  <Tree.SelectionPath separator={<ChevronRight />} />
-</Tree.Root>;
-```
-
-When no item is selected, the wrapper still renders with
-`data-empty=""` so consumers can style a placeholder (e.g. an em-dash
-via `::before`) without scoping the path bar conditionally.
-
-For full control over the markup — wiring router links, custom
-ordering, or grouping multiple selections — pass a function as
-`children`. It receives the resolved paths and replaces the default
-rendering entirely:
-
-```tsx
-<Tree.SelectionPath>
-  {({ paths }) =>
-    paths.map((path, i) => (
-      <Breadcrumb.Root key={i}>
-        <Breadcrumb.List>
-          {path.map((seg) => (
-            <Breadcrumb.Item key={seg.value}>
-              <Breadcrumb.Link asChild>
-                <RouterLink to={`/files/${seg.value}`}>
-                  {seg.label ?? seg.value}
-                </RouterLink>
-              </Breadcrumb.Link>
-            </Breadcrumb.Item>
-          ))}
-        </Breadcrumb.List>
-      </Breadcrumb.Root>
-    ))
-  }
-</Tree.SelectionPath>
-```
-
-### `useTreePath` / `useTreeSelectionPaths`
-
-For UIs that don't fit the breadcrumb shape, two hooks expose the raw
-path data:
-
-```ts
-import { useTreePath, useTreeSelectionPaths } from "@primitiv-ui/react";
-
-const path = useTreePath(value); // root → leaf for one value
-const paths = useTreeSelectionPaths(); // one path per selected value, in selection order
-```
-
-Both return arrays of `TreePathSegment`:
-
-```ts
-type TreePathSegment = {
-  value: string;
-  label: string | null; // falls back to `null` when no `label` prop was supplied
-  isBranch: boolean;
-  disabled: boolean;
-  depth: number;
-};
-```
-
-Paths survive a branch collapsing without `forceMount`: Tree keeps a
-durable copy of every node's metadata so ancestry remains resolvable
-even after descendants unmount. A value that has never mounted (e.g.
-a pre-selected item whose branch has not yet opened) returns an empty
-array.
-
-## Disabled items
-
-Pass `disabled` on an `Item` or `Branch` to render `aria-disabled` and
-`data-disabled`, ignore clicks and activation keys, and skip the item
-during arrow-key navigation and range selection. Disabled items remain
-in the DOM and focusable for discovery; `Home` / `End` still reach
-them.
-
-## Deferred past v1
-
-- Type-ahead (printable-character focus search).
-- Keyboard multi-select chords (`Ctrl+Enter`, `Shift+Arrow`, `Ctrl+A`).
-- Drag-to-reorder.
-- Imperative `expandAll` / `collapseAll` ref API.
-- Lazy / async children loading.