@stridge/noctis 1.0.0-beta.5 → 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/search-dialog/parts/root.js

@@ -1,8 +1,8 @@
 "use client";
 import { VisuallyHidden } from "../../../core/visually-hidden/visually-hidden.js";
+import { Dialog } from "../../dialog/dialog.js";
 import { SearchDialogProvider } from "../search-dialog.context.js";
 import { SEARCH_DIALOG_SLOTS } from "../search-dialog.slots.js";
-import { Dialog } from "../../dialog/dialog.js";
 import { useEffect, useMemo, useRef, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/search-dialog/parts/root.tsx

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

@@ -0,0 +1,3 @@
+import { SkeletonVariant } from "./skeleton.types.js";
+import { Skeleton } from "./skeleton.js";
+import { SkeletonDataAttributes } from "./skeleton.slots.js";

package/dist/components/skeleton/skeleton.context.js

@@ -0,0 +1,12 @@
+"use client";
+import { createContext, use } from "react";
+//#region src/components/skeleton/skeleton.context.ts
+const SkeletonContext = createContext({ variant: "shimmer" });
+/** Provider used by `Skeleton.Root` to share its `variant` with descendant shapes. */
+const SkeletonProvider = SkeletonContext.Provider;
+/** Reads the active `Skeleton` context, falling back to the shimmer default for a standalone shape. */
+function useSkeletonContext() {
+	return use(SkeletonContext);
+}
+//#endregion
+export { SkeletonProvider, useSkeletonContext };

package/dist/components/skeleton/skeleton.d.ts

@@ -0,0 +1,157 @@
+import { SkeletonVariant } from "./skeleton.types.js";
+import { SkeletonLayoutPropsArgs, SkeletonPartProps, SkeletonShapePropsArgs, boxProps, circleProps, lineProps, rootProps, textProps } from "./skeleton.props.js";
+import { ComponentPropsWithRef, ReactElement } from "react";
+
+//#region src/components/skeleton/skeleton.d.ts
+/**
+ * The accessible loading group — a `role="status"` live region that announces "Loading" to assistive
+ * tech while its placeholder shapes show. Lays its children out as a vertical stack by default (restyle
+ * via `className`/`style` for any other arrangement) and shares its `variant` down to every child shape,
+ * so you set the animation once on the group. Swap the announced text with `label`, or unmount the whole
+ * group once the real content is ready.
+ *
+ * The placeholder shapes (`Skeleton.Box`/`Circle`/`Text`) are decorative (`aria-hidden`) — this region
+ * is the single thing screen readers hear, so the loading state is conveyed once, not once per shape.
+ *
+ * @see {@link Skeleton.Root.Props}
+ */
+declare function SkeletonRoot({
+  variant,
+  label,
+  className,
+  children,
+  ...props
+}: Skeleton.Root.Props): ReactElement;
+/**
+ * A rectangular placeholder — the general-purpose block for an image, a card, a thumbnail, or any
+ * fixed-shape region. Fills its inline space and defaults to a short height; set `style`/`className`
+ * dimensions to match the content it stands in for. Decorative (`aria-hidden`); the animation comes from
+ * its own `variant` or the surrounding `Skeleton.Root`.
+ */
+declare function SkeletonBox({
+  variant,
+  className,
+  ...props
+}: Skeleton.Box.Props): ReactElement;
+/**
+ * A circular placeholder — for an avatar, a status dot, or an icon. Defaults to a `2.5rem` disc; size it
+ * with `style`/`className` to match the element it stands in for. Decorative (`aria-hidden`).
+ */
+declare function SkeletonCircle({
+  variant,
+  className,
+  ...props
+}: Skeleton.Circle.Props): ReactElement;
+/**
+ * A multi-line text placeholder — a stack of line bars standing in for a paragraph. Renders `lines` bars
+ * (default 3); the last bar is drawn shorter so the block reads as ragged prose, not a solid box. The
+ * line height tracks the surrounding font size. Decorative (`aria-hidden`); compose `Skeleton.Line`
+ * directly for full control over individual line widths.
+ */
+declare function SkeletonText({
+  lines,
+  variant,
+  className,
+  ...props
+}: Skeleton.Text.Props): ReactElement;
+/**
+ * A single text-line placeholder bar. Use it directly inside a `Skeleton.Text` (or any layout) when you
+ * want to set per-line widths via `style`/`className` instead of the uniform `Skeleton.Text` block.
+ * Decorative (`aria-hidden`).
+ */
+declare function SkeletonLine({
+  variant,
+  className,
+  ...props
+}: Skeleton.Line.Props): ReactElement;
+/**
+ * A loading placeholder that mirrors the shape of the content it stands in for. `Skeleton.Root` is the
+ * accessible group (a `role="status"` region) that announces the load and shares the animation `variant`
+ * to its shapes; compose `Skeleton.Box` (a rectangle), `Skeleton.Circle` (an avatar/icon disc), and
+ * `Skeleton.Text` (a paragraph of `Skeleton.Line`s) inside it. Each shape also works standalone.
+ *
+ * The default `shimmer` variant sweeps a light band across each placeholder; `pulse` fades it and `none`
+ * holds it static. Every variant respects `prefers-reduced-motion`, and the placeholder fill is the
+ * surface-adaptive `well` overlay so it stays visible on any surface. Styling is precompiled CSS keyed
+ * off the `data-slot` anchor (`skeleton.css`); the shapes are accent-independent and purely presentational.
+ *
+ * The runtime compound is a plain object (kept tree-shakeable); per-part prop types are exposed through
+ * the matching `Skeleton` namespace — e.g. `Skeleton.Root.Props`.
+ */
+declare const Skeleton: {
+  /** The accessible loading group. `Skeleton.Root.props({ variant })` → its prop bag. */Root: typeof SkeletonRoot & {
+    props: typeof rootProps;
+  }; /** A rectangular placeholder. `Skeleton.Box.props({ variant })` → its spreadable prop bag. */
+  Box: typeof SkeletonBox & {
+    props: typeof boxProps;
+  }; /** A circular placeholder. `Skeleton.Circle.props({ variant })` → its spreadable prop bag. */
+  Circle: typeof SkeletonCircle & {
+    props: typeof circleProps;
+  }; /** A multi-line text placeholder. `Skeleton.Text.props()` → its spreadable prop bag. */
+  Text: typeof SkeletonText & {
+    props: typeof textProps;
+  }; /** A single text-line placeholder. `Skeleton.Line.props({ variant })` → its spreadable prop bag. */
+  Line: typeof SkeletonLine & {
+    props: typeof lineProps;
+  };
+};
+/**
+ * Per-part prop types. Types-only — it emits no runtime code and merges with the `Skeleton` object
+ * above, so `Skeleton.Root` is the component value while `Skeleton.Root.Props` is its prop type.
+ */
+declare namespace Skeleton {
+  /** Animation style — `shimmer` | `pulse` | `none`. */
+  type Variant = SkeletonVariant;
+  /** The spreadable data-attribute prop bag every `Skeleton.*.props()` returns (D12). */
+  type PartProps = SkeletonPartProps;
+  namespace Root {
+    type Props = ComponentPropsWithRef<"div"> & {
+      /**
+       * Animation style shared down to every child shape.
+       * @default "shimmer"
+       */
+      variant?: SkeletonVariant;
+      /**
+       * The accessible name announced for the loading region; overrides the localized "Loading".
+       */
+      label?: string;
+    };
+    /** Argument to the `Skeleton.Root.props(...)` escape-hatch helper. */
+    type PropsArgs = SkeletonShapePropsArgs;
+  }
+  namespace Box {
+    type Props = ComponentPropsWithRef<"div"> & {
+      /** Animation style; inherits from the surrounding `Skeleton.Root` when unset. @default "shimmer" */variant?: SkeletonVariant;
+    };
+    /** Argument to the `Skeleton.Box.props(...)` escape-hatch helper. */
+    type PropsArgs = SkeletonShapePropsArgs;
+  }
+  namespace Circle {
+    type Props = ComponentPropsWithRef<"div"> & {
+      /** Animation style; inherits from the surrounding `Skeleton.Root` when unset. @default "shimmer" */variant?: SkeletonVariant;
+    };
+    /** Argument to the `Skeleton.Circle.props(...)` escape-hatch helper. */
+    type PropsArgs = SkeletonShapePropsArgs;
+  }
+  namespace Text {
+    type Props = ComponentPropsWithRef<"div"> & {
+      /**
+       * How many line bars to render; the last bar is drawn shorter.
+       * @default 3
+       */
+      lines?: number; /** Animation style; inherits from the surrounding `Skeleton.Root` when unset. @default "shimmer" */
+      variant?: SkeletonVariant;
+    };
+    /** Argument to the `Skeleton.Text.props(...)` escape-hatch helper. */
+    type PropsArgs = SkeletonLayoutPropsArgs;
+  }
+  namespace Line {
+    type Props = ComponentPropsWithRef<"div"> & {
+      /** Animation style; inherits from the surrounding `Skeleton.Root` when unset. @default "shimmer" */variant?: SkeletonVariant;
+    };
+    /** Argument to the `Skeleton.Line.props(...)` escape-hatch helper. */
+    type PropsArgs = SkeletonShapePropsArgs;
+  }
+}
+//#endregion
+export { Skeleton };

package/dist/components/skeleton/skeleton.js

@@ -0,0 +1,130 @@
+"use client";
+import { useInjectedLabels } from "../../core/use-injected-labels.js";
+import { VisuallyHidden } from "../../core/visually-hidden/visually-hidden.js";
+import { SkeletonProvider, useSkeletonContext } from "./skeleton.context.js";
+import { boxProps, circleProps, lineProps, rootProps, textProps } from "./skeleton.props.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/skeleton/skeleton.tsx
+/** English fallbacks and catalog keys for the loading region's accessible name (resolved per locale). */
+const DEFAULT_LABELS = { loading: "Loading" };
+const LABEL_KEYS = { loading: "skeleton.loading" };
+/**
+* The accessible loading group — a `role="status"` live region that announces "Loading" to assistive
+* tech while its placeholder shapes show. Lays its children out as a vertical stack by default (restyle
+* via `className`/`style` for any other arrangement) and shares its `variant` down to every child shape,
+* so you set the animation once on the group. Swap the announced text with `label`, or unmount the whole
+* group once the real content is ready.
+*
+* The placeholder shapes (`Skeleton.Box`/`Circle`/`Text`) are decorative (`aria-hidden`) — this region
+* is the single thing screen readers hear, so the loading state is conveyed once, not once per shape.
+*
+* @see {@link Skeleton.Root.Props}
+*/
+function SkeletonRoot({ variant = "shimmer", label, className, children, ...props }) {
+	const labels = useInjectedLabels(DEFAULT_LABELS, LABEL_KEYS, label === void 0 ? void 0 : { loading: label });
+	return /* @__PURE__ */ jsx("div", {
+		...rootProps({
+			variant,
+			className
+		}),
+		role: "status",
+		"aria-busy": "true",
+		...props,
+		children: /* @__PURE__ */ jsxs(SkeletonProvider, {
+			value: { variant },
+			children: [/* @__PURE__ */ jsx(VisuallyHidden, { children: labels.loading }), children]
+		})
+	});
+}
+/**
+* A rectangular placeholder — the general-purpose block for an image, a card, a thumbnail, or any
+* fixed-shape region. Fills its inline space and defaults to a short height; set `style`/`className`
+* dimensions to match the content it stands in for. Decorative (`aria-hidden`); the animation comes from
+* its own `variant` or the surrounding `Skeleton.Root`.
+*/
+function SkeletonBox({ variant, className, ...props }) {
+	const { variant: inherited } = useSkeletonContext();
+	return /* @__PURE__ */ jsx("div", {
+		...boxProps({
+			variant: variant ?? inherited,
+			className
+		}),
+		"aria-hidden": "true",
+		...props
+	});
+}
+/**
+* A circular placeholder — for an avatar, a status dot, or an icon. Defaults to a `2.5rem` disc; size it
+* with `style`/`className` to match the element it stands in for. Decorative (`aria-hidden`).
+*/
+function SkeletonCircle({ variant, className, ...props }) {
+	const { variant: inherited } = useSkeletonContext();
+	return /* @__PURE__ */ jsx("div", {
+		...circleProps({
+			variant: variant ?? inherited,
+			className
+		}),
+		"aria-hidden": "true",
+		...props
+	});
+}
+/**
+* A multi-line text placeholder — a stack of line bars standing in for a paragraph. Renders `lines` bars
+* (default 3); the last bar is drawn shorter so the block reads as ragged prose, not a solid box. The
+* line height tracks the surrounding font size. Decorative (`aria-hidden`); compose `Skeleton.Line`
+* directly for full control over individual line widths.
+*/
+function SkeletonText({ lines = 3, variant, className, ...props }) {
+	const { variant: inherited } = useSkeletonContext();
+	const resolved = variant ?? inherited;
+	return /* @__PURE__ */ jsx("div", {
+		...textProps({ className }),
+		"aria-hidden": "true",
+		...props,
+		children: Array.from({ length: Math.max(0, lines) }, (_, i) => /* @__PURE__ */ jsx(SkeletonLine, { variant: resolved }, i))
+	});
+}
+/**
+* A single text-line placeholder bar. Use it directly inside a `Skeleton.Text` (or any layout) when you
+* want to set per-line widths via `style`/`className` instead of the uniform `Skeleton.Text` block.
+* Decorative (`aria-hidden`).
+*/
+function SkeletonLine({ variant, className, ...props }) {
+	const { variant: inherited } = useSkeletonContext();
+	return /* @__PURE__ */ jsx("div", {
+		...lineProps({
+			variant: variant ?? inherited,
+			className
+		}),
+		"aria-hidden": "true",
+		...props
+	});
+}
+/**
+* A loading placeholder that mirrors the shape of the content it stands in for. `Skeleton.Root` is the
+* accessible group (a `role="status"` region) that announces the load and shares the animation `variant`
+* to its shapes; compose `Skeleton.Box` (a rectangle), `Skeleton.Circle` (an avatar/icon disc), and
+* `Skeleton.Text` (a paragraph of `Skeleton.Line`s) inside it. Each shape also works standalone.
+*
+* The default `shimmer` variant sweeps a light band across each placeholder; `pulse` fades it and `none`
+* holds it static. Every variant respects `prefers-reduced-motion`, and the placeholder fill is the
+* surface-adaptive `well` overlay so it stays visible on any surface. Styling is precompiled CSS keyed
+* off the `data-slot` anchor (`skeleton.css`); the shapes are accent-independent and purely presentational.
+*
+* The runtime compound is a plain object (kept tree-shakeable); per-part prop types are exposed through
+* the matching `Skeleton` namespace — e.g. `Skeleton.Root.Props`.
+*/
+const Skeleton = {
+	/** The accessible loading group. `Skeleton.Root.props({ variant })` → its prop bag. */
+	Root: Object.assign(SkeletonRoot, { props: rootProps }),
+	/** A rectangular placeholder. `Skeleton.Box.props({ variant })` → its spreadable prop bag. */
+	Box: Object.assign(SkeletonBox, { props: boxProps }),
+	/** A circular placeholder. `Skeleton.Circle.props({ variant })` → its spreadable prop bag. */
+	Circle: Object.assign(SkeletonCircle, { props: circleProps }),
+	/** A multi-line text placeholder. `Skeleton.Text.props()` → its spreadable prop bag. */
+	Text: Object.assign(SkeletonText, { props: textProps }),
+	/** A single text-line placeholder. `Skeleton.Line.props({ variant })` → its spreadable prop bag. */
+	Line: Object.assign(SkeletonLine, { props: lineProps })
+};
+//#endregion
+export { Skeleton };

package/dist/components/skeleton/skeleton.props.d.ts

@@ -0,0 +1,47 @@
+import { SkeletonVariant } from "./skeleton.types.js";
+
+//#region src/components/skeleton/skeleton.props.d.ts
+/** A spreadable data-attribute prop bag — the shape every `Skeleton.*.props()` returns. */
+type SkeletonPartProps = {
+  /** The slot value the matching `skeleton.css` rules anchor on. */"data-slot": string; /** Forwarded verbatim — styling is attribute-driven, so this is an optional consumer passthrough. */
+  className?: string; /** A data-attribute present (string) or absent (`undefined`); never `false`. */
+  [attr: `data-${string}`]: string | undefined;
+};
+/** Common shape: every part's `.props()` accepts an optional `className` passthrough. */
+interface BasePropsArgs {
+  /** Forwarded verbatim onto the returned prop bag. */
+  className?: string;
+}
+/** Argument to a shape's `.props(...)` — its animation variant plus the optional `className`. */
+interface SkeletonShapePropsArgs extends BasePropsArgs {
+  /** Animation style — `shimmer` (default) | `pulse` | `none`. @default "shimmer" */
+  variant?: SkeletonVariant;
+}
+/** Argument to a layout part's `.props(...)` — no animation of its own; the lines inside animate. */
+type SkeletonLayoutPropsArgs = BasePropsArgs;
+/** Root prop bag: the status-region slot plus the `data-variant` it shares down to its shapes. */
+declare function rootProps({
+  variant,
+  className
+}?: SkeletonShapePropsArgs): SkeletonPartProps;
+/** Box prop bag: the rectangle slot plus its `data-variant`. */
+declare function boxProps({
+  variant,
+  className
+}?: SkeletonShapePropsArgs): SkeletonPartProps;
+/** Circle prop bag: the disc slot plus its `data-variant`. */
+declare function circleProps({
+  variant,
+  className
+}?: SkeletonShapePropsArgs): SkeletonPartProps;
+/** Text prop bag: the lines wrapper slot (a layout stack — its `Skeleton.Line`s carry the animation). */
+declare function textProps({
+  className
+}?: SkeletonLayoutPropsArgs): SkeletonPartProps;
+/** Line prop bag: a single text-line slot plus its `data-variant`. */
+declare function lineProps({
+  variant,
+  className
+}?: SkeletonShapePropsArgs): SkeletonPartProps;
+//#endregion
+export { SkeletonLayoutPropsArgs, SkeletonPartProps, SkeletonShapePropsArgs, boxProps, circleProps, lineProps, rootProps, textProps };

package/dist/components/skeleton/skeleton.props.js

@@ -0,0 +1,57 @@
+import { SKELETON_SLOTS } from "./skeleton.slots.js";
+//#region src/components/skeleton/skeleton.props.ts
+/**
+* The D12 unified variant contract for Skeleton — the data-attribute-native styling helpers.
+*
+* Each part exposes a `props(...)` builder returning a **spreadable props object** of the form
+* `{ "data-slot": "noctis-skeleton-<part>", ...dataAttrs }`. Under the single-`data-slot` anchor model
+* the `data-slot` is the only styling hook needed — `skeleton.css` keys every rule off it plus the
+* `data-variant` animation recipe — so spreading a part's `props()` onto a *foreign* element styles it
+* as that placeholder:
+*
+*     <div {...Skeleton.Box.props({ variant: "pulse" })} style={{ height: 48 }} />
+*     // → <div data-slot="noctis-skeleton-box" data-variant="pulse" aria-hidden="true">
+*
+* The escape hatch carries no className (styling is attribute-driven); an optional `className`
+* passthrough is accepted and forwarded verbatim. The same variant→data-attribute→values mapping is
+* emitted as data from the token graph (`generated/declarations.json` → `variantSchema`) so non-React /
+* agent consumers can hand-write the markup from the docs.
+*/
+const withClassName = (bag, className) => className === void 0 ? bag : {
+	...bag,
+	className
+};
+/** Root prop bag: the status-region slot plus the `data-variant` it shares down to its shapes. */
+function rootProps({ variant = "shimmer", className } = {}) {
+	return withClassName({
+		"data-slot": SKELETON_SLOTS.root,
+		"data-variant": variant
+	}, className);
+}
+/** Box prop bag: the rectangle slot plus its `data-variant`. */
+function boxProps({ variant = "shimmer", className } = {}) {
+	return withClassName({
+		"data-slot": SKELETON_SLOTS.box,
+		"data-variant": variant
+	}, className);
+}
+/** Circle prop bag: the disc slot plus its `data-variant`. */
+function circleProps({ variant = "shimmer", className } = {}) {
+	return withClassName({
+		"data-slot": SKELETON_SLOTS.circle,
+		"data-variant": variant
+	}, className);
+}
+/** Text prop bag: the lines wrapper slot (a layout stack — its `Skeleton.Line`s carry the animation). */
+function textProps({ className } = {}) {
+	return withClassName({ "data-slot": SKELETON_SLOTS.text }, className);
+}
+/** Line prop bag: a single text-line slot plus its `data-variant`. */
+function lineProps({ variant = "shimmer", className } = {}) {
+	return withClassName({
+		"data-slot": SKELETON_SLOTS.line,
+		"data-variant": variant
+	}, className);
+}
+//#endregion
+export { boxProps, circleProps, lineProps, rootProps, textProps };