@hjmds/design-contracts 0.8.2

package/dist/command-palette.d.ts

@@ -0,0 +1,240 @@
+import type { CollectionKey, ComboboxInput, MenuItemDescriptor } from "./behaviors.js";
+import type { CollectionSource, ComboboxCollectionState } from "./collection.js";
+/**
+ * antd has no direct crosswalk target for CommandPalette — it is not in
+ * `antDesignReferenceComponents`. The nearest antd surface, `AutoComplete`/
+ * `Select` with `showSearch`, is exactly the composition question this
+ * module answers below, not a separate coverage gap.
+ *
+ * Decisive difference from Combobox: **a result is an action, not a
+ * persisted value.** Committing a Combobox sets `selectedKey` as the field's
+ * ongoing value, and `inputValue` goes on mirroring it. Running "새 트윗
+ * 작성" has no ongoing value anywhere to remember — the palette closes and
+ * resets. Forcing `selectedKey`/`onCommit` onto that would create a
+ * phantom value that is always `null` again the instant the palette reopens,
+ * the same category of dead-state mistake `docs/dropdown.md` avoided by not
+ * re-defining Menu's problem under a second name. So items here are shaped
+ * like `MenuItemDescriptor` (carries `shortcut`/`tone` for destructive
+ * commands), not `SelectItemDescriptor` (which deliberately strips both,
+ * because a Select option is a value, not an action).
+ *
+ * Everything else composes from existing contracts without changes:
+ * - **Heterogeneous sources** ("최근" / "명령어" / "검색 결과" in one list):
+ *   already representable — `CollectionSource`'s `sections` is exactly
+ *   grouped items, no new data model.
+ * - **Search/filter text**: `ComboboxInput` (inputValue/defaultInputValue/
+ *   onInputValueChange) and `ComboboxCollectionState` (local vs. external
+ *   filtering, `queryValue`/`resultQuery` staleness guard) are reused
+ *   verbatim — a command search is the same async-search problem Combobox
+ *   already solved, just over commands instead of selectable values.
+ * - **Keyboard navigation/typeahead across sections**: `getCollectionNavigationTarget`/
+ *   `getCollectionTypeaheadMatch` (`src/collection.ts`) already generalize
+ *   over any `CollectionSource`; nothing palette-specific to add.
+ * - **Global keyboard shortcut** (⌘K): explicitly out of scope. Which key
+ *   combination opens the palette, and whether it is global or scoped, is a
+ *   product/app decision — the same reason Link does not own navigation and
+ *   BottomNavigation does not own the router's route state.
+ */
+export type CommandPaletteItemDescriptor<Key extends CollectionKey = CollectionKey> = MenuItemDescriptor<Key>;
+export type CommandPaletteSource<Key extends CollectionKey = CollectionKey, SectionKey extends CollectionKey = CollectionKey> = CollectionSource<Key, SectionKey>;
+export type CommandPaletteInput = ComboboxInput;
+export type CommandPaletteQueryState = ComboboxCollectionState;
+export type CommandPaletteActivateReason = "pointer" | "keyboard";
+/**
+ * Mirrors Menu's `onAction`/`onActionAfterDismiss` split (`behaviorRegistry.menu`)
+ * without importing it — Menu, like Dialog, predates the per-component
+ * `src/<name>.ts` convention and has no exported type of its own to import,
+ * only string literals in the shared registry. `onActivate` fires
+ * immediately; `onActivateAfterDismiss` fires once the exit transition
+ * completes, for a command that itself opens another overlay (the same
+ * "close first, open the next surface after exit completes" ordering
+ * `docs/architecture.md`'s overlay-stack rule already requires).
+ */
+export type CommandPaletteActivateHandler<Key extends CollectionKey = CollectionKey> = (itemId: Key, reason: CommandPaletteActivateReason) => void;
+/**
+ * Web-only modal overlay (catalog: `platform: "web"`) — there is no `modal`
+ * axis the way SidePanel needs one; a command palette is always a modal
+ * takeover, never an inline non-modal surface. No `back`/`swipe` for the
+ * same web-only reason `SidePanelDismissReason` excludes them.
+ *
+ * `"activation"` is a dismiss reason, not merely an event: running a command
+ * always closes the palette, which is why `canDismissCommandPalette` treats
+ * it like `"programmatic"` — an owner-level certainty no policy can veto.
+ * There is no `busy` axis blocking dismissal while a command executes: the
+ * palette itself is fire-and-forget (`onActivate` fires and the palette
+ * closes); if the command's own effect is asynchronous, that runs after the
+ * palette is already gone, the same ordering Menu's `onActionAfterDismiss`
+ * already models. Recreating AlertDialog's `idle→busy→error` session here
+ * would be guessing at a requirement (a command that must block the palette
+ * open until it settles) with no measured product need.
+ */
+export type CommandPaletteDismissReason = "close-action" | "outside" | "escape" | "activation" | "programmatic";
+export type CommandPaletteOpenChangeDetails = Readonly<{
+    reason: "trigger" | CommandPaletteDismissReason;
+}>;
+export type ControlledCommandPaletteOpenState = Readonly<{
+    open: boolean;
+    defaultOpen?: never;
+    onOpenChange(open: boolean, details: CommandPaletteOpenChangeDetails): void;
+}>;
+export type UncontrolledCommandPaletteOpenState = Readonly<{
+    open?: never;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: CommandPaletteOpenChangeDetails) => void;
+}>;
+export type CommandPaletteOpenState = ControlledCommandPaletteOpenState | UncontrolledCommandPaletteOpenState;
+export type CommandPaletteDismissPolicy = Readonly<{
+    dismissible: boolean;
+    outsideDismiss: boolean;
+    escapeDismiss: boolean;
+}>;
+export declare const commandPaletteBehaviorDefaults: {
+    readonly dismissible: true;
+    readonly outsideDismiss: true;
+    readonly escapeDismiss: true;
+};
+export declare function canDismissCommandPalette(reason: CommandPaletteDismissReason, policy?: CommandPaletteDismissPolicy): boolean;
+/**
+ * `accessibilityLabel` is required, not optional like Popover's — a command
+ * palette's `role="dialog"` surface has no visible heading the way Dialog's
+ * `title` slot or typical Popover content provides; the search field alone
+ * is not a reliable accessible name across renderers. `searchPlaceholder` is
+ * required for the same reason `LoadMoreLabels`/`PaginationLabels` require
+ * every field: a renderer must not invent untranslated fallback copy.
+ */
+export type CommandPaletteDescriptor = Readonly<{
+    accessibilityLabel: string;
+    searchPlaceholder: string;
+}>;
+export declare function validateCommandPaletteDescriptor(descriptor: CommandPaletteDescriptor): void;
+/**
+ * Anatomy only — chrome for the modal shell and the pinned search field,
+ * reusing the exact tokens Dialog-family and Menu-family recipes already use
+ * (`floatingSurfaceContract`, `fieldFrameContract`, `collectionItemContract`)
+ * instead of inventing new ones. Result rows and section labels reuse
+ * `collectionItemContract` the same way `menuRecipe`/`treeRecipe` do — a
+ * command result is chrome-identical to a Menu item, it just lives in a
+ * modal instead of an anchored popup.
+ */
+export declare const commandPaletteRecipe: {
+    readonly slots: readonly ["backdrop", "positioner", "content", "searchField", "viewport", "section", "sectionLabel", "item", "leading", "copy", "label", "description", "shortcut", "emptyState"];
+    readonly backdrop: {
+        readonly color: "#000000";
+        readonly opacity: 0.6;
+    };
+    readonly content: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "bg";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly borderWidth: 1;
+        readonly radius: "lg";
+        readonly shadow: {
+            readonly color: "#000000";
+            readonly opacity: 0.12;
+            readonly radius: 12;
+            readonly offsetY: 4;
+        };
+        readonly maxWidth: 560;
+        readonly maxHeight: 420;
+    };
+    readonly searchField: {
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 16;
+        readonly borderColor: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+    };
+    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 sectionLabel: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+        readonly paddingHorizontal: 12;
+        readonly paddingVertical: 8;
+    };
+    readonly emptyState: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly textVariant: "body";
+        readonly paddingVertical: 24;
+    };
+    readonly transition: {
+        readonly enter: {
+            readonly duration: 200;
+            readonly easing: "enter";
+            readonly reducedMotion: "opacity";
+        };
+        readonly exit: {
+            readonly duration: 120;
+            readonly easing: "exit";
+            readonly reducedMotion: "instant";
+        };
+    };
+};
+export declare const commandPaletteBehaviorScenarios: readonly ["activating-a-result-always-closes-the-palette-regardless-of-dismiss-policy", "escape-and-outside-close-without-running-any-command", "sections-merge-recents-static-commands-and-search-results-without-a-new-data-model", "keyboard-navigation-and-typeahead-reuse-the-shared-collection-helpers-unchanged", "local-vs-external-filtering-reuses-comboboxcollectionstate-staleness-guard-unchanged", "empty-result-state-is-announced-once-not-per-section", "no-global-shortcut-binding-is-owned-here-the-product-decides-the-trigger-key", "activate-after-dismiss-lets-a-command-open-the-next-overlay-only-once-exit-completes"];
+//# sourceMappingURL=command-palette.d.ts.map

