@hjmds/design-contracts 0.8.2

package/dist/tree-select.js

@@ -0,0 +1,132 @@
+import { flattenTreeNodes, validateTreeNodes } from "./tree.js";
+function leafIdsOf(nodes) {
+    return new Set(flattenTreeNodes(nodes)
+        .filter((node) => node.children === undefined)
+        .map((node) => node.id));
+}
+/**
+ * A parent's own id is never meaningfully "in" the checked set — its
+ * checked/unchecked/mixed state is always derived from its descendant
+ * leaves, the same way a DataTable header is never itself a row in
+ * `selectedKeys`. Storing a parent id here would be ambiguous (does it mean
+ * "all children" or "just this category, independent of children"?) with no
+ * measured product need to resolve that ambiguity, so it is rejected instead
+ * of guessed at.
+ */
+export function validateTreeCheckedSelection(nodes, checkedKeys) {
+    validateTreeNodes(nodes);
+    const leafIds = leafIdsOf(nodes);
+    for (const key of checkedKeys) {
+        if (!leafIds.has(key)) {
+            throw new RangeError(`TreeSelect checkedKeys must reference an existing leaf node id, not a parent or unknown id: ${key}`);
+        }
+    }
+}
+function combineCoverage(a, b) {
+    return { enabled: a.enabled + b.enabled, checked: a.checked + b.checked };
+}
+function coverageToState(coverage) {
+    if (coverage.enabled === 0 || coverage.checked === 0)
+        return false;
+    return coverage.checked === coverage.enabled ? true : "mixed";
+}
+/**
+ * One depth-first pass computing every node's tri-state at once — the same
+ * "resolve the whole tree once, filter afterward" shape `resolveTreeDescriptor`
+ * already uses for depth/position, rather than re-walking per node.
+ *
+ * A parent's aggregate is computed from *enabled descendant leaf coverage*,
+ * exactly generalizing `resolveDataTableSelectAllState`'s "disabled rows are
+ * excluded from both the denominator and the count." A disabled leaf keeps
+ * its own literal `checkedKeys.has(id)` as its individual displayed state
+ * (a disabled checkbox can still visibly be checked), but never counts
+ * toward any ancestor's true/false/mixed — otherwise a single
+ * disabled-and-unchecked leaf would permanently pin every ancestor to
+ * "mixed" even once all of its enabled siblings are checked.
+ */
+export function resolveTreeCheckedStates(nodes, checkedKeys) {
+    validateTreeCheckedSelection(nodes, checkedKeys);
+    const states = new Map();
+    const visit = (node) => {
+        if (node.children === undefined) {
+            const checked = checkedKeys.has(node.id);
+            states.set(node.id, checked);
+            return node.disabled
+                ? { enabled: 0, checked: 0 }
+                : { enabled: 1, checked: checked ? 1 : 0 };
+        }
+        const coverage = node.children
+            .map(visit)
+            .reduce(combineCoverage, { enabled: 0, checked: 0 });
+        states.set(node.id, coverageToState(coverage));
+        return coverage;
+    };
+    for (const node of nodes)
+        visit(node);
+    return states;
+}
+/**
+ * Checking or unchecking any node (leaf or parent) sets every enabled
+ * descendant leaf to the opposite of "fully checked" — the same
+ * mixed-defaults-to-checked convention `getCheckboxNextState` already uses
+ * for a single aggregate Checkbox (`src/behaviors.ts`). Disabled leaves are
+ * left untouched, mirroring `toggleCheckboxSelection`'s own disabled guard.
+ * This is "the rule where selecting a parent selects the children together,"
+ * made unambiguous by the fact that parents are never independently stored.
+ */
+export function toggleTreeCheckedSelection(nodes, checkedKeys, targetId) {
+    const states = resolveTreeCheckedStates(nodes, checkedKeys);
+    const currentState = states.get(targetId);
+    if (currentState === undefined) {
+        throw new RangeError(`Tree node must exist: ${targetId}`);
+    }
+    const flattened = flattenTreeNodes(nodes);
+    const target = flattened.find((node) => node.id === targetId);
+    const descendantLeaves = (target.children ? flattenTreeNodes(target.children) : [target]).filter((node) => node.children === undefined);
+    const nextChecked = currentState !== true;
+    const next = new Set(checkedKeys);
+    for (const leaf of descendantLeaves) {
+        if (leaf.disabled)
+            continue;
+        if (nextChecked)
+            next.add(leaf.id);
+        else
+            next.delete(leaf.id);
+    }
+    return next;
+}
+/**
+ * Drops leaf ids that left the tree or stopped being leaves — the same
+ * shape as `reconcileCheckboxSelection`/`reconcileTreeExpansion`. Returns the
+ * same reference when nothing changed.
+ */
+export function reconcileTreeCheckedSelection(nodes, checkedKeys) {
+    validateTreeNodes(nodes);
+    const leafIds = leafIdsOf(nodes);
+    const reconciled = [...checkedKeys].filter((id) => leafIds.has(id));
+    return reconciled.length === checkedKeys.size ? checkedKeys : new Set(reconciled);
+}
+/**
+ * No new recipe file: the surface composes three *existing* recipes
+ * unchanged — Select's trigger/frame (`selectRecipe`), Tree's row anatomy
+ * (`treeRecipe.node`/`.toggle`/`.indentPerLevel`) for each popup row, and the
+ * existing Checkbox mark for the tri-state indicator this module derives.
+ * Declaring a fourth "treeSelectRecipe" would just alias tokens the other
+ * three already own.
+ *
+ * No new behaviorRegistry entry either: TreeSelect's open/dismiss reasons,
+ * roles, and keyboard model are `behaviorRegistry.select` verbatim — this
+ * module only adds the functions above, which a Select+Tree renderer calls
+ * to compute per-row checkbox state and to interpret a row's checkbox
+ * activation.
+ */
+export const treeSelectBehaviorScenarios = [
+    "single-select-mode-needs-none-of-this-module-selectedkey-and-flat-items-are-enough",
+    "checking-an-unchecked-parent-checks-every-enabled-descendant-leaf",
+    "unchecking-a-fully-checked-parent-unchecks-every-enabled-descendant-leaf",
+    "a-parent-with-some-but-not-all-descendant-leaves-checked-renders-mixed",
+    "disabled-leaves-are-skipped-by-cascade-toggle-but-still-counted-by-derivation",
+    "checkedkeys-containing-a-parent-or-unknown-id-is-rejected-not-silently-ignored",
+    "removing-a-checked-leaf-from-the-tree-reconciles-it-out-without-touching-siblings",
+];
+//# sourceMappingURL=tree-select.js.map

