@hjmds/design-contracts 0.8.2

package/dist/transfer-list.d.ts

@@ -0,0 +1,207 @@
+import type { CheckboxState, CollectionKey, SelectItemDescriptor } from "./behaviors.js";
+/**
+ * `docs/transfer-list.md`: two lists sharing one item set, split by whether
+ * each id is in `targetKeys`. This is the same shape CheckboxGroup already
+ * commits to (`ReadonlySet<Id>`, no third "which panel" enum to keep in
+ * sync with membership) — one source of truth instead of two arrays that can
+ * drift apart when an item is moved.
+ */
+export type TransferListPanel = "source" | "target";
+export type TransferListDescriptor<Id extends CollectionKey = CollectionKey> = Readonly<{
+    items: readonly SelectItemDescriptor<Id>[];
+    targetKeys: ReadonlySet<Id>;
+}>;
+export type TransferListSelection<Id extends CollectionKey = CollectionKey> = Readonly<{
+    source: ReadonlySet<Id>;
+    target: ReadonlySet<Id>;
+}>;
+/** An item already sitting entirely inside one panel (including all-in-target
+ * or all-in-source) is valid — nothing here requires either panel to be
+ * non-empty, and a disabled item is valid in either panel even though it can
+ * never be moved by the UI. */
+export declare function validateTransferListDescriptor<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>): void;
+export type TransferListPanels<Id extends CollectionKey = CollectionKey> = Readonly<{
+    source: readonly SelectItemDescriptor<Id>[];
+    target: readonly SelectItemDescriptor<Id>[];
+}>;
+/** Splits by `targetKeys` membership, preserving each item's relative order from `items`. */
+export declare function resolveTransferListPanels<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>): TransferListPanels<Id>;
+export declare function validateTransferListSelection<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>, selection: TransferListSelection<Id>): void;
+/** Toggles one row's checkbox within its own panel; the other panel's selection is untouched. */
+export declare function toggleTransferListSelection<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>, selection: TransferListSelection<Id>, panel: TransferListPanel, id: Id): TransferListSelection<Id>;
+/**
+ * Same tri-state `CheckboxState` `resolveDataTableSelectAllState` derives for
+ * a table header — disabled rows excluded from both the denominator and the
+ * count — generalized from "all rows" to "this one panel's rows".
+ */
+export declare function resolveTransferListSelectAllState<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>, selection: TransferListSelection<Id>, panel: TransferListPanel): CheckboxState;
+/** Mixed-defaults-to-checked, matching `getCheckboxNextState`'s existing convention. */
+export declare function toggleTransferListSelectAll<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>, selection: TransferListSelection<Id>, panel: TransferListPanel): TransferListSelection<Id>;
+export type TransferListMoveDirection = "toTarget" | "toSource";
+export type TransferListMoveResult<Id extends CollectionKey = CollectionKey> = Readonly<{
+    targetKeys: ReadonlySet<Id>;
+    selection: TransferListSelection<Id>;
+    /** In origin-panel order — the product formats the announcement string from this. */
+    movedIds: readonly Id[];
+}>;
+/**
+ * Moves every enabled, currently-selected id out of its origin panel.
+ * Disabled ids are skipped rather than rejected (a disabled row can never
+ * enter a selection through `toggleTransferListSelection`, but a product
+ * could hand one to `defaultSelectedKeys`, and skipping mirrors
+ * `toggleTreeCheckedSelection`'s disabled guard rather than throwing on it).
+ * Moved ids are cleared from the origin panel's selection and deliberately
+ * left unselected in the destination panel — a move commits a value, it does
+ * not also commit a new pending selection the user did not make.
+ */
+export declare function moveTransferListSelection<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>, selection: TransferListSelection<Id>, direction: TransferListMoveDirection): TransferListMoveResult<Id>;
+/**
+ * Where focus lands once the moved rows are gone from a panel: the item that
+ * slid into the first removed row's position, so keyboard users keep moving
+ * down the list without their focus jumping to the top or vanishing. `null`
+ * means the panel is now empty — the renderer falls back to the panel's
+ * empty-state message or the move button, never to the document body.
+ */
+export declare function resolveTransferListFocusAfterMove<Id extends CollectionKey>(remainingPanelItems: readonly SelectItemDescriptor<Id>[], removedIndex: number): Id | null;
+/** Drops selected ids that left either panel (item removed from `items` entirely). */
+export declare function reconcileTransferListSelection<Id extends CollectionKey>(descriptor: TransferListDescriptor<Id>, selection: TransferListSelection<Id>): TransferListSelection<Id>;
+export declare const transferListRecipe: {
+    readonly slots: readonly ["root", "panel", "panelHeader", "panelTitle", "panelCount", "list", "item", "itemCheckbox", "emptyState", "moveControls", "moveButton"];
+    readonly panel: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surface";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly borderWidth: 1;
+        readonly radius: "md";
+    };
+    readonly panelHeader: {
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 12;
+        readonly title: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly textVariant: "body";
+        };
+        readonly count: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textMuted";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+    };
+    readonly item: {
+        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 emptyState: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+    };
+    readonly moveControls: {
+        readonly gap: 12;
+    };
+    readonly moveButton: {
+        readonly minTarget: 44;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly disabledOpacity: 0.4;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+    };
+};
+export declare const transferListBehavior: {
+    readonly controlled: readonly ["targetKeys", "defaultTargetKeys", "onTargetKeysChange"];
+    readonly inputs: readonly ["items"];
+    readonly events: readonly ["onMove"];
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled"];
+        readonly value: readonly ["empty", "filled", "selected", "mixed"];
+    };
+    readonly web: {
+        readonly roles: readonly ["group", "listbox", "option", "checkbox", "button"];
+        readonly keyboard: readonly ["Tab", "Space", "Enter", "ArrowUp", "ArrowDown", "Home", "End"];
+        readonly focus: "roving";
+    };
+    readonly native: {
+        readonly roles: readonly ["list", "checkbox", "button"];
+        readonly states: readonly ["disabled", "selected", "checked"];
+        readonly actions: readonly ["toggle", "toggleSelectAll", "moveSelection", "moveItem"];
+    };
+    readonly scenarios: readonly ["moving-is-reachable-entirely-by-keyboard-select-with-space-then-activate-the-move-button", "moving-a-single-focused-row-does-not-require-first-opening-multi-select", "focus-after-a-move-lands-on-the-item-that-slid-into-the-removed-rows-position", "focus-after-emptying-a-panel-falls-back-to-its-empty-state-never-lost-to-the-document", "every-move-emits-which-ids-moved-so-the-product-can-announce-a-formatted-sentence", "disabled-items-are-never-selectable-and-never-move", "moved-items-are-cleared-from-the-origin-panels-selection-and-left-unselected-at-the-destination", "select-all-in-a-panel-excludes-disabled-items-from-both-the-denominator-and-the-count", "an-item-with-nothing-selected-in-its-panel-still-supports-direct-single-item-move", "search-and-pagination-inside-a-panel-are-product-composition-not-this-contract"];
+};
+//# sourceMappingURL=transfer-list.d.ts.map