package/dist/command-palette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-palette.d.ts","sourceRoot":"","sources":["../src/command-palette.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AASjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,4BAA4B,CAAC,GAAG,SAAS,aAAa,GAAG,aAAa,IAChF,kBAAkB,CAAC,GAAG,CAAC,CAAC;AAE1B,MAAM,MAAM,oBAAoB,CAC9B,GAAG,SAAS,aAAa,GAAG,aAAa,EACzC,UAAU,SAAS,aAAa,GAAG,aAAa,IAC9C,gBAAgB,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;AAEtC,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAChD,MAAM,MAAM,wBAAwB,GAAG,uBAAuB,CAAC;AAE/D,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,UAAU,CAAC;AAElE;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,CAAC,GAAG,SAAS,aAAa,GAAG,aAAa,IAAI,CACrF,MAAM,EAAE,GAAG,EACX,MAAM,EAAE,4BAA4B,KACjC,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,2BAA2B,GACnC,cAAc,GACd,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,cAAc,CAAC;AAEnB,MAAM,MAAM,+BAA+B,GAAG,QAAQ,CAAC;IACrD,MAAM,EAAE,SAAS,GAAG,2BAA2B,CAAC;CACjD,CAAC,CAAC;AAEH,MAAM,MAAM,iCAAiC,GAAG,QAAQ,CAAC;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,+BAA+B,GAAG,IAAI,CAAC;CAC7E,CAAC,CAAC;AAEH,MAAM,MAAM,mCAAmC,GAAG,QAAQ,CAAC;IACzD,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,CACb,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,+BAA+B,KACrC,IAAI,CAAC;CACX,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAC/B,iCAAiC,GACjC,mCAAmC,CAAC;AAExC,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC,CAAC;AAEH,eAAO,MAAM,8BAA8B;;;;CAIK,CAAC;AAEjD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,2BAA2B,EACnC,MAAM,GAAE,2BAA4D,GACnE,OAAO,CAMT;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC,CAAC;AAQH,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,wBAAwB,GACnC,IAAI,CAMN;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CvB,CAAC;AAEX,eAAO,MAAM,+BAA+B,knBASlC,CAAC"}