package/dist/tree-select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-select.js","sourceRoot":"","sources":["../src/tree-select.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CheckboxState } from \"./behaviors.js\";\nimport { flattenTreeNodes, validateTreeNodes, type TreeNodeDescriptor } from \"./tree.js\";\n\n/**\n * `docs/tree.md`'s own \"TreeSelect 판정\" concludes TreeSelect is Select's\n * surface (trigger + popup/sheet, committed value) plus Tree's collection\n * (depth/sibling announcement, arrow-key expand/collapse, `expandedKeys`\n * reconciliation) — no third primitive. That verdict is right for\n * **single-select** TreeSelect: picking exactly one node needs nothing\n * beyond Select's existing `selectedKey: Id | null` and Tree's flat item\n * list, because there is nothing to aggregate.\n *\n * It is incomplete for **multiple-select** TreeSelect (checkboxes at every\n * depth). Neither file solves \"a parent's checkbox must show a third,\n * aggregate state when only some of its descendant leaves are checked\" —\n * that is not a new selection model, it is `resolveDataTableSelectAllState`\n * (`src/data-table.ts`) generalized from one level (header ↔ rows) to\n * recursive depth (parent ↔ every descendant leaf), reusing the exact same\n * `CheckboxState` (`boolean | \"mixed\"`) the header checkbox already renders.\n * This module is that one missing piece — nothing else.\n */\nexport type TreeCheckedKeys<Id extends string = string> = ReadonlySet<Id>;\n\nfunction leafIdsOf<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n): ReadonlySet<Id> {\n  return new Set(\n    flattenTreeNodes(nodes)\n      .filter((node) => node.children === undefined)\n      .map((node) => node.id),\n  );\n}\n\n/**\n * A parent's own id is never meaningfully \"in\" the checked set — its\n * checked/unchecked/mixed state is always derived from its descendant\n * leaves, the same way a DataTable header is never itself a row in\n * `selectedKeys`. Storing a parent id here would be ambiguous (does it mean\n * \"all children\" or \"just this category, independent of children\"?) with no\n * measured product need to resolve that ambiguity, so it is rejected instead\n * of guessed at.\n */\nexport function validateTreeCheckedSelection<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n  checkedKeys: TreeCheckedKeys<Id>,\n): void {\n  validateTreeNodes(nodes);\n  const leafIds = leafIdsOf(nodes);\n  for (const key of checkedKeys) {\n    if (!leafIds.has(key)) {\n      throw new RangeError(\n        `TreeSelect checkedKeys must reference an existing leaf node id, not a parent or unknown id: ${key}`,\n      );\n    }\n  }\n}\n\ntype LeafCoverage = Readonly<{ enabled: number; checked: number }>;\n\nfunction combineCoverage(a: LeafCoverage, b: LeafCoverage): LeafCoverage {\n  return { enabled: a.enabled + b.enabled, checked: a.checked + b.checked };\n}\n\nfunction coverageToState(coverage: LeafCoverage): CheckboxState {\n  if (coverage.enabled === 0 || coverage.checked === 0) return false;\n  return coverage.checked === coverage.enabled ? true : \"mixed\";\n}\n\n/**\n * One depth-first pass computing every node's tri-state at once — the same\n * \"resolve the whole tree once, filter afterward\" shape `resolveTreeDescriptor`\n * already uses for depth/position, rather than re-walking per node.\n *\n * A parent's aggregate is computed from *enabled descendant leaf coverage*,\n * exactly generalizing `resolveDataTableSelectAllState`'s \"disabled rows are\n * excluded from both the denominator and the count.\" A disabled leaf keeps\n * its own literal `checkedKeys.has(id)` as its individual displayed state\n * (a disabled checkbox can still visibly be checked), but never counts\n * toward any ancestor's true/false/mixed — otherwise a single\n * disabled-and-unchecked leaf would permanently pin every ancestor to\n * \"mixed\" even once all of its enabled siblings are checked.\n */\nexport function resolveTreeCheckedStates<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n  checkedKeys: TreeCheckedKeys<Id>,\n): ReadonlyMap<Id, CheckboxState> {\n  validateTreeCheckedSelection(nodes, checkedKeys);\n\n  const states = new Map<Id, CheckboxState>();\n  const visit = (node: TreeNodeDescriptor<Id>): LeafCoverage => {\n    if (node.children === undefined) {\n      const checked = checkedKeys.has(node.id);\n      states.set(node.id, checked);\n      return node.disabled\n        ? { enabled: 0, checked: 0 }\n        : { enabled: 1, checked: checked ? 1 : 0 };\n    }\n    const coverage = node.children\n      .map(visit)\n      .reduce(combineCoverage, { enabled: 0, checked: 0 });\n    states.set(node.id, coverageToState(coverage));\n    return coverage;\n  };\n  for (const node of nodes) visit(node);\n  return states;\n}\n\n/**\n * Checking or unchecking any node (leaf or parent) sets every enabled\n * descendant leaf to the opposite of \"fully checked\" — the same\n * mixed-defaults-to-checked convention `getCheckboxNextState` already uses\n * for a single aggregate Checkbox (`src/behaviors.ts`). Disabled leaves are\n * left untouched, mirroring `toggleCheckboxSelection`'s own disabled guard.\n * This is \"the rule where selecting a parent selects the children together,\"\n * made unambiguous by the fact that parents are never independently stored.\n */\nexport function toggleTreeCheckedSelection<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n  checkedKeys: TreeCheckedKeys<Id>,\n  targetId: Id,\n): TreeCheckedKeys<Id> {\n  const states = resolveTreeCheckedStates(nodes, checkedKeys);\n  const currentState = states.get(targetId);\n  if (currentState === undefined) {\n    throw new RangeError(`Tree node must exist: ${targetId}`);\n  }\n\n  const flattened = flattenTreeNodes(nodes);\n  const target = flattened.find((node) => node.id === targetId)!;\n  const descendantLeaves = (\n    target.children ? flattenTreeNodes(target.children) : [target]\n  ).filter((node) => node.children === undefined);\n\n  const nextChecked = currentState !== true;\n  const next = new Set(checkedKeys);\n  for (const leaf of descendantLeaves) {\n    if (leaf.disabled) continue;\n    if (nextChecked) next.add(leaf.id);\n    else next.delete(leaf.id);\n  }\n  return next;\n}\n\n/**\n * Drops leaf ids that left the tree or stopped being leaves — the same\n * shape as `reconcileCheckboxSelection`/`reconcileTreeExpansion`. Returns the\n * same reference when nothing changed.\n */\nexport function reconcileTreeCheckedSelection<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n  checkedKeys: TreeCheckedKeys<Id>,\n): TreeCheckedKeys<Id> {\n  validateTreeNodes(nodes);\n  const leafIds = leafIdsOf(nodes);\n  const reconciled = [...checkedKeys].filter((id) => leafIds.has(id));\n  return reconciled.length === checkedKeys.size ? checkedKeys : new Set(reconciled);\n}\n\n/**\n * No new recipe file: the surface composes three *existing* recipes\n * unchanged — Select's trigger/frame (`selectRecipe`), Tree's row anatomy\n * (`treeRecipe.node`/`.toggle`/`.indentPerLevel`) for each popup row, and the\n * existing Checkbox mark for the tri-state indicator this module derives.\n * Declaring a fourth \"treeSelectRecipe\" would just alias tokens the other\n * three already own.\n *\n * No new behaviorRegistry entry either: TreeSelect's open/dismiss reasons,\n * roles, and keyboard model are `behaviorRegistry.select` verbatim — this\n * module only adds the functions above, which a Select+Tree renderer calls\n * to compute per-row checkbox state and to interpret a row's checkbox\n * activation.\n */\nexport const treeSelectBehaviorScenarios = [\n  \"single-select-mode-needs-none-of-this-module-selectedkey-and-flat-items-are-enough\",\n  \"checking-an-unchecked-parent-checks-every-enabled-descendant-leaf\",\n  \"unchecking-a-fully-checked-parent-unchecks-every-enabled-descendant-leaf\",\n  \"a-parent-with-some-but-not-all-descendant-leaves-checked-renders-mixed\",\n  \"disabled-leaves-are-skipped-by-cascade-toggle-but-still-counted-by-derivation\",\n  \"checkedkeys-containing-a-parent-or-unknown-id-is-rejected-not-silently-ignored\",\n  \"removing-a-checked-leaf-from-the-tree-reconciles-it-out-without-touching-siblings\",\n] as const;\n"]}