package/dist/transfer-list.d.ts.map

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

package/dist/transfer-list.js

@@ -0,0 +1,193 @@
+import { getCheckboxNextState, reconcileCheckboxSelection, toggleCheckboxSelection, } from "./selection-helpers.js";
+import { collectionItemContract, focusIndicatorContract } from "./component-contracts.js";
+import { validateCollection } from "./collection.js";
+import { control, radius, spacing, stroke } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+function withPanelSelection(selection, panel, next) {
+    return panel === "source"
+        ? { source: next, target: selection.target }
+        : { source: selection.source, target: next };
+}
+function assertKnownIds(label, ids, knownIds) {
+    for (const id of ids) {
+        if (!knownIds.has(id)) {
+            throw new RangeError(`TransferList ${label} references an unknown item id: ${id}`);
+        }
+    }
+}
+/** An item already sitting entirely inside one panel (including all-in-target
+ * or all-in-source) is valid — nothing here requires either panel to be
+ * non-empty, and a disabled item is valid in either panel even though it can
+ * never be moved by the UI. */
+export function validateTransferListDescriptor(descriptor) {
+    validateCollection({ items: descriptor.items });
+    const knownIds = new Set(descriptor.items.map((item) => item.id));
+    assertKnownIds("targetKeys", descriptor.targetKeys, knownIds);
+}
+/** Splits by `targetKeys` membership, preserving each item's relative order from `items`. */
+export function resolveTransferListPanels(descriptor) {
+    validateTransferListDescriptor(descriptor);
+    const source = [];
+    const target = [];
+    for (const item of descriptor.items) {
+        (descriptor.targetKeys.has(item.id) ? target : source).push(item);
+    }
+    return { source, target };
+}
+export function validateTransferListSelection(descriptor, selection) {
+    const panels = resolveTransferListPanels(descriptor);
+    assertKnownIds("selection.source", selection.source, new Set(panels.source.map((i) => i.id)));
+    assertKnownIds("selection.target", selection.target, new Set(panels.target.map((i) => i.id)));
+}
+/** Toggles one row's checkbox within its own panel; the other panel's selection is untouched. */
+export function toggleTransferListSelection(descriptor, selection, panel, id) {
+    const panels = resolveTransferListPanels(descriptor);
+    const next = toggleCheckboxSelection(panels[panel], selection[panel], id);
+    return withPanelSelection(selection, panel, next);
+}
+/**
+ * Same tri-state `CheckboxState` `resolveDataTableSelectAllState` derives for
+ * a table header — disabled rows excluded from both the denominator and the
+ * count — generalized from "all rows" to "this one panel's rows".
+ */
+export function resolveTransferListSelectAllState(descriptor, selection, panel) {
+    const items = resolveTransferListPanels(descriptor)[panel];
+    const selectable = items.filter((item) => !item.disabled);
+    if (selectable.length === 0)
+        return false;
+    const selectedCount = selectable.filter((item) => selection[panel].has(item.id)).length;
+    if (selectedCount === 0)
+        return false;
+    return selectedCount === selectable.length ? true : "mixed";
+}
+/** Mixed-defaults-to-checked, matching `getCheckboxNextState`'s existing convention. */
+export function toggleTransferListSelectAll(descriptor, selection, panel) {
+    const current = resolveTransferListSelectAllState(descriptor, selection, panel);
+    const checkAll = getCheckboxNextState(current);
+    const items = resolveTransferListPanels(descriptor)[panel];
+    const next = checkAll
+        ? new Set(items.filter((item) => !item.disabled).map((item) => item.id))
+        : new Set();
+    return withPanelSelection(selection, panel, next);
+}
+/**
+ * Moves every enabled, currently-selected id out of its origin panel.
+ * Disabled ids are skipped rather than rejected (a disabled row can never
+ * enter a selection through `toggleTransferListSelection`, but a product
+ * could hand one to `defaultSelectedKeys`, and skipping mirrors
+ * `toggleTreeCheckedSelection`'s disabled guard rather than throwing on it).
+ * Moved ids are cleared from the origin panel's selection and deliberately
+ * left unselected in the destination panel — a move commits a value, it does
+ * not also commit a new pending selection the user did not make.
+ */
+export function moveTransferListSelection(descriptor, selection, direction) {
+    validateTransferListSelection(descriptor, selection);
+    const fromPanel = direction === "toTarget" ? "source" : "target";
+    const fromItems = resolveTransferListPanels(descriptor)[fromPanel];
+    const movedIds = fromItems
+        .filter((item) => !item.disabled && selection[fromPanel].has(item.id))
+        .map((item) => item.id);
+    if (movedIds.length === 0) {
+        return { targetKeys: descriptor.targetKeys, selection, movedIds: [] };
+    }
+    const movedIdSet = new Set(movedIds);
+    const targetKeys = direction === "toTarget"
+        ? new Set([...descriptor.targetKeys, ...movedIds])
+        : new Set([...descriptor.targetKeys].filter((id) => !movedIdSet.has(id)));
+    const nextFromSelection = new Set([...selection[fromPanel]].filter((id) => !movedIdSet.has(id)));
+    return {
+        targetKeys,
+        selection: withPanelSelection(selection, fromPanel, nextFromSelection),
+        movedIds,
+    };
+}
+/**
+ * Where focus lands once the moved rows are gone from a panel: the item that
+ * slid into the first removed row's position, so keyboard users keep moving
+ * down the list without their focus jumping to the top or vanishing. `null`
+ * means the panel is now empty — the renderer falls back to the panel's
+ * empty-state message or the move button, never to the document body.
+ */
+export function resolveTransferListFocusAfterMove(remainingPanelItems, removedIndex) {
+    if (remainingPanelItems.length === 0)
+        return null;
+    const clamped = Math.min(Math.max(removedIndex, 0), remainingPanelItems.length - 1);
+    return remainingPanelItems[clamped].id;
+}
+/** Drops selected ids that left either panel (item removed from `items` entirely). */
+export function reconcileTransferListSelection(descriptor, selection) {
+    const panels = resolveTransferListPanels(descriptor);
+    const source = reconcileCheckboxSelection(panels.source, selection.source);
+    const target = reconcileCheckboxSelection(panels.target, selection.target);
+    if (source === selection.source && target === selection.target)
+        return selection;
+    return { source, target };
+}
+export const transferListRecipe = {
+    slots: [
+        "root",
+        "panel",
+        "panelHeader",
+        "panelTitle",
+        "panelCount",
+        "list",
+        "item",
+        "itemCheckbox",
+        "emptyState",
+        "moveControls",
+        "moveButton",
+    ],
+    panel: {
+        background: semanticColors.surface.default,
+        border: semanticColors.border.default,
+        borderWidth: stroke.default,
+        radius: "md",
+    },
+    panelHeader: {
+        minHeight: 44,
+        paddingHorizontal: spacing.sm,
+        title: { color: semanticColors.content.body, textVariant: "body" },
+        count: { color: semanticColors.content.secondary, textVariant: "label" },
+    },
+    item: collectionItemContract,
+    emptyState: { color: semanticColors.content.secondary, textVariant: "label" },
+    moveControls: { gap: spacing.sm },
+    moveButton: {
+        minTarget: control.minTouchTarget,
+        color: semanticColors.content.brand,
+        disabledOpacity: 0.4,
+    },
+    states: { focus: focusIndicatorContract },
+};
+export const transferListBehavior = {
+    controlled: ["targetKeys", "defaultTargetKeys", "onTargetKeysChange"],
+    inputs: ["items"],
+    events: ["onMove"],
+    stateAxes: {
+        availability: ["enabled", "disabled"],
+        value: ["empty", "filled", "selected", "mixed"],
+    },
+    web: {
+        roles: ["group", "listbox", "option", "checkbox", "button"],
+        keyboard: ["Tab", "Space", "Enter", "ArrowUp", "ArrowDown", "Home", "End"],
+        focus: "roving",
+    },
+    native: {
+        roles: ["list", "checkbox", "button"],
+        states: ["disabled", "selected", "checked"],
+        actions: ["toggle", "toggleSelectAll", "moveSelection", "moveItem"],
+    },
+    scenarios: [
+        "moving-is-reachable-entirely-by-keyboard-select-with-space-then-activate-the-move-button",
+        "moving-a-single-focused-row-does-not-require-first-opening-multi-select",
+        "focus-after-a-move-lands-on-the-item-that-slid-into-the-removed-rows-position",
+        "focus-after-emptying-a-panel-falls-back-to-its-empty-state-never-lost-to-the-document",
+        "every-move-emits-which-ids-moved-so-the-product-can-announce-a-formatted-sentence",
+        "disabled-items-are-never-selectable-and-never-move",
+        "moved-items-are-cleared-from-the-origin-panels-selection-and-left-unselected-at-the-destination",
+        "select-all-in-a-panel-excludes-disabled-items-from-both-the-denominator-and-the-count",
+        "an-item-with-nothing-selected-in-its-panel-still-supports-direct-single-item-move",
+        "search-and-pagination-inside-a-panel-are-product-composition-not-this-contract",
+    ],
+};
+//# sourceMappingURL=transfer-list.js.map