package/dist/command-palette.js

@@ -0,0 +1,97 @@
+import { collectionItemContract, fieldFrameContract, floatingSurfaceContract, } from "./component-contracts.js";
+import { backdrop, motionPreset, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const commandPaletteBehaviorDefaults = {
+    dismissible: true,
+    outsideDismiss: true,
+    escapeDismiss: true,
+};
+export function canDismissCommandPalette(reason, policy = commandPaletteBehaviorDefaults) {
+    if (reason === "programmatic" || reason === "activation")
+        return true;
+    if (!policy.dismissible)
+        return false;
+    if (reason === "outside")
+        return policy.outsideDismiss;
+    if (reason === "escape")
+        return policy.escapeDismiss;
+    return true;
+}
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`CommandPalette ${field} must not be empty`);
+    }
+}
+export function validateCommandPaletteDescriptor(descriptor) {
+    if (descriptor === null || typeof descriptor !== "object") {
+        throw new TypeError("CommandPalette descriptor must be an object");
+    }
+    assertNonEmpty(descriptor.accessibilityLabel, "accessibilityLabel");
+    assertNonEmpty(descriptor.searchPlaceholder, "searchPlaceholder");
+}
+/**
+ * Anatomy only — chrome for the modal shell and the pinned search field,
+ * reusing the exact tokens Dialog-family and Menu-family recipes already use
+ * (`floatingSurfaceContract`, `fieldFrameContract`, `collectionItemContract`)
+ * instead of inventing new ones. Result rows and section labels reuse
+ * `collectionItemContract` the same way `menuRecipe`/`treeRecipe` do — a
+ * command result is chrome-identical to a Menu item, it just lives in a
+ * modal instead of an anchored popup.
+ */
+export const commandPaletteRecipe = {
+    slots: [
+        "backdrop",
+        "positioner",
+        "content",
+        "searchField",
+        "viewport",
+        "section",
+        "sectionLabel",
+        "item",
+        "leading",
+        "copy",
+        "label",
+        "description",
+        "shortcut",
+        "emptyState",
+    ],
+    backdrop: backdrop.modal,
+    content: {
+        background: floatingSurfaceContract.background,
+        border: floatingSurfaceContract.border,
+        borderWidth: floatingSurfaceContract.borderWidth,
+        radius: "lg",
+        shadow: floatingSurfaceContract.shadow,
+        maxWidth: 560,
+        maxHeight: 420,
+    },
+    searchField: {
+        minHeight: fieldFrameContract.minHeight,
+        paddingHorizontal: fieldFrameContract.paddingHorizontal,
+        borderColor: fieldFrameContract.border,
+    },
+    item: collectionItemContract,
+    sectionLabel: {
+        color: semanticColors.content.secondary,
+        textVariant: "label",
+        paddingHorizontal: spacing.sm,
+        paddingVertical: spacing.xs,
+    },
+    emptyState: {
+        color: semanticColors.content.secondary,
+        textVariant: "body",
+        paddingVertical: spacing.xl,
+    },
+    transition: { enter: motionPreset.enter, exit: motionPreset.exit },
+};
+export const commandPaletteBehaviorScenarios = [
+    "activating-a-result-always-closes-the-palette-regardless-of-dismiss-policy",
+    "escape-and-outside-close-without-running-any-command",
+    "sections-merge-recents-static-commands-and-search-results-without-a-new-data-model",
+    "keyboard-navigation-and-typeahead-reuse-the-shared-collection-helpers-unchanged",
+    "local-vs-external-filtering-reuses-comboboxcollectionstate-staleness-guard-unchanged",
+    "empty-result-state-is-announced-once-not-per-section",
+    "no-global-shortcut-binding-is-owned-here-the-product-decides-the-trigger-key",
+    "activate-after-dismiss-lets-a-command-open-the-next-overlay-only-once-exit-completes",
+];
+//# sourceMappingURL=command-palette.js.map