package/dist/tree.d.ts

@@ -0,0 +1,206 @@
+import type { AsyncCollectionState, CollectionItemDescriptor, CollectionSelectionModel, SelectionDirection, WebKeyboardKey } from "./behaviors.js";
+import { type CollectionNavigationIntent, type CollectionTypeaheadOptions } from "./collection.js";
+/**
+ * Ant Design Tree's drag-to-reorder is intentionally not reproduced — no
+ * measured product need exists yet, and it is a materially harder contract
+ * (drop-position semantics, cross-parent move validation) that should not be
+ * guessed at ahead of a real screen. See docs/tree.md.
+ */
+export type TreeNodeDescriptor<Id extends string = string> = Omit<CollectionItemDescriptor<Id>, "shortcut" | "tone"> & Readonly<{
+    /** Absent on a leaf. Never an empty array — a node either has no children or at least one. */
+    children?: readonly TreeNodeDescriptor<Id>[];
+}>;
+export type TreeSelectionModel<Id extends string = string> = CollectionSelectionModel<Id>;
+export type TreeAsyncState = AsyncCollectionState;
+/** Checks one node's own fields; does not recurse — validateTreeNodes walks the whole tree. */
+export declare function validateTreeNode<Id extends string>(node: TreeNodeDescriptor<Id>): void;
+/** Depth-first flatten of every node at every depth, parents before children. */
+export declare function flattenTreeNodes<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[]): readonly TreeNodeDescriptor<Id>[];
+/**
+ * `TreeNodeDescriptor` is `CollectionItemDescriptor` plus recursion, so the
+ * flattened list is passed straight into the existing `validateCollection`
+ * for base-contract checks (non-empty label/textValue, globally unique id)
+ * instead of re-implementing them. Only the structural checks that
+ * `validateCollection`'s fixed two-level `{items} | {sections}` shape cannot
+ * express — id whitespace, the empty-children rule, and the recursion itself
+ * — are new here.
+ */
+export declare function validateTreeNodes<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[]): void;
+/**
+ * Drops expanded keys that no longer identify an expandable node — removed
+ * since the last render, or a leaf that never had children — the same way
+ * `reconcileCheckboxSelection` drops selected ids that left the collection.
+ * Returns the same reference when nothing changed.
+ */
+export declare function reconcileTreeExpansion<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[], expandedKeys: ReadonlySet<Id>): ReadonlySet<Id>;
+export type TreeAccessibleNameInfo = Readonly<{
+    /** 1-indexed; root nodes are depth 1. */
+    depth: number;
+    /** 1-indexed position among this node's own siblings, not the whole flattened tree. */
+    position: number;
+    siblingCount: number;
+    label: string;
+    hasChildren: boolean;
+    expanded: boolean;
+}>;
+/**
+ * Products own phrase order and whether/how "펼쳐짐"/"collapsed" is said for
+ * a leaf (`hasChildren` lets the composer skip that clause entirely) — same
+ * reason Steps, Timeline, and Carousel do not assemble their own accessible
+ * name.
+ */
+export type ComposeTreeAccessibleName = (info: TreeAccessibleNameInfo) => string;
+export type ResolvedTreeNodeDescriptor<Id extends string = string> = Omit<TreeNodeDescriptor<Id>, "children"> & Readonly<{
+    depth: number;
+    position: number;
+    siblingCount: number;
+    parentId: Id | null;
+    hasChildren: boolean;
+    /** Always false when `hasChildren` is false — a leaf has no expansion state. */
+    expanded: boolean;
+    /** False when any ancestor is collapsed. A renderer may still choose to keep it mounted-but-hidden. */
+    visible: boolean;
+    accessibleName: string;
+}>;
+export type ResolveTreeOptions = Readonly<{
+    composeAccessibleName: ComposeTreeAccessibleName;
+}>;
+/**
+ * Flattens the whole tree (not only the visible part) and attaches depth,
+ * sibling position, parent linkage, expansion, visibility, and the composed
+ * accessible name. Callers filter `.visible` for rendering and for the
+ * navigation helpers below — one resolved array is the single source both
+ * consult, the same relationship Tabs' resolved panel list has to its mount
+ * policy.
+ */
+export declare function resolveTreeDescriptor<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[], expandedKeys: ReadonlySet<Id>, options: ResolveTreeOptions): readonly ResolvedTreeNodeDescriptor<Id>[];
+export type TreeArrowKeyIntent = "expand" | "collapse";
+/**
+ * ArrowRight/ArrowLeft carry opposite meaning in RTL, the same translation
+ * `getSelectionNavigationIntent` already applies for CheckboxGroup/RadioGroup
+ * orientation. Every other key (Up/Down/Home/End/Typeahead) is a linear-list
+ * problem Tree does not re-solve — see getVisibleTreeNodes below.
+ */
+export declare function getTreeArrowKeyIntent(key: WebKeyboardKey, direction: SelectionDirection): TreeArrowKeyIntent | undefined;
+export type TreeArrowResult<Id extends string = string> = Readonly<{
+    action: "expand" | "collapse";
+}> | Readonly<{
+    action: "moveFocus";
+    targetId: Id;
+}> | Readonly<{
+    action: "none";
+}>;
+/**
+ * Resolves the WAI-ARIA tree pattern for the pressed arrow: expand or move
+ * into the first child; collapse or move to the parent. `disabled` never
+ * gates this — it only gates selection eligibility (CollectionItemDescriptor
+ * precedent), a node's children stay explorable either way.
+ */
+export declare function getTreeArrowResult<Id extends string>(visible: readonly ResolvedTreeNodeDescriptor<Id>[], currentId: Id, intent: TreeArrowKeyIntent): TreeArrowResult<Id>;
+/**
+ * Vertical movement across the currently visible nodes only — a collapsed
+ * subtree's descendants are absent from `visible`, so this needs no Tree-
+ * specific math at all: `getCollectionNavigationTarget` (disabled-skip, no
+ * loop) already does exactly this for Menu/Select, and a resolved,
+ * `.visible`-filtered node list satisfies `CollectionItemDescriptor` because
+ * it is one, plus extra fields.
+ */
+export declare function getVisibleTreeNavigationTarget<Id extends string>(visible: readonly ResolvedTreeNodeDescriptor<Id>[], currentId: Id | null | undefined, intent: CollectionNavigationIntent): Id | undefined;
+/** Same reuse for typeahead: only currently visible nodes are matchable. */
+export declare function getVisibleTreeTypeaheadMatch<Id extends string>(visible: readonly ResolvedTreeNodeDescriptor<Id>[], query: string, options?: CollectionTypeaheadOptions<Id>): Id | undefined;
+export declare const treeBehaviorDefaults: {
+    readonly loop: false;
+};
+export declare const treeBehavior: {
+    readonly controlled: readonly ["expandedKeys", "defaultExpandedKeys", "onExpandedKeysChange", "selection", "asyncState"];
+    readonly defaults: {
+        readonly loop: false;
+    };
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled"];
+        readonly value: readonly ["selected", "expanded"];
+        readonly content: readonly ["idle", "loading", "loadingMore", "empty", "error"];
+    };
+    readonly web: {
+        readonly roles: readonly ["tree", "treeitem", "group"];
+        readonly keyboard: readonly ["Tab", "Enter", "Space", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "Typeahead"];
+        readonly focus: "roving";
+    };
+    /** Tree is Web-only per catalog platform classification — no native surface, matching Breadcrumb and Tooltip. */
+    readonly native: {
+        readonly roles: readonly [];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["depth-and-sibling-position-are-announced-not-only-visual-indent", "arrow-expands-or-moves-to-the-first-child-arrow-collapses-or-moves-to-the-parent-respecting-rtl", "up-down-home-end-move-across-visible-nodes-only-collapsed-subtrees-are-skipped", "typeahead-matches-only-currently-visible-nodes", "disabled-gates-selection-only-expand-and-collapse-remain-available", "empty-children-array-is-rejected-a-node-either-omits-children-or-lists-at-least-one", "one-tab-stop-per-node-the-expand-collapse-glyph-is-decorative-not-a-nested-control", "drag-reorder-is-out-of-scope-until-a-real-product-need-exists"];
+};
+export declare const treeRecipe: {
+    readonly slots: readonly ["root", "node", "toggle", "indent", "label", "description"];
+    readonly indentPerLevel: 20;
+    /** Reuses the same row chrome Menu/Select items already use instead of inventing new selection-row visuals. */
+    readonly node: {
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 12;
+        readonly gap: 12;
+        readonly radius: "md";
+        readonly label: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly textVariant: "body";
+        };
+        readonly description: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textMuted";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly highlightedBackground: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly selectedBackground: Readonly<{
+            source: "theme";
+            key: "primary";
+            alpha?: number;
+        }>;
+        readonly selectedIndicator: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly danger: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+    };
+    readonly toggle: {
+        readonly size: "sm";
+        readonly icons: {
+            readonly collapsed: "chevronEnd";
+            readonly expanded: "chevronDown";
+        };
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly hitTarget: 44;
+    };
+};
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"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"}