package/dist/transfer-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-list.js","sourceRoot":"","sources":["../src/transfer-list.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type {\n  BehaviorContract,\n  CheckboxState,\n  CollectionKey,\n  SelectItemDescriptor,\n} from \"./behaviors.js\";\nimport {\n  getCheckboxNextState,\n  reconcileCheckboxSelection,\n  toggleCheckboxSelection,\n} from \"./selection-helpers.js\";\nimport { collectionItemContract, focusIndicatorContract } from \"./component-contracts.js\";\nimport { validateCollection } from \"./collection.js\";\nimport { control, radius, spacing, stroke } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * `docs/transfer-list.md`: two lists sharing one item set, split by whether\n * each id is in `targetKeys`. This is the same shape CheckboxGroup already\n * commits to (`ReadonlySet<Id>`, no third \"which panel\" enum to keep in\n * sync with membership) — one source of truth instead of two arrays that can\n * drift apart when an item is moved.\n */\nexport type TransferListPanel = \"source\" | \"target\";\n\nexport type TransferListDescriptor<Id extends CollectionKey = CollectionKey> = Readonly<{\n  items: readonly SelectItemDescriptor<Id>[];\n  targetKeys: ReadonlySet<Id>;\n}>;\n\nexport type TransferListSelection<Id extends CollectionKey = CollectionKey> = Readonly<{\n  source: ReadonlySet<Id>;\n  target: ReadonlySet<Id>;\n}>;\n\nfunction withPanelSelection<Id extends CollectionKey>(\n  selection: TransferListSelection<Id>,\n  panel: TransferListPanel,\n  next: ReadonlySet<Id>,\n): TransferListSelection<Id> {\n  return panel === \"source\"\n    ? { source: next, target: selection.target }\n    : { source: selection.source, target: next };\n}\n\nfunction assertKnownIds<Id extends CollectionKey>(\n  label: string,\n  ids: ReadonlySet<Id>,\n  knownIds: ReadonlySet<Id>,\n): void {\n  for (const id of ids) {\n    if (!knownIds.has(id)) {\n      throw new RangeError(`TransferList ${label} references an unknown item id: ${id}`);\n    }\n  }\n}\n\n/** An item already sitting entirely inside one panel (including all-in-target\n * or all-in-source) is valid — nothing here requires either panel to be\n * non-empty, and a disabled item is valid in either panel even though it can\n * never be moved by the UI. */\nexport function validateTransferListDescriptor<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n): void {\n  validateCollection({ items: descriptor.items });\n  const knownIds = new Set(descriptor.items.map((item) => item.id));\n  assertKnownIds(\"targetKeys\", descriptor.targetKeys, knownIds);\n}\n\nexport type TransferListPanels<Id extends CollectionKey = CollectionKey> = Readonly<{\n  source: readonly SelectItemDescriptor<Id>[];\n  target: readonly SelectItemDescriptor<Id>[];\n}>;\n\n/** Splits by `targetKeys` membership, preserving each item's relative order from `items`. */\nexport function resolveTransferListPanels<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n): TransferListPanels<Id> {\n  validateTransferListDescriptor(descriptor);\n  const source: SelectItemDescriptor<Id>[] = [];\n  const target: SelectItemDescriptor<Id>[] = [];\n  for (const item of descriptor.items) {\n    (descriptor.targetKeys.has(item.id) ? target : source).push(item);\n  }\n  return { source, target };\n}\n\nexport function validateTransferListSelection<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n  selection: TransferListSelection<Id>,\n): void {\n  const panels = resolveTransferListPanels(descriptor);\n  assertKnownIds(\"selection.source\", selection.source, new Set(panels.source.map((i) => i.id)));\n  assertKnownIds(\"selection.target\", selection.target, new Set(panels.target.map((i) => i.id)));\n}\n\n/** Toggles one row's checkbox within its own panel; the other panel's selection is untouched. */\nexport function toggleTransferListSelection<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n  selection: TransferListSelection<Id>,\n  panel: TransferListPanel,\n  id: Id,\n): TransferListSelection<Id> {\n  const panels = resolveTransferListPanels(descriptor);\n  const next = toggleCheckboxSelection(panels[panel], selection[panel], id);\n  return withPanelSelection(selection, panel, next);\n}\n\n/**\n * Same tri-state `CheckboxState` `resolveDataTableSelectAllState` derives for\n * a table header — disabled rows excluded from both the denominator and the\n * count — generalized from \"all rows\" to \"this one panel's rows\".\n */\nexport function resolveTransferListSelectAllState<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n  selection: TransferListSelection<Id>,\n  panel: TransferListPanel,\n): CheckboxState {\n  const items = resolveTransferListPanels(descriptor)[panel];\n  const selectable = items.filter((item) => !item.disabled);\n  if (selectable.length === 0) return false;\n  const selectedCount = selectable.filter((item) => selection[panel].has(item.id)).length;\n  if (selectedCount === 0) return false;\n  return selectedCount === selectable.length ? true : \"mixed\";\n}\n\n/** Mixed-defaults-to-checked, matching `getCheckboxNextState`'s existing convention. */\nexport function toggleTransferListSelectAll<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n  selection: TransferListSelection<Id>,\n  panel: TransferListPanel,\n): TransferListSelection<Id> {\n  const current = resolveTransferListSelectAllState(descriptor, selection, panel);\n  const checkAll = getCheckboxNextState(current);\n  const items = resolveTransferListPanels(descriptor)[panel];\n  const next = checkAll\n    ? new Set(items.filter((item) => !item.disabled).map((item) => item.id))\n    : new Set<Id>();\n  return withPanelSelection(selection, panel, next);\n}\n\nexport type TransferListMoveDirection = \"toTarget\" | \"toSource\";\n\nexport type TransferListMoveResult<Id extends CollectionKey = CollectionKey> = Readonly<{\n  targetKeys: ReadonlySet<Id>;\n  selection: TransferListSelection<Id>;\n  /** In origin-panel order — the product formats the announcement string from this. */\n  movedIds: readonly Id[];\n}>;\n\n/**\n * Moves every enabled, currently-selected id out of its origin panel.\n * Disabled ids are skipped rather than rejected (a disabled row can never\n * enter a selection through `toggleTransferListSelection`, but a product\n * could hand one to `defaultSelectedKeys`, and skipping mirrors\n * `toggleTreeCheckedSelection`'s disabled guard rather than throwing on it).\n * Moved ids are cleared from the origin panel's selection and deliberately\n * left unselected in the destination panel — a move commits a value, it does\n * not also commit a new pending selection the user did not make.\n */\nexport function moveTransferListSelection<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n  selection: TransferListSelection<Id>,\n  direction: TransferListMoveDirection,\n): TransferListMoveResult<Id> {\n  validateTransferListSelection(descriptor, selection);\n  const fromPanel: TransferListPanel = direction === \"toTarget\" ? \"source\" : \"target\";\n  const fromItems = resolveTransferListPanels(descriptor)[fromPanel];\n  const movedIds = fromItems\n    .filter((item) => !item.disabled && selection[fromPanel].has(item.id))\n    .map((item) => item.id);\n\n  if (movedIds.length === 0) {\n    return { targetKeys: descriptor.targetKeys, selection, movedIds: [] };\n  }\n\n  const movedIdSet = new Set(movedIds);\n  const targetKeys =\n    direction === \"toTarget\"\n      ? new Set([...descriptor.targetKeys, ...movedIds])\n      : new Set([...descriptor.targetKeys].filter((id) => !movedIdSet.has(id)));\n\n  const nextFromSelection = new Set(\n    [...selection[fromPanel]].filter((id) => !movedIdSet.has(id)),\n  );\n  return {\n    targetKeys,\n    selection: withPanelSelection(selection, fromPanel, nextFromSelection),\n    movedIds,\n  };\n}\n\n/**\n * Where focus lands once the moved rows are gone from a panel: the item that\n * slid into the first removed row's position, so keyboard users keep moving\n * down the list without their focus jumping to the top or vanishing. `null`\n * means the panel is now empty — the renderer falls back to the panel's\n * empty-state message or the move button, never to the document body.\n */\nexport function resolveTransferListFocusAfterMove<Id extends CollectionKey>(\n  remainingPanelItems: readonly SelectItemDescriptor<Id>[],\n  removedIndex: number,\n): Id | null {\n  if (remainingPanelItems.length === 0) return null;\n  const clamped = Math.min(Math.max(removedIndex, 0), remainingPanelItems.length - 1);\n  return remainingPanelItems[clamped]!.id;\n}\n\n/** Drops selected ids that left either panel (item removed from `items` entirely). */\nexport function reconcileTransferListSelection<Id extends CollectionKey>(\n  descriptor: TransferListDescriptor<Id>,\n  selection: TransferListSelection<Id>,\n): TransferListSelection<Id> {\n  const panels = resolveTransferListPanels(descriptor);\n  const source = reconcileCheckboxSelection(panels.source, selection.source);\n  const target = reconcileCheckboxSelection(panels.target, selection.target);\n  if (source === selection.source && target === selection.target) return selection;\n  return { source, target };\n}\n\nexport const transferListRecipe = {\n  slots: [\n    \"root\",\n    \"panel\",\n    \"panelHeader\",\n    \"panelTitle\",\n    \"panelCount\",\n    \"list\",\n    \"item\",\n    \"itemCheckbox\",\n    \"emptyState\",\n    \"moveControls\",\n    \"moveButton\",\n  ] as const,\n  panel: {\n    background: semanticColors.surface.default,\n    border: semanticColors.border.default,\n    borderWidth: stroke.default,\n    radius: \"md\" as const,\n  },\n  panelHeader: {\n    minHeight: 44,\n    paddingHorizontal: spacing.sm,\n    title: { color: semanticColors.content.body, textVariant: \"body\" as const },\n    count: { color: semanticColors.content.secondary, textVariant: \"label\" as const },\n  },\n  item: collectionItemContract,\n  emptyState: { color: semanticColors.content.secondary, textVariant: \"label\" as const },\n  moveControls: { gap: spacing.sm },\n  moveButton: {\n    minTarget: control.minTouchTarget,\n    color: semanticColors.content.brand,\n    disabledOpacity: 0.4,\n  },\n  states: { focus: focusIndicatorContract },\n} as const satisfies {\n  slots: readonly [\n    \"root\",\n    \"panel\",\n    \"panelHeader\",\n    \"panelTitle\",\n    \"panelCount\",\n    \"list\",\n    \"item\",\n    \"itemCheckbox\",\n    \"emptyState\",\n    \"moveControls\",\n    \"moveButton\",\n  ];\n  panel: { background: ColorReference; border: ColorReference; borderWidth: number; radius: keyof typeof radius };\n  panelHeader: {\n    minHeight: number;\n    paddingHorizontal: number;\n    title: { color: ColorReference; textVariant: \"body\" };\n    count: { color: ColorReference; textVariant: \"label\" };\n  };\n  item: typeof collectionItemContract;\n  emptyState: { color: ColorReference; textVariant: \"label\" };\n  moveControls: { gap: number };\n  moveButton: { minTarget: number; color: ColorReference; disabledOpacity: number };\n  states: { focus: typeof focusIndicatorContract };\n};\n\nexport const transferListBehavior = {\n  controlled: [\"targetKeys\", \"defaultTargetKeys\", \"onTargetKeysChange\"],\n  inputs: [\"items\"],\n  events: [\"onMove\"],\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\"],\n    value: [\"empty\", \"filled\", \"selected\", \"mixed\"],\n  },\n  web: {\n    roles: [\"group\", \"listbox\", \"option\", \"checkbox\", \"button\"],\n    keyboard: [\"Tab\", \"Space\", \"Enter\", \"ArrowUp\", \"ArrowDown\", \"Home\", \"End\"],\n    focus: \"roving\",\n  },\n  native: {\n    roles: [\"list\", \"checkbox\", \"button\"],\n    states: [\"disabled\", \"selected\", \"checked\"],\n    actions: [\"toggle\", \"toggleSelectAll\", \"moveSelection\", \"moveItem\"],\n  },\n  scenarios: [\n    \"moving-is-reachable-entirely-by-keyboard-select-with-space-then-activate-the-move-button\",\n    \"moving-a-single-focused-row-does-not-require-first-opening-multi-select\",\n    \"focus-after-a-move-lands-on-the-item-that-slid-into-the-removed-rows-position\",\n    \"focus-after-emptying-a-panel-falls-back-to-its-empty-state-never-lost-to-the-document\",\n    \"every-move-emits-which-ids-moved-so-the-product-can-announce-a-formatted-sentence\",\n    \"disabled-items-are-never-selectable-and-never-move\",\n    \"moved-items-are-cleared-from-the-origin-panels-selection-and-left-unselected-at-the-destination\",\n    \"select-all-in-a-panel-excludes-disabled-items-from-both-the-denominator-and-the-count\",\n    \"an-item-with-nothing-selected-in-its-panel-still-supports-direct-single-item-move\",\n    \"search-and-pagination-inside-a-panel-are-product-composition-not-this-contract\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/tree-select.d.ts