package/dist/command-palette.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-palette.js","sourceRoot":"","sources":["../src/command-palette.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAsHtD,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,WAAW,EAAE,IAAI;IACjB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;CAC2B,CAAC;AAEjD,MAAM,UAAU,wBAAwB,CACtC,MAAmC,EACnC,SAAsC,8BAA8B;IAEpE,IAAI,MAAM,KAAK,cAAc,IAAI,MAAM,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IACtE,IAAI,CAAC,MAAM,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,cAAc,CAAC;IACvD,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,aAAa,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC;AAeD,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,SAAS,CAAC,kBAAkB,KAAK,oBAAoB,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,UAAoC;IAEpC,IAAI,UAAU,KAAK,IAAI,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,SAAS,CAAC,6CAA6C,CAAC,CAAC;IACrE,CAAC;IACD,cAAc,CAAC,UAAU,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IACpE,cAAc,CAAC,UAAU,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,KAAK,EAAE;QACL,UAAU;QACV,YAAY;QACZ,SAAS;QACT,aAAa;QACb,UAAU;QACV,SAAS;QACT,cAAc;QACd,MAAM;QACN,SAAS;QACT,MAAM;QACN,OAAO;QACP,aAAa;QACb,UAAU;QACV,YAAY;KACJ;IACV,QAAQ,EAAE,QAAQ,CAAC,KAAK;IACxB,OAAO,EAAE;QACP,UAAU,EAAE,uBAAuB,CAAC,UAAU;QAC9C,MAAM,EAAE,uBAAuB,CAAC,MAAM;QACtC,WAAW,EAAE,uBAAuB,CAAC,WAAW;QAChD,MAAM,EAAE,IAAa;QACrB,MAAM,EAAE,uBAAuB,CAAC,MAAM;QACtC,QAAQ,EAAE,GAAG;QACb,SAAS,EAAE,GAAG;KACf;IACD,WAAW,EAAE;QACX,SAAS,EAAE,kBAAkB,CAAC,SAAS;QACvC,iBAAiB,EAAE,kBAAkB,CAAC,iBAAiB;QACvD,WAAW,EAAE,kBAAkB,CAAC,MAAM;KACvC;IACD,IAAI,EAAE,sBAAsB;IAC5B,YAAY,EAAE;QACZ,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;QACvC,WAAW,EAAE,OAAgB;QAC7B,iBAAiB,EAAE,OAAO,CAAC,EAAE;QAC7B,eAAe,EAAE,OAAO,CAAC,EAAE;KAC5B;IACD,UAAU,EAAE;QACV,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;QACvC,WAAW,EAAE,MAAe;QAC5B,eAAe,EAAE,OAAO,CAAC,EAAE;KAC5B;IACD,UAAU,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE;CAC1D,CAAC;AAEX,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,4EAA4E;IAC5E,sDAAsD;IACtD,oFAAoF;IACpF,iFAAiF;IACjF,sFAAsF;IACtF,sDAAsD;IACtD,8EAA8E;IAC9E,sFAAsF;CAC9E,CAAC","sourcesContent":["import type { CollectionKey, ComboboxInput, MenuItemDescriptor } from \"./behaviors.js\";\nimport type { CollectionSource, ComboboxCollectionState } from \"./collection.js\";\nimport {\n  collectionItemContract,\n  fieldFrameContract,\n  floatingSurfaceContract,\n} from \"./component-contracts.js\";\nimport { backdrop, motionPreset, spacing } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * antd has no direct crosswalk target for CommandPalette — it is not in\n * `antDesignReferenceComponents`. The nearest antd surface, `AutoComplete`/\n * `Select` with `showSearch`, is exactly the composition question this\n * module answers below, not a separate coverage gap.\n *\n * Decisive difference from Combobox: **a result is an action, not a\n * persisted value.** Committing a Combobox sets `selectedKey` as the field's\n * ongoing value, and `inputValue` goes on mirroring it. Running \"새 트윗\n * 작성\" has no ongoing value anywhere to remember — the palette closes and\n * resets. Forcing `selectedKey`/`onCommit` onto that would create a\n * phantom value that is always `null` again the instant the palette reopens,\n * the same category of dead-state mistake `docs/dropdown.md` avoided by not\n * re-defining Menu's problem under a second name. So items here are shaped\n * like `MenuItemDescriptor` (carries `shortcut`/`tone` for destructive\n * commands), not `SelectItemDescriptor` (which deliberately strips both,\n * because a Select option is a value, not an action).\n *\n * Everything else composes from existing contracts without changes:\n * - **Heterogeneous sources** (\"최근\" / \"명령어\" / \"검색 결과\" in one list):\n *   already representable — `CollectionSource`'s `sections` is exactly\n *   grouped items, no new data model.\n * - **Search/filter text**: `ComboboxInput` (inputValue/defaultInputValue/\n *   onInputValueChange) and `ComboboxCollectionState` (local vs. external\n *   filtering, `queryValue`/`resultQuery` staleness guard) are reused\n *   verbatim — a command search is the same async-search problem Combobox\n *   already solved, just over commands instead of selectable values.\n * - **Keyboard navigation/typeahead across sections**: `getCollectionNavigationTarget`/\n *   `getCollectionTypeaheadMatch` (`src/collection.ts`) already generalize\n *   over any `CollectionSource`; nothing palette-specific to add.\n * - **Global keyboard shortcut** (⌘K): explicitly out of scope. Which key\n *   combination opens the palette, and whether it is global or scoped, is a\n *   product/app decision — the same reason Link does not own navigation and\n *   BottomNavigation does not own the router's route state.\n */\nexport type CommandPaletteItemDescriptor<Key extends CollectionKey = CollectionKey> =\n  MenuItemDescriptor<Key>;\n\nexport type CommandPaletteSource<\n  Key extends CollectionKey = CollectionKey,\n  SectionKey extends CollectionKey = CollectionKey,\n> = CollectionSource<Key, SectionKey>;\n\nexport type CommandPaletteInput = ComboboxInput;\nexport type CommandPaletteQueryState = ComboboxCollectionState;\n\nexport type CommandPaletteActivateReason = \"pointer\" | \"keyboard\";\n\n/**\n * Mirrors Menu's `onAction`/`onActionAfterDismiss` split (`behaviorRegistry.menu`)\n * without importing it — Menu, like Dialog, predates the per-component\n * `src/<name>.ts` convention and has no exported type of its own to import,\n * only string literals in the shared registry. `onActivate` fires\n * immediately; `onActivateAfterDismiss` fires once the exit transition\n * completes, for a command that itself opens another overlay (the same\n * \"close first, open the next surface after exit completes\" ordering\n * `docs/architecture.md`'s overlay-stack rule already requires).\n */\nexport type CommandPaletteActivateHandler<Key extends CollectionKey = CollectionKey> = (\n  itemId: Key,\n  reason: CommandPaletteActivateReason,\n) => void;\n\n/**\n * Web-only modal overlay (catalog: `platform: \"web\"`) — there is no `modal`\n * axis the way SidePanel needs one; a command palette is always a modal\n * takeover, never an inline non-modal surface. No `back`/`swipe` for the\n * same web-only reason `SidePanelDismissReason` excludes them.\n *\n * `\"activation\"` is a dismiss reason, not merely an event: running a command\n * always closes the palette, which is why `canDismissCommandPalette` treats\n * it like `\"programmatic\"` — an owner-level certainty no policy can veto.\n * There is no `busy` axis blocking dismissal while a command executes: the\n * palette itself is fire-and-forget (`onActivate` fires and the palette\n * closes); if the command's own effect is asynchronous, that runs after the\n * palette is already gone, the same ordering Menu's `onActionAfterDismiss`\n * already models. Recreating AlertDialog's `idle→busy→error` session here\n * would be guessing at a requirement (a command that must block the palette\n * open until it settles) with no measured product need.\n */\nexport type CommandPaletteDismissReason =\n  | \"close-action\"\n  | \"outside\"\n  | \"escape\"\n  | \"activation\"\n  | \"programmatic\";\n\nexport type CommandPaletteOpenChangeDetails = Readonly<{\n  reason: \"trigger\" | CommandPaletteDismissReason;\n}>;\n\nexport type ControlledCommandPaletteOpenState = Readonly<{\n  open: boolean;\n  defaultOpen?: never;\n  onOpenChange(open: boolean, details: CommandPaletteOpenChangeDetails): void;\n}>;\n\nexport type UncontrolledCommandPaletteOpenState = Readonly<{\n  open?: never;\n  defaultOpen?: boolean;\n  onOpenChange?: (\n    open: boolean,\n    details: CommandPaletteOpenChangeDetails,\n  ) => void;\n}>;\n\nexport type CommandPaletteOpenState =\n  | ControlledCommandPaletteOpenState\n  | UncontrolledCommandPaletteOpenState;\n\nexport type CommandPaletteDismissPolicy = Readonly<{\n  dismissible: boolean;\n  outsideDismiss: boolean;\n  escapeDismiss: boolean;\n}>;\n\nexport const commandPaletteBehaviorDefaults = {\n  dismissible: true,\n  outsideDismiss: true,\n  escapeDismiss: true,\n} as const satisfies CommandPaletteDismissPolicy;\n\nexport function canDismissCommandPalette(\n  reason: CommandPaletteDismissReason,\n  policy: CommandPaletteDismissPolicy = commandPaletteBehaviorDefaults,\n): boolean {\n  if (reason === \"programmatic\" || reason === \"activation\") return true;\n  if (!policy.dismissible) return false;\n  if (reason === \"outside\") return policy.outsideDismiss;\n  if (reason === \"escape\") return policy.escapeDismiss;\n  return true;\n}\n\n/**\n * `accessibilityLabel` is required, not optional like Popover's — a command\n * palette's `role=\"dialog\"` surface has no visible heading the way Dialog's\n * `title` slot or typical Popover content provides; the search field alone\n * is not a reliable accessible name across renderers. `searchPlaceholder` is\n * required for the same reason `LoadMoreLabels`/`PaginationLabels` require\n * every field: a renderer must not invent untranslated fallback copy.\n */\nexport type CommandPaletteDescriptor = Readonly<{\n  accessibilityLabel: string;\n  searchPlaceholder: string;\n}>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`CommandPalette ${field} must not be empty`);\n  }\n}\n\nexport function validateCommandPaletteDescriptor(\n  descriptor: CommandPaletteDescriptor,\n): void {\n  if (descriptor === null || typeof descriptor !== \"object\") {\n    throw new TypeError(\"CommandPalette descriptor must be an object\");\n  }\n  assertNonEmpty(descriptor.accessibilityLabel, \"accessibilityLabel\");\n  assertNonEmpty(descriptor.searchPlaceholder, \"searchPlaceholder\");\n}\n\n/**\n * Anatomy only — chrome for the modal shell and the pinned search field,\n * reusing the exact tokens Dialog-family and Menu-family recipes already use\n * (`floatingSurfaceContract`, `fieldFrameContract`, `collectionItemContract`)\n * instead of inventing new ones. Result rows and section labels reuse\n * `collectionItemContract` the same way `menuRecipe`/`treeRecipe` do — a\n * command result is chrome-identical to a Menu item, it just lives in a\n * modal instead of an anchored popup.\n */\nexport const commandPaletteRecipe = {\n  slots: [\n    \"backdrop\",\n    \"positioner\",\n    \"content\",\n    \"searchField\",\n    \"viewport\",\n    \"section\",\n    \"sectionLabel\",\n    \"item\",\n    \"leading\",\n    \"copy\",\n    \"label\",\n    \"description\",\n    \"shortcut\",\n    \"emptyState\",\n  ] as const,\n  backdrop: backdrop.modal,\n  content: {\n    background: floatingSurfaceContract.background,\n    border: floatingSurfaceContract.border,\n    borderWidth: floatingSurfaceContract.borderWidth,\n    radius: \"lg\" as const,\n    shadow: floatingSurfaceContract.shadow,\n    maxWidth: 560,\n    maxHeight: 420,\n  },\n  searchField: {\n    minHeight: fieldFrameContract.minHeight,\n    paddingHorizontal: fieldFrameContract.paddingHorizontal,\n    borderColor: fieldFrameContract.border,\n  },\n  item: collectionItemContract,\n  sectionLabel: {\n    color: semanticColors.content.secondary,\n    textVariant: \"label\" as const,\n    paddingHorizontal: spacing.sm,\n    paddingVertical: spacing.xs,\n  },\n  emptyState: {\n    color: semanticColors.content.secondary,\n    textVariant: \"body\" as const,\n    paddingVertical: spacing.xl,\n  },\n  transition: { enter: motionPreset.enter, exit: motionPreset.exit },\n} as const;\n\nexport const commandPaletteBehaviorScenarios = [\n  \"activating-a-result-always-closes-the-palette-regardless-of-dismiss-policy\",\n  \"escape-and-outside-close-without-running-any-command\",\n  \"sections-merge-recents-static-commands-and-search-results-without-a-new-data-model\",\n  \"keyboard-navigation-and-typeahead-reuse-the-shared-collection-helpers-unchanged\",\n  \"local-vs-external-filtering-reuses-comboboxcollectionstate-staleness-guard-unchanged\",\n  \"empty-result-state-is-announced-once-not-per-section\",\n  \"no-global-shortcut-binding-is-owned-here-the-product-decides-the-trigger-key\",\n  \"activate-after-dismiss-lets-a-command-open-the-next-overlay-only-once-exit-completes\",\n] as const;\n"]}