package/dist/tree.js

@@ -0,0 +1,223 @@
+import { getCollectionNavigationTarget, getCollectionTypeaheadMatch, validateCollection, } from "./collection.js";
+import { collectionItemContract } from "./component-contracts.js";
+import { control, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+function assertNonEmpty(value, field) {
+    if (value.trim().length === 0) {
+        throw new TypeError(`Tree ${field} must not be empty`);
+    }
+}
+/** Checks one node's own fields; does not recurse — validateTreeNodes walks the whole tree. */
+export function validateTreeNode(node) {
+    assertNonEmpty(node.id, "node id");
+    if (node.id !== node.id.trim()) {
+        throw new TypeError("Tree node id must not start or end with whitespace");
+    }
+    assertNonEmpty(node.label, "node label");
+    assertNonEmpty(node.textValue, "node textValue");
+    if (node.description !== undefined) {
+        assertNonEmpty(node.description, "node description");
+    }
+    if (node.children !== undefined && node.children.length === 0) {
+        throw new TypeError(`Tree node ${node.id} children must not be an empty array — omit children instead`);
+    }
+}
+/** Depth-first flatten of every node at every depth, parents before children. */
+export function flattenTreeNodes(nodes) {
+    return nodes.flatMap((node) => [
+        node,
+        ...(node.children ? flattenTreeNodes(node.children) : []),
+    ]);
+}
+/**
+ * `TreeNodeDescriptor` is `CollectionItemDescriptor` plus recursion, so the
+ * flattened list is passed straight into the existing `validateCollection`
+ * for base-contract checks (non-empty label/textValue, globally unique id)
+ * instead of re-implementing them. Only the structural checks that
+ * `validateCollection`'s fixed two-level `{items} | {sections}` shape cannot
+ * express — id whitespace, the empty-children rule, and the recursion itself
+ * — are new here.
+ */
+export function validateTreeNodes(nodes) {
+    if (nodes.length === 0) {
+        throw new RangeError("Tree must contain at least one root node");
+    }
+    const flattened = flattenTreeNodes(nodes);
+    for (const node of flattened) {
+        validateTreeNode(node);
+    }
+    validateCollection({ items: flattened });
+}
+/**
+ * Drops expanded keys that no longer identify an expandable node — removed
+ * since the last render, or a leaf that never had children — the same way
+ * `reconcileCheckboxSelection` drops selected ids that left the collection.
+ * Returns the same reference when nothing changed.
+ */
+export function reconcileTreeExpansion(nodes, expandedKeys) {
+    const expandable = new Set(flattenTreeNodes(nodes)
+        .filter((node) => node.children !== undefined)
+        .map((node) => node.id));
+    const reconciled = [...expandedKeys].filter((id) => expandable.has(id));
+    return reconciled.length === expandedKeys.size ? expandedKeys : new Set(reconciled);
+}
+/**
+ * Flattens the whole tree (not only the visible part) and attaches depth,
+ * sibling position, parent linkage, expansion, visibility, and the composed
+ * accessible name. Callers filter `.visible` for rendering and for the
+ * navigation helpers below — one resolved array is the single source both
+ * consult, the same relationship Tabs' resolved panel list has to its mount
+ * policy.
+ */
+export function resolveTreeDescriptor(nodes, expandedKeys, options) {
+    validateTreeNodes(nodes);
+    if (typeof options.composeAccessibleName !== "function") {
+        throw new TypeError("Tree composeAccessibleName must be a function");
+    }
+    const resolved = [];
+    const walk = (siblings, depth, parentId, parentVisible) => {
+        siblings.forEach((node, index) => {
+            const hasChildren = node.children !== undefined;
+            const expanded = hasChildren && expandedKeys.has(node.id);
+            const position = index + 1;
+            const siblingCount = siblings.length;
+            const accessibleName = options.composeAccessibleName({
+                depth,
+                position,
+                siblingCount,
+                label: node.label,
+                hasChildren,
+                expanded,
+            });
+            if (typeof accessibleName !== "string" || accessibleName.trim().length === 0) {
+                throw new TypeError("Tree composeAccessibleName must return a non-empty string");
+            }
+            const { children, ...rest } = node;
+            resolved.push({
+                ...rest,
+                depth,
+                position,
+                siblingCount,
+                parentId,
+                hasChildren,
+                expanded,
+                visible: parentVisible,
+                accessibleName,
+            });
+            if (children) {
+                walk(children, depth + 1, node.id, parentVisible && expanded);
+            }
+        });
+    };
+    walk(nodes, 1, null, true);
+    return resolved;
+}
+/**
+ * ArrowRight/ArrowLeft carry opposite meaning in RTL, the same translation
+ * `getSelectionNavigationIntent` already applies for CheckboxGroup/RadioGroup
+ * orientation. Every other key (Up/Down/Home/End/Typeahead) is a linear-list
+ * problem Tree does not re-solve — see getVisibleTreeNodes below.
+ */
+export function getTreeArrowKeyIntent(key, direction) {
+    if (key === "ArrowRight")
+        return direction === "rtl" ? "collapse" : "expand";
+    if (key === "ArrowLeft")
+        return direction === "rtl" ? "expand" : "collapse";
+    return undefined;
+}
+/**
+ * Resolves the WAI-ARIA tree pattern for the pressed arrow: expand or move
+ * into the first child; collapse or move to the parent. `disabled` never
+ * gates this — it only gates selection eligibility (CollectionItemDescriptor
+ * precedent), a node's children stay explorable either way.
+ */
+export function getTreeArrowResult(visible, currentId, intent) {
+    const node = visible.find((candidate) => candidate.id === currentId);
+    if (!node) {
+        throw new RangeError(`Tree node must be visible to receive arrow input: ${String(currentId)}`);
+    }
+    if (intent === "expand") {
+        if (!node.hasChildren)
+            return { action: "none" };
+        if (!node.expanded)
+            return { action: "expand" };
+        const firstChild = visible.find((candidate) => candidate.parentId === node.id && candidate.position === 1);
+        return firstChild ? { action: "moveFocus", targetId: firstChild.id } : { action: "none" };
+    }
+    if (node.hasChildren && node.expanded)
+        return { action: "collapse" };
+    if (node.parentId !== null)
+        return { action: "moveFocus", targetId: node.parentId };
+    return { action: "none" };
+}
+/**
+ * Vertical movement across the currently visible nodes only — a collapsed
+ * subtree's descendants are absent from `visible`, so this needs no Tree-
+ * specific math at all: `getCollectionNavigationTarget` (disabled-skip, no
+ * loop) already does exactly this for Menu/Select, and a resolved,
+ * `.visible`-filtered node list satisfies `CollectionItemDescriptor` because
+ * it is one, plus extra fields.
+ */
+export function getVisibleTreeNavigationTarget(visible, currentId, intent) {
+    return getCollectionNavigationTarget({ items: visible }, currentId, intent, false);
+}
+/** Same reuse for typeahead: only currently visible nodes are matchable. */
+export function getVisibleTreeTypeaheadMatch(visible, query, options) {
+    return getCollectionTypeaheadMatch({ items: visible }, query, options);
+}
+export const treeBehaviorDefaults = {
+    loop: false,
+};
+export const treeBehavior = {
+    controlled: ["expandedKeys", "defaultExpandedKeys", "onExpandedKeysChange", "selection", "asyncState"],
+    defaults: treeBehaviorDefaults,
+    stateAxes: {
+        availability: ["enabled", "disabled"],
+        value: ["selected", "expanded"],
+        content: ["idle", "loading", "loadingMore", "empty", "error"],
+    },
+    web: {
+        roles: ["tree", "treeitem", "group"],
+        keyboard: [
+            "Tab",
+            "Enter",
+            "Space",
+            "ArrowUp",
+            "ArrowDown",
+            "ArrowLeft",
+            "ArrowRight",
+            "Home",
+            "End",
+            "Typeahead",
+        ],
+        focus: "roving",
+    },
+    /** Tree is Web-only per catalog platform classification — no native surface, matching Breadcrumb and Tooltip. */
+    native: { roles: [], states: [], actions: [] },
+    scenarios: [
+        "depth-and-sibling-position-are-announced-not-only-visual-indent",
+        "arrow-expands-or-moves-to-the-first-child-arrow-collapses-or-moves-to-the-parent-respecting-rtl",
+        "up-down-home-end-move-across-visible-nodes-only-collapsed-subtrees-are-skipped",
+        "typeahead-matches-only-currently-visible-nodes",
+        "disabled-gates-selection-only-expand-and-collapse-remain-available",
+        "empty-children-array-is-rejected-a-node-either-omits-children-or-lists-at-least-one",
+        "one-tab-stop-per-node-the-expand-collapse-glyph-is-decorative-not-a-nested-control",
+        "drag-reorder-is-out-of-scope-until-a-real-product-need-exists",
+    ],
+};
+export const treeRecipe = {
+    slots: ["root", "node", "toggle", "indent", "label", "description"],
+    indentPerLevel: spacing.lg,
+    /** Reuses the same row chrome Menu/Select items already use instead of inventing new selection-row visuals. */
+    node: collectionItemContract,
+    toggle: {
+        size: "sm",
+        icons: {
+            collapsed: "chevronEnd",
+            expanded: "chevronDown",
+        },
+        color: semanticColors.content.secondary,
+        hitTarget: control.minTouchTarget,
+    },
+};
+//# sourceMappingURL=tree.js.map

package/dist/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  AsyncCollectionState,\n  BehaviorContract,\n  CollectionItemDescriptor,\n  CollectionSelectionModel,\n  SelectionDirection,\n  WebKeyboardKey,\n} from \"./behaviors.js\";\nimport {\n  getCollectionNavigationTarget,\n  getCollectionTypeaheadMatch,\n  validateCollection,\n  type CollectionNavigationIntent,\n  type CollectionTypeaheadOptions,\n} from \"./collection.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport type { SemanticIconName } from \"./icon.js\";\nimport { collectionItemContract } from \"./component-contracts.js\";\nimport { control, spacing } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Ant Design Tree's drag-to-reorder is intentionally not reproduced — no\n * measured product need exists yet, and it is a materially harder contract\n * (drop-position semantics, cross-parent move validation) that should not be\n * guessed at ahead of a real screen. See docs/tree.md.\n */\nexport type TreeNodeDescriptor<Id extends string = string> = Omit<\n  CollectionItemDescriptor<Id>,\n  \"shortcut\" | \"tone\"\n> &\n  Readonly<{\n    /** Absent on a leaf. Never an empty array — a node either has no children or at least one. */\n    children?: readonly TreeNodeDescriptor<Id>[];\n  }>;\n\nexport type TreeSelectionModel<Id extends string = string> = CollectionSelectionModel<Id>;\nexport type TreeAsyncState = AsyncCollectionState;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`Tree ${field} must not be empty`);\n  }\n}\n\n/** Checks one node's own fields; does not recurse — validateTreeNodes walks the whole tree. */\nexport function validateTreeNode<Id extends string>(node: TreeNodeDescriptor<Id>): void {\n  assertNonEmpty(node.id, \"node id\");\n  if (node.id !== node.id.trim()) {\n    throw new TypeError(\"Tree node id must not start or end with whitespace\");\n  }\n  assertNonEmpty(node.label, \"node label\");\n  assertNonEmpty(node.textValue, \"node textValue\");\n  if (node.description !== undefined) {\n    assertNonEmpty(node.description, \"node description\");\n  }\n  if (node.children !== undefined && node.children.length === 0) {\n    throw new TypeError(\n      `Tree node ${node.id} children must not be an empty array — omit children instead`,\n    );\n  }\n}\n\n/** Depth-first flatten of every node at every depth, parents before children. */\nexport function flattenTreeNodes<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n): readonly TreeNodeDescriptor<Id>[] {\n  return nodes.flatMap((node) => [\n    node,\n    ...(node.children ? flattenTreeNodes(node.children) : []),\n  ]);\n}\n\n/**\n * `TreeNodeDescriptor` is `CollectionItemDescriptor` plus recursion, so the\n * flattened list is passed straight into the existing `validateCollection`\n * for base-contract checks (non-empty label/textValue, globally unique id)\n * instead of re-implementing them. Only the structural checks that\n * `validateCollection`'s fixed two-level `{items} | {sections}` shape cannot\n * express — id whitespace, the empty-children rule, and the recursion itself\n * — are new here.\n */\nexport function validateTreeNodes<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n): void {\n  if (nodes.length === 0) {\n    throw new RangeError(\"Tree must contain at least one root node\");\n  }\n  const flattened = flattenTreeNodes(nodes);\n  for (const node of flattened) {\n    validateTreeNode(node);\n  }\n  validateCollection({ items: flattened });\n}\n\n/**\n * Drops expanded keys that no longer identify an expandable node — removed\n * since the last render, or a leaf that never had children — the same way\n * `reconcileCheckboxSelection` drops selected ids that left the collection.\n * Returns the same reference when nothing changed.\n */\nexport function reconcileTreeExpansion<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n  expandedKeys: ReadonlySet<Id>,\n): ReadonlySet<Id> {\n  const expandable = new Set(\n    flattenTreeNodes(nodes)\n      .filter((node) => node.children !== undefined)\n      .map((node) => node.id),\n  );\n  const reconciled = [...expandedKeys].filter((id) => expandable.has(id));\n  return reconciled.length === expandedKeys.size ? expandedKeys : new Set(reconciled);\n}\n\nexport type TreeAccessibleNameInfo = Readonly<{\n  /** 1-indexed; root nodes are depth 1. */\n  depth: number;\n  /** 1-indexed position among this node's own siblings, not the whole flattened tree. */\n  position: number;\n  siblingCount: number;\n  label: string;\n  hasChildren: boolean;\n  expanded: boolean;\n}>;\n\n/**\n * Products own phrase order and whether/how \"펼쳐짐\"/\"collapsed\" is said for\n * a leaf (`hasChildren` lets the composer skip that clause entirely) — same\n * reason Steps, Timeline, and Carousel do not assemble their own accessible\n * name.\n */\nexport type ComposeTreeAccessibleName = (info: TreeAccessibleNameInfo) => string;\n\nexport type ResolvedTreeNodeDescriptor<Id extends string = string> = Omit<\n  TreeNodeDescriptor<Id>,\n  \"children\"\n> &\n  Readonly<{\n    depth: number;\n    position: number;\n    siblingCount: number;\n    parentId: Id | null;\n    hasChildren: boolean;\n    /** Always false when `hasChildren` is false — a leaf has no expansion state. */\n    expanded: boolean;\n    /** False when any ancestor is collapsed. A renderer may still choose to keep it mounted-but-hidden. */\n    visible: boolean;\n    accessibleName: string;\n  }>;\n\nexport type ResolveTreeOptions = Readonly<{\n  composeAccessibleName: ComposeTreeAccessibleName;\n}>;\n\n/**\n * Flattens the whole tree (not only the visible part) and attaches depth,\n * sibling position, parent linkage, expansion, visibility, and the composed\n * accessible name. Callers filter `.visible` for rendering and for the\n * navigation helpers below — one resolved array is the single source both\n * consult, the same relationship Tabs' resolved panel list has to its mount\n * policy.\n */\nexport function resolveTreeDescriptor<Id extends string>(\n  nodes: readonly TreeNodeDescriptor<Id>[],\n  expandedKeys: ReadonlySet<Id>,\n  options: ResolveTreeOptions,\n): readonly ResolvedTreeNodeDescriptor<Id>[] {\n  validateTreeNodes(nodes);\n  if (typeof options.composeAccessibleName !== \"function\") {\n    throw new TypeError(\"Tree composeAccessibleName must be a function\");\n  }\n\n  const resolved: ResolvedTreeNodeDescriptor<Id>[] = [];\n  const walk = (\n    siblings: readonly TreeNodeDescriptor<Id>[],\n    depth: number,\n    parentId: Id | null,\n    parentVisible: boolean,\n  ): void => {\n    siblings.forEach((node, index) => {\n      const hasChildren = node.children !== undefined;\n      const expanded = hasChildren && expandedKeys.has(node.id);\n      const position = index + 1;\n      const siblingCount = siblings.length;\n      const accessibleName = options.composeAccessibleName({\n        depth,\n        position,\n        siblingCount,\n        label: node.label,\n        hasChildren,\n        expanded,\n      });\n      if (typeof accessibleName !== \"string\" || accessibleName.trim().length === 0) {\n        throw new TypeError(\n          \"Tree composeAccessibleName must return a non-empty string\",\n        );\n      }\n      const { children, ...rest } = node;\n      resolved.push({\n        ...rest,\n        depth,\n        position,\n        siblingCount,\n        parentId,\n        hasChildren,\n        expanded,\n        visible: parentVisible,\n        accessibleName,\n      });\n      if (children) {\n        walk(children, depth + 1, node.id, parentVisible && expanded);\n      }\n    });\n  };\n  walk(nodes, 1, null, true);\n  return resolved;\n}\n\nexport type TreeArrowKeyIntent = \"expand\" | \"collapse\";\n\n/**\n * ArrowRight/ArrowLeft carry opposite meaning in RTL, the same translation\n * `getSelectionNavigationIntent` already applies for CheckboxGroup/RadioGroup\n * orientation. Every other key (Up/Down/Home/End/Typeahead) is a linear-list\n * problem Tree does not re-solve — see getVisibleTreeNodes below.\n */\nexport function getTreeArrowKeyIntent(\n  key: WebKeyboardKey,\n  direction: SelectionDirection,\n): TreeArrowKeyIntent | undefined {\n  if (key === \"ArrowRight\") return direction === \"rtl\" ? \"collapse\" : \"expand\";\n  if (key === \"ArrowLeft\") return direction === \"rtl\" ? \"expand\" : \"collapse\";\n  return undefined;\n}\n\nexport type TreeArrowResult<Id extends string = string> =\n  | Readonly<{ action: \"expand\" | \"collapse\" }>\n  | Readonly<{ action: \"moveFocus\"; targetId: Id }>\n  | Readonly<{ action: \"none\" }>;\n\n/**\n * Resolves the WAI-ARIA tree pattern for the pressed arrow: expand or move\n * into the first child; collapse or move to the parent. `disabled` never\n * gates this — it only gates selection eligibility (CollectionItemDescriptor\n * precedent), a node's children stay explorable either way.\n */\nexport function getTreeArrowResult<Id extends string>(\n  visible: readonly ResolvedTreeNodeDescriptor<Id>[],\n  currentId: Id,\n  intent: TreeArrowKeyIntent,\n): TreeArrowResult<Id> {\n  const node = visible.find((candidate) => candidate.id === currentId);\n  if (!node) {\n    throw new RangeError(`Tree node must be visible to receive arrow input: ${String(currentId)}`);\n  }\n  if (intent === \"expand\") {\n    if (!node.hasChildren) return { action: \"none\" };\n    if (!node.expanded) return { action: \"expand\" };\n    const firstChild = visible.find(\n      (candidate) => candidate.parentId === node.id && candidate.position === 1,\n    );\n    return firstChild ? { action: \"moveFocus\", targetId: firstChild.id } : { action: \"none\" };\n  }\n  if (node.hasChildren && node.expanded) return { action: \"collapse\" };\n  if (node.parentId !== null) return { action: \"moveFocus\", targetId: node.parentId };\n  return { action: \"none\" };\n}\n\n/**\n * Vertical movement across the currently visible nodes only — a collapsed\n * subtree's descendants are absent from `visible`, so this needs no Tree-\n * specific math at all: `getCollectionNavigationTarget` (disabled-skip, no\n * loop) already does exactly this for Menu/Select, and a resolved,\n * `.visible`-filtered node list satisfies `CollectionItemDescriptor` because\n * it is one, plus extra fields.\n */\nexport function getVisibleTreeNavigationTarget<Id extends string>(\n  visible: readonly ResolvedTreeNodeDescriptor<Id>[],\n  currentId: Id | null | undefined,\n  intent: CollectionNavigationIntent,\n): Id | undefined {\n  return getCollectionNavigationTarget({ items: visible }, currentId, intent, false);\n}\n\n/** Same reuse for typeahead: only currently visible nodes are matchable. */\nexport function getVisibleTreeTypeaheadMatch<Id extends string>(\n  visible: readonly ResolvedTreeNodeDescriptor<Id>[],\n  query: string,\n  options?: CollectionTypeaheadOptions<Id>,\n): Id | undefined {\n  return getCollectionTypeaheadMatch({ items: visible }, query, options);\n}\n\nexport const treeBehaviorDefaults = {\n  loop: false,\n} as const satisfies Readonly<{ loop: boolean }>;\n\nexport const treeBehavior = {\n  controlled: [\"expandedKeys\", \"defaultExpandedKeys\", \"onExpandedKeysChange\", \"selection\", \"asyncState\"],\n  defaults: treeBehaviorDefaults,\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\"],\n    value: [\"selected\", \"expanded\"],\n    content: [\"idle\", \"loading\", \"loadingMore\", \"empty\", \"error\"],\n  },\n  web: {\n    roles: [\"tree\", \"treeitem\", \"group\"],\n    keyboard: [\n      \"Tab\",\n      \"Enter\",\n      \"Space\",\n      \"ArrowUp\",\n      \"ArrowDown\",\n      \"ArrowLeft\",\n      \"ArrowRight\",\n      \"Home\",\n      \"End\",\n      \"Typeahead\",\n    ],\n    focus: \"roving\",\n  },\n  /** Tree is Web-only per catalog platform classification — no native surface, matching Breadcrumb and Tooltip. */\n  native: { roles: [], states: [], actions: [] },\n  scenarios: [\n    \"depth-and-sibling-position-are-announced-not-only-visual-indent\",\n    \"arrow-expands-or-moves-to-the-first-child-arrow-collapses-or-moves-to-the-parent-respecting-rtl\",\n    \"up-down-home-end-move-across-visible-nodes-only-collapsed-subtrees-are-skipped\",\n    \"typeahead-matches-only-currently-visible-nodes\",\n    \"disabled-gates-selection-only-expand-and-collapse-remain-available\",\n    \"empty-children-array-is-rejected-a-node-either-omits-children-or-lists-at-least-one\",\n    \"one-tab-stop-per-node-the-expand-collapse-glyph-is-decorative-not-a-nested-control\",\n    \"drag-reorder-is-out-of-scope-until-a-real-product-need-exists\",\n  ],\n} as const satisfies BehaviorContract;\n\nexport const treeRecipe = {\n  slots: [\"root\", \"node\", \"toggle\", \"indent\", \"label\", \"description\"] as const,\n  indentPerLevel: spacing.lg,\n  /** Reuses the same row chrome Menu/Select items already use instead of inventing new selection-row visuals. */\n  node: collectionItemContract,\n  toggle: {\n    size: \"sm\",\n    icons: {\n      collapsed: \"chevronEnd\",\n      expanded: \"chevronDown\",\n    },\n    color: semanticColors.content.secondary,\n    hitTarget: control.minTouchTarget,\n  },\n} as const satisfies {\n  slots: readonly string[];\n  indentPerLevel: number;\n  node: typeof collectionItemContract;\n  toggle: {\n    size: string;\n    icons: Readonly<{ collapsed: SemanticIconName; expanded: SemanticIconName }>;\n    color: ColorReference;\n    hitTarget: number;\n  };\n};\n"]}