acture-palette-react 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,135 @@
+import { Registry, Context, Tier, AnyCommandRecord, Result, CommandKind } from 'acture';
+import { z } from 'zod';
+
+/**
+ * `<CommandPalette />` — Phase 2 implementation.
+ *
+ * Adds parameterized-command support per research-2 §9 (and the
+ * `acture-palette-design` skill):
+ *
+ *   - `deriveKind(command)` returns 'atomic' | 'handoff'. Authors may
+ *     override via `record.kind`.
+ *   - 'atomic' commands render an inline picker chain INSIDE the
+ *     palette (Linear / Discord chip-style).
+ *   - 'handoff' commands either render a host-supplied form inline
+ *     (when `formAdapter` is provided) or fall back to firing
+ *     `onParameterizedSelect` for the host to open its own form view.
+ *
+ * Phase 1 behavior is preserved for parameter-free commands and for
+ * hosts that supply neither a form adapter nor a parameterized-select
+ * callback — the palette just closes the picker view.
+ *
+ * Per `acture-hard-donts` skill: no bundled UI kit. All elements use
+ * cmdk's built-in classes plus consumer-supplied className overrides.
+ */
+
+type PaletteItemRenderer = (cmd: AnyCommandRecord) => React.ReactNode;
+/** Props the palette passes to a host-supplied form adapter. The host
+ *  renders a form derived from `command.params` and calls `onSubmit`
+ *  with the validated params (or `onCancel`). */
+interface PaletteFormAdapterProps {
+    command: AnyCommandRecord;
+    defaults?: Record<string, unknown>;
+    onSubmit: (params: unknown) => void;
+    onCancel: () => void;
+}
+type PaletteFormAdapter = React.ComponentType<PaletteFormAdapterProps>;
+interface CommandPaletteProps {
+    /** The acture registry. */
+    registry: Registry;
+    /** Optional context for when-clause filtering and dispatch. */
+    context?: Context;
+    /** Tier filter. Default: `['stable']`. */
+    tiers?: readonly Tier[] | 'all';
+    /** Called when a dispatch (parameter-free OR parameterized) finishes. */
+    onDispatched?: (cmd: AnyCommandRecord, result: Result<unknown>) => void;
+    /** Fired when the user picks a `handoff` command and no `formAdapter`
+     *  is configured. Hosts that want to open their own form view should
+     *  handle this. */
+    onParameterizedSelect?: (cmd: AnyCommandRecord) => void;
+    /** Optional form adapter for `handoff` commands. When present, the
+     *  palette switches its inner view to this component instead of
+     *  closing. Plug in `acture-forms-autoform` or `acture-forms-rjsf`. */
+    formAdapter?: PaletteFormAdapter;
+    /** Per-field defaults injected into the picker chain / form. Useful
+     *  for context-aware prefill (Things-style — research-2 §9.4). */
+    paramDefaults?: (cmd: AnyCommandRecord) => Record<string, unknown> | undefined;
+    placeholder?: string;
+    className?: string;
+    /** Custom item renderer for the list view. */
+    renderItem?: PaletteItemRenderer;
+}
+declare function CommandPalette(props: CommandPaletteProps): React.ReactElement;
+
+/**
+ * Subscribe to a registry's `commandsChanged` event from inside React.
+ *
+ * Returns a monotonically-incrementing `revision` integer that changes
+ * whenever a command is added or removed. Useful as a key for
+ * `useMemo` over the command list.
+ */
+
+declare function useCommandsChanged(registry: Registry): number;
+
+/**
+ * Auto-derived `kind` heuristic per research-2 §9.3 (acture-palette-design
+ * skill). Determines whether a parameterized command should be collected
+ * inline (atomic picker chain) or handed off to a dedicated form.
+ *
+ *   0 params                                           → atomic
+ *   1–2 params, all picker-typed                       → atomic
+ *   3 params, all picker-typed AND all have defaults   → atomic
+ *   else                                               → handoff
+ *
+ * "Picker-typed" = the param has a discrete, enumerable value space
+ * (enum, boolean) OR is a string carrying an explicit `paramKind: 'picker'`
+ * extension hint via `.describe()`. Unconstrained `z.string()` and
+ * `z.number()` are NOT picker-typed.
+ *
+ * Authors override by setting `kind` explicitly on the CommandRecord.
+ */
+
+interface ParamSummary {
+    readonly name: string;
+    readonly schema: z.ZodTypeAny;
+    readonly isPicker: boolean;
+    readonly hasDefault: boolean;
+    readonly optional: boolean;
+}
+/** Inspect a Zod schema and produce per-field summaries for deriveKind
+ *  and the picker-chain renderer. Defensive against non-object schemas. */
+declare function summarizeParams(record: AnyCommandRecord): ParamSummary[];
+/** Auto-derive `kind` from the param summary; explicit `kind` wins. */
+declare function deriveKind(record: AnyCommandRecord): CommandKind;
+/** Picker-typed = discrete, enumerable value space. */
+declare function isPickerSchema(s: z.ZodTypeAny): boolean;
+/** Read enum options for picker rendering. Returns [] for non-enums. */
+declare function readEnumOptions(s: z.ZodTypeAny): string[];
+
+/**
+ * Atomic picker-chain UI rendered INSIDE the palette container.
+ *
+ * Used when `deriveKind(record) === 'atomic'` for parameterized
+ * commands. Each step shows a labeled picker / input for one param;
+ * Enter advances when valid; Esc backs up to the previous step (or
+ * cancels at step 0).
+ *
+ * Per research-2 §9.4: per-step validation inline, step counter `n/N`
+ * only when N ≥ 2, Tab/Enter both advance, Esc backs up.
+ *
+ * This is deliberately minimal — a host that wants richer field
+ * widgets can pass a custom `pickerRenderer`.
+ */
+
+interface PickerChainProps {
+    command: AnyCommandRecord;
+    /** Initial values (e.g. defaults derived from context). */
+    defaults?: Record<string, unknown>;
+    /** Called when the user finishes the last step. */
+    onSubmit: (params: Record<string, unknown>) => void;
+    /** Called when the user cancels (Esc at step 0). */
+    onCancel: () => void;
+}
+declare function PickerChain(props: PickerChainProps): React.ReactElement;
+
+export { CommandPalette, type CommandPaletteProps, type PaletteFormAdapter, type PaletteFormAdapterProps, type PaletteItemRenderer, type ParamSummary, PickerChain, type PickerChainProps, deriveKind, isPickerSchema, readEnumOptions, summarizeParams, useCommandsChanged };

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import { Registry, Context, Tier, AnyCommandRecord, Result, CommandKind } from 'acture';
+import { z } from 'zod';
+
+/**
+ * `<CommandPalette />` — Phase 2 implementation.
+ *
+ * Adds parameterized-command support per research-2 §9 (and the
+ * `acture-palette-design` skill):
+ *
+ *   - `deriveKind(command)` returns 'atomic' | 'handoff'. Authors may
+ *     override via `record.kind`.
+ *   - 'atomic' commands render an inline picker chain INSIDE the
+ *     palette (Linear / Discord chip-style).
+ *   - 'handoff' commands either render a host-supplied form inline
+ *     (when `formAdapter` is provided) or fall back to firing
+ *     `onParameterizedSelect` for the host to open its own form view.
+ *
+ * Phase 1 behavior is preserved for parameter-free commands and for
+ * hosts that supply neither a form adapter nor a parameterized-select
+ * callback — the palette just closes the picker view.
+ *
+ * Per `acture-hard-donts` skill: no bundled UI kit. All elements use
+ * cmdk's built-in classes plus consumer-supplied className overrides.
+ */
+
+type PaletteItemRenderer = (cmd: AnyCommandRecord) => React.ReactNode;
+/** Props the palette passes to a host-supplied form adapter. The host
+ *  renders a form derived from `command.params` and calls `onSubmit`
+ *  with the validated params (or `onCancel`). */
+interface PaletteFormAdapterProps {
+    command: AnyCommandRecord;
+    defaults?: Record<string, unknown>;
+    onSubmit: (params: unknown) => void;
+    onCancel: () => void;
+}
+type PaletteFormAdapter = React.ComponentType<PaletteFormAdapterProps>;
+interface CommandPaletteProps {
+    /** The acture registry. */
+    registry: Registry;
+    /** Optional context for when-clause filtering and dispatch. */
+    context?: Context;
+    /** Tier filter. Default: `['stable']`. */
+    tiers?: readonly Tier[] | 'all';
+    /** Called when a dispatch (parameter-free OR parameterized) finishes. */
+    onDispatched?: (cmd: AnyCommandRecord, result: Result<unknown>) => void;
+    /** Fired when the user picks a `handoff` command and no `formAdapter`
+     *  is configured. Hosts that want to open their own form view should
+     *  handle this. */
+    onParameterizedSelect?: (cmd: AnyCommandRecord) => void;
+    /** Optional form adapter for `handoff` commands. When present, the
+     *  palette switches its inner view to this component instead of
+     *  closing. Plug in `acture-forms-autoform` or `acture-forms-rjsf`. */
+    formAdapter?: PaletteFormAdapter;
+    /** Per-field defaults injected into the picker chain / form. Useful
+     *  for context-aware prefill (Things-style — research-2 §9.4). */
+    paramDefaults?: (cmd: AnyCommandRecord) => Record<string, unknown> | undefined;
+    placeholder?: string;
+    className?: string;
+    /** Custom item renderer for the list view. */
+    renderItem?: PaletteItemRenderer;
+}
+declare function CommandPalette(props: CommandPaletteProps): React.ReactElement;
+
+/**
+ * Subscribe to a registry's `commandsChanged` event from inside React.
+ *
+ * Returns a monotonically-incrementing `revision` integer that changes
+ * whenever a command is added or removed. Useful as a key for
+ * `useMemo` over the command list.
+ */
+
+declare function useCommandsChanged(registry: Registry): number;
+
+/**
+ * Auto-derived `kind` heuristic per research-2 §9.3 (acture-palette-design
+ * skill). Determines whether a parameterized command should be collected
+ * inline (atomic picker chain) or handed off to a dedicated form.
+ *
+ *   0 params                                           → atomic
+ *   1–2 params, all picker-typed                       → atomic
+ *   3 params, all picker-typed AND all have defaults   → atomic
+ *   else                                               → handoff
+ *
+ * "Picker-typed" = the param has a discrete, enumerable value space
+ * (enum, boolean) OR is a string carrying an explicit `paramKind: 'picker'`
+ * extension hint via `.describe()`. Unconstrained `z.string()` and
+ * `z.number()` are NOT picker-typed.
+ *
+ * Authors override by setting `kind` explicitly on the CommandRecord.
+ */
+
+interface ParamSummary {
+    readonly name: string;
+    readonly schema: z.ZodTypeAny;
+    readonly isPicker: boolean;
+    readonly hasDefault: boolean;
+    readonly optional: boolean;
+}
+/** Inspect a Zod schema and produce per-field summaries for deriveKind
+ *  and the picker-chain renderer. Defensive against non-object schemas. */
+declare function summarizeParams(record: AnyCommandRecord): ParamSummary[];
+/** Auto-derive `kind` from the param summary; explicit `kind` wins. */
+declare function deriveKind(record: AnyCommandRecord): CommandKind;
+/** Picker-typed = discrete, enumerable value space. */
+declare function isPickerSchema(s: z.ZodTypeAny): boolean;
+/** Read enum options for picker rendering. Returns [] for non-enums. */
+declare function readEnumOptions(s: z.ZodTypeAny): string[];
+
+/**
+ * Atomic picker-chain UI rendered INSIDE the palette container.
+ *
+ * Used when `deriveKind(record) === 'atomic'` for parameterized
+ * commands. Each step shows a labeled picker / input for one param;
+ * Enter advances when valid; Esc backs up to the previous step (or
+ * cancels at step 0).
+ *
+ * Per research-2 §9.4: per-step validation inline, step counter `n/N`
+ * only when N ≥ 2, Tab/Enter both advance, Esc backs up.
+ *
+ * This is deliberately minimal — a host that wants richer field
+ * widgets can pass a custom `pickerRenderer`.
+ */
+
+interface PickerChainProps {
+    command: AnyCommandRecord;
+    /** Initial values (e.g. defaults derived from context). */
+    defaults?: Record<string, unknown>;
+    /** Called when the user finishes the last step. */
+    onSubmit: (params: Record<string, unknown>) => void;
+    /** Called when the user cancels (Esc at step 0). */
+    onCancel: () => void;
+}
+declare function PickerChain(props: PickerChainProps): React.ReactElement;
+
+export { CommandPalette, type CommandPaletteProps, type PaletteFormAdapter, type PaletteFormAdapterProps, type PaletteItemRenderer, type ParamSummary, PickerChain, type PickerChainProps, deriveKind, isPickerSchema, readEnumOptions, summarizeParams, useCommandsChanged };