package/dist/component-contracts.d.ts

@@ -0,0 +1,137 @@
+/** Internal visual fragments keep future recipes from inventing new chrome. */
+export declare const focusIndicatorContract: {
+    readonly color: Readonly<{
+        source: "theme";
+        key: "contentBrand";
+        alpha?: number;
+    }>;
+    readonly width: 2;
+    readonly offset: 2;
+};
+export declare const fieldFrameContract: {
+    readonly background: Readonly<{
+        source: "theme";
+        key: "surface";
+        alpha?: number;
+    }>;
+    readonly border: Readonly<{
+        source: "theme";
+        key: "textMuted";
+        alpha?: number;
+    }>;
+    readonly focusBorder: Readonly<{
+        source: "theme";
+        key: "contentBrand";
+        alpha?: number;
+    }>;
+    readonly invalidBorder: Readonly<{
+        source: "theme";
+        key: "danger";
+        alpha?: number;
+    }>;
+    readonly radius: "md";
+    readonly borderWidth: 1;
+    readonly minHeight: 44;
+    readonly paddingHorizontal: 16;
+};
+export declare const formSupportContract: {
+    readonly label: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly textVariant: "body";
+        readonly fontWeight: "600";
+    };
+    readonly hint: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+    };
+    readonly error: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+    };
+    readonly gap: 8;
+};
+export declare const floatingSurfaceContract: {
+    readonly background: Readonly<{
+        source: "theme";
+        key: "bg";
+        alpha?: number;
+    }>;
+    readonly border: Readonly<{
+        source: "theme";
+        key: "border";
+        alpha?: number;
+    }>;
+    readonly borderWidth: 1;
+    readonly radius: "md";
+    readonly shadow: {
+        readonly color: "#000000";
+        readonly opacity: 0.12;
+        readonly radius: 12;
+        readonly offsetY: 4;
+    };
+    readonly padding: 8;
+};
+export declare const collectionItemContract: {
+    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;
+    }>;
+};
+//# sourceMappingURL=component-contracts.d.ts.map

