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

package/dist/components/command/command.slots.js

@@ -0,0 +1,60 @@
+//#region src/components/command/command.slots.ts
+/**
+* The slot vocabulary every `Command` part stamps as its `data-slot`. The authored source the
+* orchestration file reads from, prefixed `noctis-command-{part}` (the precompiled `command.css` keys
+* every rule off these anchors); SLOTS.md generates from the token-graph declaration.
+*
+* `backdrop`, `header`, `breadcrumb`, `inputAction`, `listSizer`, `listView`, `group`, `itemIcon`,
+* `itemLabel`, `separator`, `loading`, and `footer` are styling-only anchors (the modal scrim, the input
+* row, the drill-in trail, the trailing input affordance, the list's measured content wrapper, the
+* per-page view that re-animates on drill-in, the section wrapper, the row's glyph and label columns,
+* the divider, and the footer region) — they carry no token mints, so they live here but not in the
+* token-graph anatomy.
+*
+* The component is deliberately unopinionated past the leading icon: a row pushes any trailing content
+* (a `Kbd` shortcut, a badge, a count) to its end via the label's `flex`, and the footer is a bare
+* region — neither bakes in a "shortcut"/"hint" concept, so the consumer composes those freely.
+*/
+const COMMAND_SLOTS = {
+	panel: "noctis-command",
+	backdrop: "noctis-command-backdrop",
+	header: "noctis-command-header",
+	breadcrumb: "noctis-command-breadcrumb",
+	input: "noctis-command-input",
+	inputAction: "noctis-command-input-action",
+	list: "noctis-command-list",
+	listSizer: "noctis-command-list-sizer",
+	listView: "noctis-command-list-view",
+	group: "noctis-command-group",
+	groupLabel: "noctis-command-group-label",
+	item: "noctis-command-item",
+	itemIcon: "noctis-command-item-icon",
+	itemLabel: "noctis-command-item-label",
+	separator: "noctis-command-separator",
+	empty: "noctis-command-empty",
+	loading: "noctis-command-loading",
+	footer: "noctis-command-footer"
+};
+/**
+* The `data-*` hooks `Command` stamps on its parts, for host-side styling and tests. Slot values mark
+* each rendered element; the state attributes are emitted by the palette's own combobox/listbox engine
+* (which drives the keyboard model — see `command-listbox`) and by the composed Dialog — pair a slot with
+* a state to target, say, the highlighted row or the modal panel while it transitions in.
+*/
+let CommandDataAttributes = /* @__PURE__ */ function(CommandDataAttributes) {
+	/** Marks each rendered part. */
+	CommandDataAttributes["slot"] = "data-slot";
+	/** Present on the panel in its modal form (the centred, fixed-height, scale-fading popup). */
+	CommandDataAttributes["modal"] = "data-modal";
+	/** Present on the command row the pointer or keyboard is currently over (the active descendant). */
+	CommandDataAttributes["highlighted"] = "data-highlighted";
+	/** Present on a disabled command row. */
+	CommandDataAttributes["disabled"] = "data-disabled";
+	/** Present on the modal panel/scrim for the first frame after mount — the transition's start state. */
+	CommandDataAttributes["startingStyle"] = "data-starting-style";
+	/** Present on the modal panel/scrim while it transitions out before unmounting. */
+	CommandDataAttributes["endingStyle"] = "data-ending-style";
+	return CommandDataAttributes;
+}({});
+//#endregion
+export { COMMAND_SLOTS, CommandDataAttributes };

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

@@ -0,0 +1,6 @@
+import { CommandPage } from "./command.context.js";
+import { Command } from "./command.js";
+import { CommandDataAttributes } from "./command.slots.js";
+import { commandScore } from "./command-score.js";
+import { RankOptions, RankableItem, rankItems } from "./command-rank.js";
+import { UseCommandRankingOptions, createRankingWorker, useCommandRanking } from "./use-command-ranking.js";

package/dist/components/command/use-command-ranking.d.ts

