@primitiv-ui/core 0.0.0-stage → 0.1.43

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Revill
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @primitiv-ui/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The framework-free behaviour core shared by every Primitiv surface. Pure
+TypeScript functions with **no DOM, no framework and no dependencies**: keyboard
+maps, roving-focus targets, id derivation and, as components move over, each
+component's keyboard and state policy.
+
+You do not normally install this package yourself. It arrives as a dependency
+of the surface you chose: [`@primitiv-ui/react`](../react/README.md) today, and
+`@primitiv-ui/web` (standard custom elements) as it lands. Both surfaces import
+the same functions, so they cannot disagree about how a component behaves. See
+[RFC 0033](../../docs/rfcs/0033-web-components.md) for the design.
+
+## Exports
+
+| Export | What it does |
+| --- | --- |
+| `getKeyToActionMap(options)` | Builds the key → roving action map (`"next"`, `"prev"`, `"first"`, `"last"`, `"activate"`) for an orientation, reading direction, Home/End and Enter/Space. |
+| `RovingKeyAction` | The action vocabulary those maps return. |
+| `resolveRovingTarget({ action, navigable, currentKey })` | Resolves which item a roving action lands on (wrapping, Home/End, Enter/Space), as `{ target }` or `null`. |
+| `deriveId(rootId, suffix, value)` | Builds the paired ids (`aria-controls`, `aria-labelledby`) a compound component wires between its parts. |
+| `tabsKeydown(state, focused, key)` | Tabs' keyboard contract: which tab to focus and which, if any, to activate. |
+| `tabsClick(state, value)` | The tab a click activates, or `null` when it is disabled or already active. |
+| `tabsTabStop(state)` | The tab that takes part in the page's Tab order. |
+| `TabsState`, `TabsKeyOutcome`, `TabsOrientation`, `TabsReadingDirection`, `TabsActivationMode` | The plain data those functions read and return. |
+
+## Rules for this package
+
+- **No DOM.** `tsconfig.json` leaves `DOM` out of `lib`, so a DOM type in a
+  signature is a compile error.
+- **100% coverage and 100% mutation score**, both gated: `pnpm qa:units` and
+  `pnpm mutate`.
+- **Versioned in lockstep** with every other Primitiv package
+  (`scripts/bump-version.mjs`).