package/dist/component-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-contracts.d.ts","sourceRoot":"","sources":["../src/component-contracts.ts"],"names":[],"mappings":"AAGA,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB;;;;;;;;CAIzB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;CASrB,CAAC;AAEX,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;CAStB,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;CAO1B,CAAC;AAEX,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAezB,CAAC"}

package/dist/component-contracts.js

@@ -0,0 +1,53 @@
+import { fontWeight, shadow, spacing, stroke } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+/** Internal visual fragments keep future recipes from inventing new chrome. */
+export const focusIndicatorContract = {
+    color: semanticColors.border.focus,
+    width: stroke.focus,
+    offset: 2,
+};
+export const fieldFrameContract = {
+    background: semanticColors.surface.default,
+    border: semanticColors.content.secondary,
+    focusBorder: semanticColors.border.focus,
+    invalidBorder: semanticColors.border.danger,
+    radius: "md",
+    borderWidth: stroke.default,
+    minHeight: 44,
+    paddingHorizontal: spacing.md,
+};
+export const formSupportContract = {
+    label: {
+        color: semanticColors.content.body,
+        textVariant: "body",
+        fontWeight: fontWeight.semibold,
+    },
+    hint: { color: semanticColors.content.secondary, textVariant: "label" },
+    error: { color: semanticColors.content.danger, textVariant: "label" },
+    gap: spacing.xs,
+};
+export const floatingSurfaceContract = {
+    background: semanticColors.canvas,
+    border: semanticColors.border.default,
+    borderWidth: stroke.default,
+    radius: "md",
+    shadow: shadow.floating,
+    padding: spacing.xs,
+};
+export const collectionItemContract = {
+    minHeight: 44,
+    paddingHorizontal: spacing.sm,
+    gap: spacing.sm,
+    radius: "md",
+    label: { color: semanticColors.content.body, textVariant: "body" },
+    description: {
+        color: semanticColors.content.secondary,
+        textVariant: "label",
+    },
+    highlightedBackground: semanticColors.interaction.hover,
+    focus: focusIndicatorContract,
+    selectedBackground: semanticColors.interaction.selected,
+    selectedIndicator: semanticColors.border.focus,
+    danger: semanticColors.content.danger,
+};
+//# sourceMappingURL=component-contracts.js.map

package/dist/component-contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-contracts.js","sourceRoot":"","sources":["../src/component-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK;IAClC,KAAK,EAAE,MAAM,CAAC,KAAK;IACnB,MAAM,EAAE,CAAC;CACD,CAAC;AAEX,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC,OAAO;IAC1C,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;IACxC,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK;IACxC,aAAa,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM;IAC3C,MAAM,EAAE,IAAa;IACrB,WAAW,EAAE,MAAM,CAAC,OAAO;IAC3B,SAAS,EAAE,EAAE;IACb,iBAAiB,EAAE,OAAO,CAAC,EAAE;CACrB,CAAC;AAEX,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,KAAK,EAAE;QACL,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;QAClC,WAAW,EAAE,MAAe;QAC5B,UAAU,EAAE,UAAU,CAAC,QAAQ;KAChC;IACD,IAAI,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,EAAE,OAAgB,EAAE;IAChF,KAAK,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,OAAgB,EAAE;IAC9E,GAAG,EAAE,OAAO,CAAC,EAAE;CACP,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU,EAAE,cAAc,CAAC,MAAM;IACjC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO;IACrC,WAAW,EAAE,MAAM,CAAC,OAAO;IAC3B,MAAM,EAAE,IAAa;IACrB,MAAM,EAAE,MAAM,CAAC,QAAQ;IACvB,OAAO,EAAE,OAAO,CAAC,EAAE;CACX,CAAC;AAEX,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,SAAS,EAAE,EAAE;IACb,iBAAiB,EAAE,OAAO,CAAC,EAAE;IAC7B,GAAG,EAAE,OAAO,CAAC,EAAE;IACf,MAAM,EAAE,IAAa;IACrB,KAAK,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,MAAe,EAAE;IAC3E,WAAW,EAAE;QACX,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;QACvC,WAAW,EAAE,OAAgB;KAC9B;IACD,qBAAqB,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK;IACvD,KAAK,EAAE,sBAAsB;IAC7B,kBAAkB,EAAE,cAAc,CAAC,WAAW,CAAC,QAAQ;IACvD,iBAAiB,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK;IAC9C,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM;CAC7B,CAAC","sourcesContent":["import { fontWeight, shadow, spacing, stroke } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/** Internal visual fragments keep future recipes from inventing new chrome. */\nexport const focusIndicatorContract = {\n  color: semanticColors.border.focus,\n  width: stroke.focus,\n  offset: 2,\n} as const;\n\nexport const fieldFrameContract = {\n  background: semanticColors.surface.default,\n  border: semanticColors.content.secondary,\n  focusBorder: semanticColors.border.focus,\n  invalidBorder: semanticColors.border.danger,\n  radius: \"md\" as const,\n  borderWidth: stroke.default,\n  minHeight: 44,\n  paddingHorizontal: spacing.md,\n} as const;\n\nexport const formSupportContract = {\n  label: {\n    color: semanticColors.content.body,\n    textVariant: \"body\" as const,\n    fontWeight: fontWeight.semibold,\n  },\n  hint: { color: semanticColors.content.secondary, textVariant: \"label\" as const },\n  error: { color: semanticColors.content.danger, textVariant: \"label\" as const },\n  gap: spacing.xs,\n} as const;\n\nexport const floatingSurfaceContract = {\n  background: semanticColors.canvas,\n  border: semanticColors.border.default,\n  borderWidth: stroke.default,\n  radius: \"md\" as const,\n  shadow: shadow.floating,\n  padding: spacing.xs,\n} as const;\n\nexport const collectionItemContract = {\n  minHeight: 44,\n  paddingHorizontal: spacing.sm,\n  gap: spacing.sm,\n  radius: \"md\" as const,\n  label: { color: semanticColors.content.body, textVariant: \"body\" as const },\n  description: {\n    color: semanticColors.content.secondary,\n    textVariant: \"label\" as const,\n  },\n  highlightedBackground: semanticColors.interaction.hover,\n  focus: focusIndicatorContract,\n  selectedBackground: semanticColors.interaction.selected,\n  selectedIndicator: semanticColors.border.focus,\n  danger: semanticColors.content.danger,\n} as const;\n"]}