@@ -0,0 +1,37 @@
+import { RankOptions, RankableItem } from "./command-rank.js";
+
+//#region src/components/command/use-command-ranking.d.ts
+/**
+ * Options for {@link useCommandRanking} — the {@link RankOptions} plus the Worker-offload controls.
+ * A custom `score` function forces the synchronous path (functions can't cross the Worker boundary).
+ */
+interface UseCommandRankingOptions<T extends RankableItem> extends RankOptions<T> {
+  /**
+   * Offload ranking to a Web Worker once the candidate count reaches `workerThreshold`, keeping a
+   * large palette's keystrokes off the main thread. Falls back to synchronous ranking when a Worker
+   * can't be constructed (SSR, older bundlers, a custom `score`).
+   * @default true
+   */
+  worker?: boolean;
+  /**
+   * Candidate count at or above which the Worker is used (below it the synchronous path is faster
+   * than the round-trip).
+   * @default 250
+   */
+  workerThreshold?: number;
+}
+/**
+ * Build an inline-Blob ranking Worker, or `null` when the environment can't host one. Browser-only:
+ * jsdom has no `Worker`, so this is excluded from coverage (the hook's null-fallback path is tested).
+ */
+declare function createRankingWorker(): Worker | null;
+/**
+ * Rank `items` against `query`, offloading to a Web Worker for large candidate sets while staying
+ * synchronous (and SSR-safe) otherwise. The synchronous result is always returned immediately; a
+ * Worker result, when it arrives, supersedes it — so the palette never blocks on the round-trip.
+ *
+ * Pass `worker: false` (or a custom `score`) to force the synchronous path.
+ */
+declare function useCommandRanking<T extends RankableItem>(items: readonly T[], query: string, options?: UseCommandRankingOptions<T>): T[];
+//#endregion
+export { UseCommandRankingOptions, createRankingWorker, useCommandRanking };

package/dist/components/command/use-command-ranking.js

@@ -0,0 +1,127 @@
+"use client";
+import { commandScore } from "./command-score.js";
+import { rankItems, rankValues } from "./command-rank.js";
+import { useEffect, useMemo, useRef, useState } from "react";
+//#region src/components/command/use-command-ranking.ts
+/**
+* The Worker's message glue: take a ranking request, run the shared `rankValues`, post the ordered
+* values back. This is the *only* worker-specific code — the scoring and ranking it relies on are the
+* real, tested `commandScore` / `rankValues`, serialised verbatim alongside it (see `WORKER_SOURCE`),
+* so the Worker reuses the exact same implementation rather than a copy. Runs only inside a Worker
+* runtime, so it is excluded from coverage.
+*/
+/* v8 ignore start -- executes only inside a Worker (absent in jsdom); its `rankValues`/`commandScore` are covered */
+function workerGlue() {
+	const scope = self;
+	scope.onmessage = (event) => {
+		const { id, items, query, threshold } = event.data;
+		scope.postMessage({
+			id,
+			values: rankValues(items, query, threshold)
+		});
+	};
+}
+/* v8 ignore stop */
+const WORKER_SOURCE = `${commandScore};\n${rankValues};\n(${workerGlue})();`;
+/**
+* Build an inline-Blob ranking Worker, or `null` when the environment can't host one. Browser-only:
+* jsdom has no `Worker`, so this is excluded from coverage (the hook's null-fallback path is tested).
+*/
+/* v8 ignore start -- browser-only Worker construction (no `Worker` in jsdom) */
+function createRankingWorker() {
+	try {
+		if (typeof Worker === "undefined" || typeof Blob === "undefined" || typeof URL?.createObjectURL !== "function") return null;
+		const url = URL.createObjectURL(new Blob([WORKER_SOURCE], { type: "application/javascript" }));
+		const worker = new Worker(url);
+		URL.revokeObjectURL(url);
+		return worker;
+	} catch {
+		return null;
+	}
+}
+/* v8 ignore stop */
+/**
+* Rank `items` against `query`, offloading to a Web Worker for large candidate sets while staying
+* synchronous (and SSR-safe) otherwise. The synchronous result is always returned immediately; a
+* Worker result, when it arrives, supersedes it — so the palette never blocks on the round-trip.
+*
+* Pass `worker: false` (or a custom `score`) to force the synchronous path.
+*/
+function useCommandRanking(items, query, options = {}) {
+	const { worker = true, workerThreshold = 250, threshold = 0, score } = options;
+	const useWorker = worker && score === void 0 && items.length >= workerThreshold;
+	const sync = useMemo(() => rankItems(items, query, {
+		threshold,
+		score
+	}), [
+		items,
+		query,
+		threshold,
+		score
+	]);
+	const [workerOrder, setWorkerOrder] = useState(null);
+	const workerRef = useRef(null);
+	const jobRef = useRef(0);
+	useEffect(() => {
+		if (!useWorker) {
+			setWorkerOrder(null);
+			return;
+		}
+		/* v8 ignore start -- the Worker path: jsdom has no Worker, so createRankingWorker is null and
+		the message wiring below never runs (the hook's sync fallback is what gets tested) */
+		const w = workerRef.current ??= createRankingWorker();
+		if (!w) {
+			setWorkerOrder(null);
+			return;
+		}
+		const id = ++jobRef.current;
+		setWorkerOrder(null);
+		const onMessage = (event) => {
+			const data = event.data;
+			if (data.id === id) setWorkerOrder(data.values);
+		};
+		w.addEventListener("message", onMessage);
+		w.postMessage({
+			id,
+			query,
+			threshold,
+			items: items.map((item) => ({
+				value: item.value,
+				label: item.label,
+				keywords: item.keywords,
+				boost: item.boost
+			}))
+		});
+		return () => w.removeEventListener("message", onMessage);
+		/* v8 ignore stop */
+	}, [
+		useWorker,
+		items,
+		query,
+		threshold
+	]);
+	useEffect(() => () => {
+		/* v8 ignore next -- workerRef is only ever set on the live-Worker path */
+		workerRef.current?.terminate();
+	}, []);
+	return useMemo(() => {
+		if (!useWorker) return sync;
+		/* v8 ignore start -- reached only when a Worker has replied (never in jsdom) */
+		if (workerOrder === null) return sync;
+		const byValue = new Map(items.map((item) => [item.value, item]));
+		const ordered = [];
+		for (const value of workerOrder) {
+			const item = byValue.get(value);
+			if (item) ordered.push(item);
+		}
+		return ordered;
+		/* v8 ignore stop */
+	}, [
+		useWorker,
+		workerOrder,
+		sync,
+		items
+	]);
+}
+//#endregion
+export { createRankingWorker, useCommandRanking };

package/dist/components/pagination/index.d.ts

@@ -0,0 +1,3 @@
+import { PaginationLabels, PaginationSize } from "./pagination.types.js";
+import { Pagination } from "./pagination.js";
+import { PaginationDataAttributes } from "./pagination.slots.js";

package/dist/components/pagination/pagination.context.js

@@ -0,0 +1,16 @@
+"use client";
+import { createContext, use } from "react";
+//#region src/components/pagination/pagination.context.ts
+const PaginationContext = createContext(null);
+const PaginationProvider = PaginationContext.Provider;
+/**
+* Read the enclosing `Pagination.Root` state. Every compound part is meaningless on its own (it needs
+* the page model and shared labels), so this throws a part-named error when used outside the root.
+*/
+function usePaginationContext(part) {
+	const context = use(PaginationContext);
+	if (!context) throw new Error(`Pagination.${part} must be rendered inside a <Pagination.Root>.`);
+	return context;
+}
+//#endregion
+export { PaginationProvider, usePaginationContext };

package/dist/components/pagination/pagination.d.ts

@@ -0,0 +1,217 @@
+import { Button } from "../button/button.js";
+import { PaginationLabels, PaginationSize } from "./pagination.types.js";
+import { PaginationPartProps, PaginationRootPropsArgs, controlsProps, infoProps, pageProps, pageSizeLabelProps, pageSizeProps, rootProps, separatorProps } from "./pagination.props.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
+
+//#region src/components/pagination/pagination.d.ts
+/**
+ * Page navigation: a row of nav controls (a welded `ButtonGroup` of First/Previous/Next/Last buttons),
+ * an optional editable page field, a "Showing X–Y of Z" info line, and a page-size picker — composed
+ * from the shipped `Button`, `ButtonGroup`, `Input`, and `Select`. `Pagination.Root` is controlled:
+ * pass `page` + `onPageChange`, and `total` + `perPage` (so the info line and the last-page bound can
+ * be computed) or an explicit `pageCount`. Every part reads the shared model through context, so the
+ * bounds-disabling and clamping are handled for you.
+ *
+ * @see {@link Pagination.Root.Props}
+ */
+declare function PaginationRoot({
+  page,
+  onPageChange,
+  total,
+  perPage,
+  pageCount: pageCountProp,
+  size,
+  labels: labelsProp,
+  className,
+  children,
+  ...props
+}: Pagination.Root.Props): ReactElement;
+/** The render-prop state `Pagination.Info` exposes for custom info text. */
+interface PaginationInfoState {
+  /** Current page, 1-indexed. */
+  page: number;
+  /** The last reachable page. */
+  pageCount: number;
+  /** Items per page, when known. */
+  perPage?: number;
+  /** Total item count, when known. */
+  total?: number;
+  /** First item index on the current page (1-indexed), or 0 when the set is empty. */
+  from: number;
+  /** Last item index on the current page. */
+  to: number;
+}
+/**
+ * The "Showing X–Y of Z" status line, announced politely as the page changes. Renders nothing unless
+ * `total` and `perPage` are known on the root — or pass a render function as children for custom text
+ * (e.g. "Page X of Y"). Quieter than the controls by design.
+ */
+declare function PaginationInfo({
+  children,
+  className,
+  ...props
+}: Pagination.Info.Props): ReactElement | null;
+/**
+ * The page-size cluster — a layout wrapper that holds a `Pagination.PageSizeLabel` and a
+ * `Pagination.PageSizeSelect` side by side. Compose them inside; the label and select are separate so
+ * the consumer can reorder, restyle, translate, or drop either independently.
+ */
+declare function PaginationPageSize({
+  className,
+  children,
+  ...props
+}: Pagination.PageSize.Props): ReactElement;
+/**
+ * The label beside the page-size select (visible "Per page" micro-copy). Defaults to the localized
+ * label; pass children to override the text. Purely visual — the select carries its own accessible name.
+ */
+declare function PaginationPageSizeLabel({
+  className,
+  children,
+  ...props
+}: Pagination.PageSizeLabel.Props): ReactElement;
+/**
+ * The page-size `Select` of "items per page" choices. Controlled via `value` + `onValueChange`;
+ * resetting the page to 1 on change is the consumer's call (do it in the handler).
+ */
+declare function PaginationPageSizeSelect({
+  value,
+  onValueChange,
+  options
+}: Pagination.PageSizeSelect.Props): ReactElement;
+/**
+ * The navigation landmark wrapping a welded `ButtonGroup` of nav buttons. Compose `Pagination.First`,
+ * `Pagination.Previous`, `Pagination.Next`, `Pagination.Last`, and/or `Pagination.Page` inside — use
+ * only Previous/Next for a simple control, or add First/Last/Page for the full set.
+ */
+declare function PaginationControls({
+  className,
+  children,
+  ...props
+}: Pagination.Controls.Props): ReactElement;
+/** Jump to the first page. Disabled on page 1. */
+declare function PaginationFirst(props: Pagination.NavButton.Props): ReactElement;
+/** Step to the previous page. Disabled on page 1. */
+declare function PaginationPrevious(props: Pagination.NavButton.Props): ReactElement;
+/** Step to the next page. Disabled on the last page. */
+declare function PaginationNext(props: Pagination.NavButton.Props): ReactElement;
+/** Jump to the last page. Disabled on the last page. */
+declare function PaginationLast(props: Pagination.NavButton.Props): ReactElement;
+/**
+ * An editable page-number field (the "full" affordance). Type a page and press Enter or blur to commit;
+ * the value is clamped to the valid range and snaps back if cleared. Sits beside the nav buttons.
+ */
+declare function PaginationPage({
+  className,
+  ...props
+}: Pagination.Page.Props): ReactElement;
+/** A vertical hairline between pagination clusters. Purely decorative — a quiet visual rule, hidden
+ * from assistive tech (the clusters are already distinct landmarks/labels). */
+declare function PaginationSeparator({
+  className,
+  ...props
+}: Pagination.Separator.Props): ReactElement;
+/**
+ * Page navigation controls. `Pagination.Root` owns the controlled page model and shares it with the
+ * parts: `Pagination.Controls` (the welded nav `ButtonGroup`) hosting `Pagination.First` / `Previous` /
+ * `Next` / `Last` and the editable `Pagination.Page`, plus the `Pagination.Info` status line, the
+ * `Pagination.PageSize` picker, and the `Pagination.Separator` divider.
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop types are exposed through
+ * the matching `Pagination` namespace — e.g. `Pagination.Root.Props`.
+ */
+declare const Pagination: {
+  /** Owns the controlled page model + shared context. `Pagination.Root.props({ size })` → its prop bag. */Root: typeof PaginationRoot & {
+    props: typeof rootProps;
+  }; /** The "Showing X–Y of Z" status line. `Pagination.Info.props()` → its prop bag. */
+  Info: typeof PaginationInfo & {
+    props: typeof infoProps;
+  }; /** The page-size cluster (compose `PageSizeLabel` + `PageSizeSelect`). `Pagination.PageSize.props()` → its prop bag. */
+  PageSize: typeof PaginationPageSize & {
+    props: typeof pageSizeProps;
+  }; /** The page-size label. `Pagination.PageSizeLabel.props()` → its prop bag. */
+  PageSizeLabel: typeof PaginationPageSizeLabel & {
+    props: typeof pageSizeLabelProps;
+  }; /** The page-size select control. */
+  PageSizeSelect: typeof PaginationPageSizeSelect; /** The nav landmark + welded `ButtonGroup`. `Pagination.Controls.props()` → its prop bag. */
+  Controls: typeof PaginationControls & {
+    props: typeof controlsProps;
+  }; /** First-page button. */
+  First: typeof PaginationFirst; /** Previous-page button. */
+  Previous: typeof PaginationPrevious; /** Next-page button. */
+  Next: typeof PaginationNext; /** Last-page button. */
+  Last: typeof PaginationLast; /** The editable page-number field. `Pagination.Page.props()` → its prop bag. */
+  Page: typeof PaginationPage & {
+    props: typeof pageProps;
+  }; /** A vertical divider between clusters. `Pagination.Separator.props()` → its prop bag. */
+  Separator: typeof PaginationSeparator & {
+    props: typeof separatorProps;
+  };
+};
+/**
+ * Per-part prop types. Types-only — it emits no runtime code and merges with the `Pagination` object
+ * above, so `Pagination.Root` is the component value while `Pagination.Root.Props` is its prop type.
+ */
+declare namespace Pagination {
+  /** Control scale — `sm` | `md`. */
+  type Size = PaginationSize;
+  /** The accessible-name + micro-copy overrides. */
+  type Labels = PaginationLabels;
+  /** The spreadable data-attribute prop bag every owned `Pagination.*.props()` returns (D12). */
+  type PartProps = PaginationPartProps;
+  namespace Root {
+    type Props = Omit<ComponentProps<"div">, "onChange"> & {
+      /**
+       * Current page, 1-indexed.
+       * @default 1
+       */
+      page?: number; /** Called with the next page (already clamped to `[1, pageCount]`) when the user navigates. */
+      onPageChange?: (page: number) => void; /** Total item count across all pages — drives the info range and the last-page bound. */
+      total?: number; /** Items shown per page — drives the info range and the last-page bound. */
+      perPage?: number; /** The last reachable page, when you'd rather supply it than derive it from `total`/`perPage`. */
+      pageCount?: number;
+      /**
+       * Control scale, fed to the hosted Button/Input/Select.
+       * @default "md"
+       */
+      size?: PaginationSize; /** Per-instance overrides for the accessible names + micro-copy. */
+      labels?: PaginationLabels;
+    };
+    /** Argument to the `Pagination.Root.props(...)` escape-hatch helper. */
+    type PropsArgs = PaginationRootPropsArgs;
+  }
+  namespace Info {
+    type Props = Omit<ComponentProps<"div">, "children"> & {
+      /** Render function for custom info text; omit for the default "Showing X–Y of Z". */children?: (state: PaginationInfoState) => ReactNode;
+    };
+  }
+  namespace PageSize {
+    /** The cluster wrapper — compose `Pagination.PageSizeLabel` and `Pagination.PageSizeSelect` inside. */
+    type Props = ComponentProps<"div">;
+  }
+  namespace PageSizeLabel {
+    /** The visible "Per page" label; children override the default localized text. */
+    type Props = ComponentProps<"span">;
+  }
+  namespace PageSizeSelect {
+    type Props = {
+      /** The current page size. */value: number; /** Called with the chosen page size. */
+      onValueChange: (size: number) => void; /** The available page-size choices. @default [10, 25, 50, 100] */
+      options?: readonly number[];
+    };
+  }
+  namespace Controls {
+    type Props = ComponentProps<"nav">;
+  }
+  namespace NavButton {
+    type Props = Omit<Button.Props, "iconOnly" | "startIcon" | "endIcon" | "onClick" | "children">;
+  }
+  namespace Page {
+    type Props = ComponentProps<"div">;
+  }
+  namespace Separator {
+    type Props = ComponentProps<"div">;
+  }
+}
+//#endregion
+export { Pagination };