@@ -0,0 +1,78 @@
+import type { CheckboxState } from "./behaviors.js";
+import { type TreeNodeDescriptor } from "./tree.js";
+/**
+ * `docs/tree.md`'s own "TreeSelect 판정" concludes TreeSelect is Select's
+ * surface (trigger + popup/sheet, committed value) plus Tree's collection
+ * (depth/sibling announcement, arrow-key expand/collapse, `expandedKeys`
+ * reconciliation) — no third primitive. That verdict is right for
+ * **single-select** TreeSelect: picking exactly one node needs nothing
+ * beyond Select's existing `selectedKey: Id | null` and Tree's flat item
+ * list, because there is nothing to aggregate.
+ *
+ * It is incomplete for **multiple-select** TreeSelect (checkboxes at every
+ * depth). Neither file solves "a parent's checkbox must show a third,
+ * aggregate state when only some of its descendant leaves are checked" —
+ * that is not a new selection model, it is `resolveDataTableSelectAllState`
+ * (`src/data-table.ts`) generalized from one level (header ↔ rows) to
+ * recursive depth (parent ↔ every descendant leaf), reusing the exact same
+ * `CheckboxState` (`boolean | "mixed"`) the header checkbox already renders.
+ * This module is that one missing piece — nothing else.
+ */
+export type TreeCheckedKeys<Id extends string = string> = ReadonlySet<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 declare function validateTreeCheckedSelection<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[], checkedKeys: TreeCheckedKeys<Id>): void;
+/**
+ * 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 declare function resolveTreeCheckedStates<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[], checkedKeys: TreeCheckedKeys<Id>): ReadonlyMap<Id, CheckboxState>;
+/**
+ * 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 declare function toggleTreeCheckedSelection<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[], checkedKeys: TreeCheckedKeys<Id>, targetId: Id): TreeCheckedKeys<Id>;
+/**
+ * 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 declare function reconcileTreeCheckedSelection<Id extends string>(nodes: readonly TreeNodeDescriptor<Id>[], checkedKeys: TreeCheckedKeys<Id>): TreeCheckedKeys<Id>;
+/**
+ * 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 declare const treeSelectBehaviorScenarios: readonly ["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.d.ts.map

package/dist/tree-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-select.d.ts","sourceRoot":"","sources":["../src/tree-select.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAuC,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEzF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC;AAY1E;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,SAAS,MAAM,EAC5D,KAAK,EAAE,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,WAAW,EAAE,eAAe,CAAC,EAAE,CAAC,GAC/B,IAAI,CAUN;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,SAAS,MAAM,EACxD,KAAK,EAAE,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,WAAW,EAAE,eAAe,CAAC,EAAE,CAAC,GAC/B,WAAW,CAAC,EAAE,EAAE,aAAa,CAAC,CAoBhC;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAC1D,KAAK,EAAE,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,WAAW,EAAE,eAAe,CAAC,EAAE,CAAC,EAChC,QAAQ,EAAE,EAAE,GACX,eAAe,CAAC,EAAE,CAAC,CAqBrB;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,EAAE,SAAS,MAAM,EAC7D,KAAK,EAAE,SAAS,kBAAkB,CAAC,EAAE,CAAC,EAAE,EACxC,WAAW,EAAE,eAAe,CAAC,EAAE,CAAC,GAC/B,eAAe,CAAC,EAAE,CAAC,CAKrB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,ojBAQ9B,CAAC"}