package/dist/ids/deriveId.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Builds a deterministic sub-id from a stable root id (typically the
+ * value returned by React's `useId()`), a fixed role suffix, and a
+ * per-item value. Used to wire `aria-controls`, `aria-labelledby`, and
+ * matching DOM `id` attributes between paired sub-components such as
+ * Tabs.Trigger ↔ Tabs.Content and Accordion.Trigger ↔ Accordion.Content
+ * without each compound component re-deriving the same template literal.
+ *
+ * @example Inside a Tabs.Trigger
+ * ```ts
+ * const triggerId = deriveId(tabsId, "trigger", value);
+ * const panelId = deriveId(tabsId, "panel", value);
+ * ```
+ *
+ * @param rootId - The shared id for the compound component, normally
+ *   from `useId()`. Any string is accepted, including React 18's
+ *   colon-bracketed ids (`":r1:"`).
+ * @param suffix - The role of the derived id within the compound,
+ *   e.g. `"trigger"`, `"panel"`, `"heading"`.
+ * @param value - The per-item discriminator (the value prop on the
+ *   trigger / panel pair).
+ *
+ * @returns The concatenation `${rootId}-${suffix}-${value}`.
+ */
+export declare function deriveId(rootId: string, suffix: string, value: string): string;

package/dist/ids/deriveId.js

@@ -0,0 +1,27 @@
+/**
+ * Builds a deterministic sub-id from a stable root id (typically the
+ * value returned by React's `useId()`), a fixed role suffix, and a
+ * per-item value. Used to wire `aria-controls`, `aria-labelledby`, and
+ * matching DOM `id` attributes between paired sub-components such as
+ * Tabs.Trigger ↔ Tabs.Content and Accordion.Trigger ↔ Accordion.Content
+ * without each compound component re-deriving the same template literal.
+ *
+ * @example Inside a Tabs.Trigger
+ * ```ts
+ * const triggerId = deriveId(tabsId, "trigger", value);
+ * const panelId = deriveId(tabsId, "panel", value);
+ * ```
+ *
+ * @param rootId - The shared id for the compound component, normally
+ *   from `useId()`. Any string is accepted, including React 18's
+ *   colon-bracketed ids (`":r1:"`).
+ * @param suffix - The role of the derived id within the compound,
+ *   e.g. `"trigger"`, `"panel"`, `"heading"`.
+ * @param value - The per-item discriminator (the value prop on the
+ *   trigger / panel pair).
+ *
+ * @returns The concatenation `${rootId}-${suffix}-${value}`.
+ */
+export function deriveId(rootId, suffix, value) {
+    return `${rootId}-${suffix}-${value}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { deriveId } from "./ids/deriveId.js";
+export { getKeyToActionMap, type RovingKeyAction } from "./keyboard/getKeyToActionMap.js";
+export { resolveRovingTarget, type ResolveRovingTargetOptions, } from "./keyboard/resolveRovingTarget.js";
+export { tabsClick, tabsKeydown, tabsTabStop, type TabsActivationMode, type TabsKeyOutcome, type TabsOrientation, type TabsReadingDirection, type TabsState, } from "./tabs/policy.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { deriveId } from "./ids/deriveId.js";
+export { getKeyToActionMap } from "./keyboard/getKeyToActionMap.js";
+export { resolveRovingTarget, } from "./keyboard/resolveRovingTarget.js";
+export { tabsClick, tabsKeydown, tabsTabStop, } from "./tabs/policy.js";

package/dist/keyboard/getKeyToActionMap.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The abstract roving-tabindex action that a keyboard event maps to.
+ *
+ * Consumers translate the action into whatever "go to" semantics suit
+ * their pattern (focus only, focus + activate, focus + select, etc.).
+ */
+export type RovingKeyAction = "next" | "prev" | "first" | "last" | "activate";
+type GetKeyToActionMapOptions = {
+    /**
+     * Which arrow-key axis is active. `"horizontal"` enables Arrow Left/Right,
+     * `"vertical"` enables Arrow Up/Down, `"both"` enables all four. RTL
+     * inversion (see {@link GetKeyToActionMapOptions.dir | `dir`}) swaps the
+     * horizontal pair for both `"horizontal"` and `"both"`; the vertical pair
+     * is never swapped, since vertical reading order does not depend on
+     * direction.
+     */
+    orientation: "horizontal" | "vertical" | "both";
+    /**
+     * Reading direction. When `"rtl"`, swaps the meaning of Arrow Left and
+     * Arrow Right — applied for both `"horizontal"` and `"both"` orientation
+     * (never the vertical pair). Defaults to `"ltr"`.
+     */
+    dir?: "ltr" | "rtl";
+    /**
+     * When `true`, Home maps to `"first"` and End to `"last"`. Use for
+     * patterns where Home/End jumping is part of the keyboard contract
+     * (Tabs, Accordion). Defaults to `false`.
+     */
+    homeEnd?: boolean;
+    /**
+     * When `true`, Enter and Space map to `"activate"`. Use for patterns
+     * where the focused item can be confirmed via the keyboard (Tabs in
+     * `"manual"` activation mode). Defaults to `false`.
+     */
+    activate?: boolean;
+};
+/**
+ * Builds the keyboard-key → roving-tabindex-action map for a single
+ * focusable item in a compound widget. Each consumer shares the same
+ * RTL / orientation / Home-End / Enter-Space conventions and just needs
+ * to translate the abstract action ("next", "prev", "first", "last",
+ * "activate") into its own movement / activation logic.
+ *
+ * Returns a plain `Record<string, RovingKeyAction>` so call sites can do
+ * `const action = map[event.key]; if (action === "next") ...`.
+ *
+ * @example Tabs trigger (horizontal, RTL, all features)
+ * ```ts
+ * const map = getKeyToActionMap({
+ *   orientation: "horizontal",
+ *   dir,
+ *   homeEnd: true,
+ *   activate: true,
+ * });
+ * const action = map[event.key];
+ * ```
+ *
+ * @example Accordion trigger (vertical, no Enter/Space — handled separately)
+ * ```ts
+ * const map = getKeyToActionMap({ orientation: "vertical", homeEnd: true });
+ * ```
+ */
+export declare function getKeyToActionMap({ orientation, dir, homeEnd, activate, }: GetKeyToActionMapOptions): Record<string, RovingKeyAction>;
+export {};

package/dist/keyboard/getKeyToActionMap.js

@@ -0,0 +1,51 @@
+/**
+ * Builds the keyboard-key → roving-tabindex-action map for a single
+ * focusable item in a compound widget. Each consumer shares the same
+ * RTL / orientation / Home-End / Enter-Space conventions and just needs
+ * to translate the abstract action ("next", "prev", "first", "last",
+ * "activate") into its own movement / activation logic.
+ *
+ * Returns a plain `Record<string, RovingKeyAction>` so call sites can do
+ * `const action = map[event.key]; if (action === "next") ...`.
+ *
+ * @example Tabs trigger (horizontal, RTL, all features)
+ * ```ts
+ * const map = getKeyToActionMap({
+ *   orientation: "horizontal",
+ *   dir,
+ *   homeEnd: true,
+ *   activate: true,
+ * });
+ * const action = map[event.key];
+ * ```
+ *
+ * @example Accordion trigger (vertical, no Enter/Space — handled separately)
+ * ```ts
+ * const map = getKeyToActionMap({ orientation: "vertical", homeEnd: true });
+ * ```
+ */
+export function getKeyToActionMap({ orientation, 
+// No `= "ltr"` default: only `"rtl"` is ever tested, so an omitted `dir`
+// already reads as LTR, and a default here is an equivalent mutant.
+dir, homeEnd = false, activate = false, }) {
+    const map = {};
+    if (orientation === "horizontal" || orientation === "both") {
+        const forward = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+        const backward = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+        map[forward] = "next";
+        map[backward] = "prev";
+    }
+    if (orientation === "vertical" || orientation === "both") {
+        map.ArrowDown = "next";
+        map.ArrowUp = "prev";
+    }
+    if (homeEnd) {
+        map.Home = "first";
+        map.End = "last";
+    }
+    if (activate) {
+        map.Enter = "activate";
+        map[" "] = "activate";
+    }
+    return map;
+}

package/dist/keyboard/resolveRovingTarget.d.ts

@@ -0,0 +1,42 @@
+import type { RovingKeyAction } from "./getKeyToActionMap.js";
+/** Input to {@link resolveRovingTarget}. */
+export type ResolveRovingTargetOptions<K> = {
+    /**
+     * The abstract action a key press mapped to (see `getKeyToActionMap`), or
+     * `undefined` for a key the map does not cover, which resolves nothing. So a
+     * caller can pass `map[event.key]` straight through.
+     */
+    action: RovingKeyAction | undefined;
+    /**
+     * The ordered keys navigation walks through. The caller filters it: RadioGroup
+     * and Accordion leave disabled items out so arrows skip them, while Tabs keeps
+     * them in so arrows land on a disabled tab without activating it.
+     */
+    navigable: readonly K[];
+    /** The key of the item that owns the key press: the pivot for next / prev. */
+    currentKey: K;
+};
+/**
+ * Resolves which item a roving-tabindex action lands on: the index arithmetic
+ * of the WAI-ARIA roving-tabindex pattern, with no DOM and no framework.
+ *
+ * - `"next"` / `"prev"` move one step and wrap at either end. They resolve
+ *   nothing when `currentKey` is not in `navigable`, which is RadioGroup's
+ *   contract: arrows do nothing while focus sits on a disabled radio.
+ * - `"first"` / `"last"` jump to either end, whatever the current key.
+ * - `"activate"` targets the current key, so the caller confirms it.
+ * - An empty `navigable`, or no action at all, resolves nothing.
+ *
+ * The result is wrapped as `{ target }`, with `null` for "nothing", because a
+ * key can itself be `null` or `undefined` (Combobox navigates `string | null`).
+ *
+ * @example
+ * ```ts
+ * const action = getKeyToActionMap({ orientation: "horizontal" })[event.key];
+ * const result = resolveRovingTarget({ action, navigable, currentKey });
+ * if (result) focusItem(result.target);
+ * ```
+ */
+export declare function resolveRovingTarget<K>({ action, navigable, currentKey, }: ResolveRovingTargetOptions<K>): {
+    target: K;
+} | null;

package/dist/keyboard/resolveRovingTarget.js

@@ -0,0 +1,44 @@
+/**
+ * Resolves which item a roving-tabindex action lands on: the index arithmetic
+ * of the WAI-ARIA roving-tabindex pattern, with no DOM and no framework.
+ *
+ * - `"next"` / `"prev"` move one step and wrap at either end. They resolve
+ *   nothing when `currentKey` is not in `navigable`, which is RadioGroup's
+ *   contract: arrows do nothing while focus sits on a disabled radio.
+ * - `"first"` / `"last"` jump to either end, whatever the current key.
+ * - `"activate"` targets the current key, so the caller confirms it.
+ * - An empty `navigable`, or no action at all, resolves nothing.
+ *
+ * The result is wrapped as `{ target }`, with `null` for "nothing", because a
+ * key can itself be `null` or `undefined` (Combobox navigates `string | null`).
+ *
+ * @example
+ * ```ts
+ * const action = getKeyToActionMap({ orientation: "horizontal" })[event.key];
+ * const result = resolveRovingTarget({ action, navigable, currentKey });
+ * if (result) focusItem(result.target);
+ * ```
+ */
+export function resolveRovingTarget({ action, navigable, currentKey, }) {
+    const total = navigable.length;
+    if (total === 0)
+        return null;
+    switch (action) {
+        case "activate":
+            return { target: currentKey };
+        case "first":
+            return { target: navigable[0] };
+        case "last":
+            return { target: navigable[total - 1] };
+        case undefined:
+            return null;
+        case "next":
+        case "prev": {
+            const currentIndex = navigable.indexOf(currentKey);
+            if (currentIndex === -1)
+                return null;
+            const step = action === "next" ? 1 : total - 1;
+            return { target: navigable[(currentIndex + step) % total] };
+        }
+    }
+}

package/dist/tabs/policy.d.ts

@@ -0,0 +1,54 @@
+/** Layout axis of the tab list: which arrow pair moves between tabs. */
+export type TabsOrientation = "horizontal" | "vertical";
+/** Reading direction. Under `"rtl"` the horizontal arrows are mirrored. */
+export type TabsReadingDirection = "ltr" | "rtl";
+/** When a focused tab becomes active: on arrival (`"automatic"`), or only on
+ * Enter / Space (`"manual"`). */
+export type TabsActivationMode = "automatic" | "manual";
+/**
+ * Everything Tabs' keyboard and activation rules depend on, as plain data. Each
+ * surface builds it from wherever it keeps state — React state, or a custom
+ * element's attributes — and applies the outcome back the same way.
+ */
+export type TabsState = {
+    /** Every tab's value, in DOM order, disabled ones included. */
+    values: readonly string[];
+    /** The values of the disabled tabs. */
+    disabled: ReadonlySet<string>;
+    /** The active tab's value, or `undefined` when no tab is active. */
+    active: string | undefined;
+    orientation: TabsOrientation;
+    dir: TabsReadingDirection;
+    activationMode: TabsActivationMode;
+};
+/** What a key press on a tab asks for: always a tab to focus, and a tab to
+ * activate when the press should change the selection. */
+export type TabsKeyOutcome = {
+    focus: string;
+    activate: string | null;
+};
+/**
+ * The tab that takes part in the page's Tab order (the roving tab stop): the
+ * active tab, or the first tab while none is active so the tablist is still
+ * reachable by keyboard. An active value that matches no tab is returned as it
+ * is, which leaves no tab as the stop — the behaviour Tabs has always had.
+ */
+export declare function tabsTabStop(state: Pick<TabsState, "values" | "active">): string | undefined;
+/** The tab a click on `value` activates: `null` when it is disabled or already
+ * active. */
+export declare function tabsClick(state: Pick<TabsState, "disabled" | "active">, value: string): string | null;
+/**
+ * Tabs' keyboard contract for a key press on the tab `focused`:
+ *
+ * - arrows follow `orientation`, mirrored under RTL; Home / End jump to the ends;
+ *   Enter / Space confirm;
+ * - arrows **land** on a disabled tab but never activate it — unlike RadioGroup
+ *   and Accordion, which skip disabled items;
+ * - in `"automatic"` mode arriving at a tab activates it; in `"manual"` mode only
+ *   Enter / Space do;
+ * - the already-active tab is never re-activated, so no change is reported.
+ *
+ * Returns `null` for a key Tabs does not handle, which tells the caller to leave
+ * the event alone (no `preventDefault`).
+ */
+export declare function tabsKeydown(state: TabsState, focused: string, key: string): TabsKeyOutcome | null;

package/dist/tabs/policy.js

@@ -0,0 +1,44 @@
+import { getKeyToActionMap } from "../keyboard/getKeyToActionMap.js";
+import { resolveRovingTarget } from "../keyboard/resolveRovingTarget.js";
+/**
+ * The tab that takes part in the page's Tab order (the roving tab stop): the
+ * active tab, or the first tab while none is active so the tablist is still
+ * reachable by keyboard. An active value that matches no tab is returned as it
+ * is, which leaves no tab as the stop — the behaviour Tabs has always had.
+ */
+export function tabsTabStop(state) {
+    return state.active ?? state.values[0];
+}
+/** The tab a click on `value` activates: `null` when it is disabled or already
+ * active. */
+export function tabsClick(state, value) {
+    return state.disabled.has(value) || state.active === value ? null : value;
+}
+/**
+ * Tabs' keyboard contract for a key press on the tab `focused`:
+ *
+ * - arrows follow `orientation`, mirrored under RTL; Home / End jump to the ends;
+ *   Enter / Space confirm;
+ * - arrows **land** on a disabled tab but never activate it — unlike RadioGroup
+ *   and Accordion, which skip disabled items;
+ * - in `"automatic"` mode arriving at a tab activates it; in `"manual"` mode only
+ *   Enter / Space do;
+ * - the already-active tab is never re-activated, so no change is reported.
+ *
+ * Returns `null` for a key Tabs does not handle, which tells the caller to leave
+ * the event alone (no `preventDefault`).
+ */
+export function tabsKeydown(state, focused, key) {
+    const action = getKeyToActionMap({
+        orientation: state.orientation,
+        dir: state.dir,
+        homeEnd: true,
+        activate: true,
+    })[key];
+    const result = resolveRovingTarget({ action, navigable: state.values, currentKey: focused });
+    if (!result)
+        return null;
+    const target = result.target;
+    const requested = state.activationMode === "automatic" || action === "activate";
+    return { focus: target, activate: requested ? tabsClick(state, target) : null };
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@primitiv-ui/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.43",
+  "description": "The framework-free behaviour core shared by every Primitiv surface — keyboard maps, roving-focus targets, id derivation and per-component policy, as pure functions with no DOM and no dependencies.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/primitiv-ui/primitiv.git",
+    "directory": "packages/core"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
+    "@vitest/coverage-v8": "^4.1.4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/finalize-dist.mjs dist",
+    "qa": "pnpm qa:units",
+    "qa:units": "vitest run --coverage",
+    "qa:units:watch": "vitest --coverage",
+    "mutate": "stryker run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }