@stridge/noctis 1.0.0-beta.5 → 1.0.0-beta.6

package/dist/components/command/command.d.ts

@@ -0,0 +1,396 @@
+import { useRender } from "../../core/render.js";
+import { CommandPage } from "./command.context.js";
+import { CommandPartProps, breadcrumbProps, emptyProps, footerProps, groupLabelProps, groupProps, headerProps, inputActionProps, inputProps, itemIconProps, itemLabelProps, itemProps, listProps, loadingProps, panelProps, separatorProps } from "./command.props.js";
+import { ComponentPropsWithoutRef, ReactElement, ReactNode, Ref } from "react";
+
+//#region src/components/command/command.d.ts
+/** The query + drill-in state both mounting modes share, wired into the listbox engine and the context. */
+interface PaletteStateProps {
+  /** The query value (controlled). */
+  value?: string;
+  /** The initial query when uncontrolled. */
+  defaultValue?: string;
+  /** Called as the query changes. */
+  onValueChange?: (value: string) => void;
+  /**
+   * The drill-in stack (controlled). Selecting a parent command pushes a page; Backspace on the empty
+   * query — or clicking an earlier breadcrumb — pops. The consumer owns the stack so children can load
+   * lazily; map the current page to the rendered `Command.Item`s.
+   */
+  pages?: readonly CommandPage[];
+  /** Called when the drill-in stack should change (push on select, pop on Backspace/breadcrumb). */
+  onPagesChange?: (pages: readonly CommandPage[]) => void;
+  /** Whether async results are still settling; drives the loading/empty copy and `aria-busy`. */
+  loading?: boolean;
+  /**
+   * Whether arrow-key navigation cycles past the ends of the list — `ArrowDown` from the last row
+   * wraps back to the first (through the input, per the ARIA combobox pattern) and `ArrowUp` from the
+   * first wraps to the last. Off by default: the highlight stops at the ends, matching a command bar.
+   * @default false
+   */
+  loop?: boolean;
+}
+/** Props for {@link CommandRoot}. */
+interface CommandRootProps extends PaletteStateProps, Omit<ComponentPropsWithoutRef<"div">, "defaultValue"> {
+  /** The palette parts — a `Command.Header`, a `Command.List`, and an optional `Command.Footer`. */
+  children?: ReactNode;
+}
+/**
+ * The inline palette: the command interface embedded in normal flow (a page, a sidebar, a settings
+ * panel) rather than a modal. Renders the panel through `Surface` (the `menu` elevation scope, border,
+ * and card shadow) and shares the query + drill-in state with every part. For the modal launcher use
+ * `Command.Dialog`; both share identical inner parts.
+ *
+ * @see {@link CommandRootProps}
+ */
+declare function CommandRoot({
+  value,
+  defaultValue,
+  onValueChange,
+  pages,
+  onPagesChange,
+  loading,
+  loop,
+  children,
+  ...props
+}: CommandRootProps): ReactElement;
+/** Props for {@link CommandDialog}. */
+interface CommandDialogProps extends PaletteStateProps {
+  /** Whether the modal palette is open. */
+  open: boolean;
+  /** Called when the open state should change (backdrop, Esc, dismissal). */
+  onOpenChange: (open: boolean) => void;
+  /**
+   * The dialog's accessible name (rendered visually hidden; the palette has no visible heading).
+   * Defaults to the localized `command.label` string from the Noctis i18n catalog ("Command palette").
+   */
+  label?: string;
+  /** The palette parts — a `Command.Header`, a `Command.List`, and an optional `Command.Footer`. */
+  children?: ReactNode;
+}
+/**
+ * The modal palette: the centred, focus-trapped command launcher built on the Noctis `Dialog` chassis
+ * (portal, blurred backdrop, scroll-lock, Esc/outside-click dismissal) with a top-anchored, fixed-height
+ * panel that scale-fades in. Wire `open`/`onOpenChange` to a `Command.Trigger` (or any control). Shares
+ * identical inner parts with the inline `Command.Root`.
+ *
+ * @see {@link CommandDialogProps}
+ */
+declare function CommandDialog({
+  open,
+  onOpenChange,
+  label,
+  value,
+  defaultValue,
+  onValueChange,
+  pages,
+  onPagesChange,
+  loading,
+  loop,
+  children
+}: CommandDialogProps): ReactElement;
+/** Props for {@link CommandTrigger}. */
+interface CommandTriggerProps extends ComponentPropsWithoutRef<"button"> {
+  /** Whether the palette this trigger opens is currently open (reflected as `aria-expanded`). */
+  open?: boolean;
+  /** Called to open the palette (fired on click). Wire it to the same setter as `Command.Dialog`. */
+  onOpenChange?: (open: boolean) => void;
+  /** A Base UI render prop — bring your own button/visuals; the trigger only wires behaviour + ARIA. */
+  render?: useRender.RenderProp;
+  /** Ref to the rendered element. */
+  ref?: Ref<HTMLButtonElement>;
+}
+/**
+ * A headless launcher for the modal palette. It wires only behaviour and accessibility — `onClick` to
+ * open, `aria-haspopup="dialog"`, and `aria-expanded` — onto whatever element you render, so you bring
+ * your own `Button`/`Kbd` visuals. Wire the same `open`/`onOpenChange` state you pass to `Command.Dialog`.
+ *
+ * @see {@link CommandTriggerProps}
+ */
+declare function CommandTrigger({
+  open,
+  onOpenChange,
+  render,
+  ref,
+  onClick,
+  ...props
+}: CommandTriggerProps): ReactElement;
+/** Props for {@link CommandHeader}. */
+interface CommandHeaderProps extends ComponentPropsWithoutRef<"div"> {}
+/** The input row: holds an optional `Command.Breadcrumb`, a leading glyph, the `Command.Input`, and an
+ * optional `Command.InputAction`, over a hairline divider. */
+declare function CommandHeader({
+  children,
+  ...props
+}: CommandHeaderProps): ReactElement;
+/** Props for {@link CommandBreadcrumb}. */
+interface CommandBreadcrumbProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {}
+/**
+ * The drill-in trail. Renders one button per page in the stack and nothing at the top level; clicking a
+ * segment truncates the stack back to its depth. Reads the stack from context — just drop it in the
+ * header.
+ */
+declare function CommandBreadcrumb(props: CommandBreadcrumbProps): ReactElement | null;
+/** Props for {@link CommandInput}. */
+interface CommandInputProps extends Omit<ComponentPropsWithoutRef<"input">, "value" | "onChange" | "type" | "role" | "aria-activedescendant"> {}
+/**
+ * The query field — a `role="combobox"` that keeps focus while a virtual cursor (`aria-activedescendant`)
+ * moves the active row. Typing filters (you rank externally); arrows / Home / End / PageUp-Down move the
+ * highlight, Enter activates it, and Backspace on an empty query pops the drill-in stack. The keyboard
+ * model is the palette's own (see `command-listbox`), not a delegated primitive's.
+ *
+ * @see {@link CommandInput.Props}
+ */
+declare function CommandInput({
+  onKeyDown,
+  ...props
+}: CommandInputProps): ReactElement;
+/** Props for {@link CommandInputAction}. */
+interface CommandInputActionProps extends ComponentPropsWithoutRef<"div"> {}
+/** A trailing affordance slot in the input row (a mode pill, an "ask" hand-off, a hint). */
+declare function CommandInputAction({
+  children,
+  ...props
+}: CommandInputActionProps): ReactElement;
+/** Props for {@link CommandList}. */
+interface CommandListProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "role"> {
+  /** The command rows and sections (rendered inside the measured sizer). */
+  children?: ReactNode;
+}
+/**
+ * The scrolling `role="listbox"` of command rows and sections. The rows render inside a measured sizer so
+ * the palette can animate its height as the result set changes (see {@link useListAutoHeight}). Within it,
+ * a per-page view wrapper is keyed by the drill-in depth: pushing or popping a page remounts it, so its
+ * CSS enter animation replays — the old view gives way and the new one opens — while a query change (same
+ * page) leaves it in place so typing doesn't re-animate.
+ */
+declare function CommandList({
+  children,
+  ...props
+}: CommandListProps): ReactElement;
+/** Props for {@link CommandGroup}. */
+interface CommandGroupProps extends Omit<ComponentPropsWithoutRef<"div">, "role"> {}
+/** A labelled section: a `role="group"` wrapping a `Command.GroupLabel` and its rows, `aria-labelledby`
+ * the label while one is rendered. */
+declare function CommandGroup({
+  children,
+  ...props
+}: CommandGroupProps): ReactElement;
+/** Props for {@link CommandGroupLabel}. */
+interface CommandGroupLabelProps extends Omit<ComponentPropsWithoutRef<"div">, "id"> {}
+/** A section heading (not an option). Lends its id to the enclosing `Command.Group`'s `aria-labelledby`. */
+declare function CommandGroupLabel({
+  children,
+  ...props
+}: CommandGroupLabelProps): ReactElement;
+/** Props for {@link CommandItem}. */
+interface CommandItemProps extends Omit<ComponentPropsWithoutRef<"div">, "id" | "role" | "onSelect"> {
+  /** A stable, unique value for the row (the React key / selection value). */
+  value: string;
+  /** Whether the row is disabled — non-activatable and skipped by keyboard navigation. */
+  disabled?: boolean;
+  /** Run when the row is activated by click or by Enter while highlighted. */
+  onSelect?: (value: string) => void;
+}
+/**
+ * One command row (`role="option"`). Activated by click or by pressing Enter while highlighted
+ * (`onSelect`). Compose a `Command.ItemIcon` and a `Command.ItemLabel` inside; any further content (a
+ * `Kbd` shortcut, a badge, a count) is pushed to the row's end by the label's `flex` — the row stays
+ * yours to fill past the icon. Hovering highlights it; the keyboard highlight (`data-highlighted`, the
+ * input's `aria-activedescendant`) is the palette's own; activation runs the action, never fills the query.
+ *
+ * @see {@link CommandItem.Props}
+ */
+declare function CommandItem({
+  value,
+  disabled,
+  onSelect,
+  onClick,
+  onPointerMove,
+  children,
+  ...props
+}: CommandItemProps): ReactElement;
+/** Props for {@link CommandItemIcon}. */
+interface CommandItemIconProps extends ComponentPropsWithoutRef<"span"> {}
+/** The leading glyph column of a row (wrap an `Icon` so it keeps its token sizing). */
+declare function CommandItemIcon({
+  children,
+  ...props
+}: CommandItemIconProps): ReactElement;
+/** Props for {@link CommandItemLabel}. */
+interface CommandItemLabelProps extends ComponentPropsWithoutRef<"span"> {}
+/** The row's text column (truncates rather than wrapping). */
+declare function CommandItemLabel({
+  children,
+  ...props
+}: CommandItemLabelProps): ReactElement;
+/** Props for {@link CommandSeparator}. */
+interface CommandSeparatorProps extends ComponentPropsWithoutRef<"div"> {}
+/** A thin divider between sections. */
+declare function CommandSeparator(props: CommandSeparatorProps): ReactElement;
+/** Props for {@link CommandEmpty}. */
+interface CommandEmptyProps extends ComponentPropsWithoutRef<"div"> {}
+/**
+ * The centred no-results message. A polite live region so screen readers announce it; render it
+ * conditionally when your ranked list is empty (you own the data, so you know when there's nothing to
+ * show — Noctis doesn't filter internally).
+ */
+declare function CommandEmpty({
+  children,
+  ...props
+}: CommandEmptyProps): ReactElement;
+/** Props for {@link CommandLoading}. */
+interface CommandLoadingProps extends ComponentPropsWithoutRef<"div"> {}
+/** The centred async progress shell, shown before results settle (compose a spinner glyph + copy). */
+declare function CommandLoading({
+  children,
+  ...props
+}: CommandLoadingProps): ReactElement;
+/** Props for {@link CommandFooter}. */
+interface CommandFooterProps extends ComponentPropsWithoutRef<"div"> {}
+/**
+ * The footer region — a bare, end-aligned strip below the list. Unopinionated about its contents: drop
+ * in whatever status or hints you want (e.g. `Kbd` caps beside a label). The component ships no
+ * "hint" part, so you own the markup.
+ */
+declare function CommandFooter({
+  children,
+  ...props
+}: CommandFooterProps): ReactElement;
+/**
+ * An accessible command palette — a query field over a ranked, sectioned list of commands with full
+ * combobox/`aria-activedescendant` keyboard navigation and breadcrumb drill-in. Ships as a modal
+ * (`Command.Dialog` + a headless `Command.Trigger`) or inline (`Command.Root`); both share identical
+ * inner parts. Ranking is owned by Noctis — rank your commands with the exported `rankItems` /
+ * `useCommandRanking` and render the survivors as `Command.Item`s.
+ *
+ * @example
+ * ```tsx
+ * const ranked = rankItems(commands, query);
+ * <Command.Dialog open={open} onOpenChange={setOpen} value={query} onValueChange={setQuery}>
+ *   <Command.Header>
+ *     <SearchIcon />
+ *     <Command.Input placeholder="Type a command…" />
+ *   </Command.Header>
+ *   <Command.List>
+ *     <Command.Empty>No commands found.</Command.Empty>
+ *     {ranked.map((c) => (
+ *       <Command.Item key={c.value} value={c.value} onSelect={c.run}>
+ *         <Command.ItemLabel>{c.label}</Command.ItemLabel>
+ *       </Command.Item>
+ *     ))}
+ *   </Command.List>
+ * </Command.Dialog>
+ * ```
+ */
+declare const Command: {
+  /** The inline palette (embedded in normal flow). `Command.Root.props()` → its spreadable panel prop bag. */Root: typeof CommandRoot & {
+    props: typeof panelProps;
+  }; /** The modal palette (centred, focus-trapped). */
+  Dialog: typeof CommandDialog; /** A headless launcher that wires open + ARIA onto your own button. */
+  Trigger: typeof CommandTrigger; /** The input row. `Command.Header.props()` → its spreadable prop bag. */
+  Header: typeof CommandHeader & {
+    props: typeof headerProps;
+  }; /** The drill-in trail. `Command.Breadcrumb.props()` → its spreadable prop bag. */
+  Breadcrumb: typeof CommandBreadcrumb & {
+    props: typeof breadcrumbProps;
+  }; /** The query field. `Command.Input.props()` → its spreadable prop bag. */
+  Input: typeof CommandInput & {
+    props: typeof inputProps;
+  }; /** The trailing input affordance. `Command.InputAction.props()` → its spreadable prop bag. */
+  InputAction: typeof CommandInputAction & {
+    props: typeof inputActionProps;
+  }; /** The scrolling listbox. `Command.List.props()` → its spreadable prop bag. */
+  List: typeof CommandList & {
+    props: typeof listProps;
+  }; /** A labelled section. `Command.Group.props()` → its spreadable prop bag. */
+  Group: typeof CommandGroup & {
+    props: typeof groupProps;
+  }; /** A section heading. `Command.GroupLabel.props()` → its spreadable prop bag. */
+  GroupLabel: typeof CommandGroupLabel & {
+    props: typeof groupLabelProps;
+  }; /** One command row. `Command.Item.props({ highlighted, disabled })` → its spreadable prop bag for a foreign element. */
+  Item: typeof CommandItem & {
+    props: typeof itemProps;
+  }; /** The leading row glyph. `Command.ItemIcon.props()` → its spreadable prop bag. */
+  ItemIcon: typeof CommandItemIcon & {
+    props: typeof itemIconProps;
+  }; /** The row's text column. `Command.ItemLabel.props()` → its spreadable prop bag. */
+  ItemLabel: typeof CommandItemLabel & {
+    props: typeof itemLabelProps;
+  }; /** A section divider. `Command.Separator.props()` → its spreadable prop bag. */
+  Separator: typeof CommandSeparator & {
+    props: typeof separatorProps;
+  }; /** The no-results message. `Command.Empty.props()` → its spreadable prop bag. */
+  Empty: typeof CommandEmpty & {
+    props: typeof emptyProps;
+  }; /** The async progress shell. `Command.Loading.props()` → its spreadable prop bag. */
+  Loading: typeof CommandLoading & {
+    props: typeof loadingProps;
+  }; /** The footer region (compose your own status/hints). `Command.Footer.props()` → its spreadable prop bag. */
+  Footer: typeof CommandFooter & {
+    props: typeof footerProps;
+  };
+};
+/**
+ * Per-part prop types, mirroring Base UI's `Component.Part.Props` convention. Types-only — it emits no
+ * runtime code and merges with the `Command` object above, so `Command.Item` is the component value
+ * while `Command.Item.Props` is its prop type.
+ */
+declare namespace Command {
+  /** The spreadable data-attribute prop bag every `Command.*.props()` returns (D12). */
+  type PartProps = CommandPartProps;
+  namespace Root {
+    type Props = CommandRootProps;
+  }
+  namespace Dialog {
+    type Props = CommandDialogProps;
+  }
+  namespace Trigger {
+    type Props = CommandTriggerProps;
+  }
+  namespace Header {
+    type Props = CommandHeaderProps;
+  }
+  namespace Breadcrumb {
+    type Props = CommandBreadcrumbProps;
+  }
+  namespace Input {
+    type Props = CommandInputProps;
+  }
+  namespace InputAction {
+    type Props = CommandInputActionProps;
+  }
+  namespace List {
+    type Props = CommandListProps;
+  }
+  namespace Group {
+    type Props = CommandGroupProps;
+  }
+  namespace GroupLabel {
+    type Props = CommandGroupLabelProps;
+  }
+  namespace Item {
+    type Props = CommandItemProps;
+  }
+  namespace ItemIcon {
+    type Props = CommandItemIconProps;
+  }
+  namespace ItemLabel {
+    type Props = CommandItemLabelProps;
+  }
+  namespace Separator {
+    type Props = CommandSeparatorProps;
+  }
+  namespace Empty {
+    type Props = CommandEmptyProps;
+  }
+  namespace Loading {
+    type Props = CommandLoadingProps;
+  }
+  namespace Footer {
+    type Props = CommandFooterProps;
+  }
+}
+//#endregion
+export { Command };