@primitiv-ui/core 0.1.59 → 0.1.61

package/dist/checkbox-card/policy.d.ts

@@ -0,0 +1,13 @@
+/** A checkbox's state: checked, unchecked, or `"indeterminate"` (mixed). */
+export type CheckboxCardCheckedState = boolean | "indeterminate";
+/** Everything a checkbox card's toggle depends on, as plain data. */
+export type CheckboxCardState = {
+    checked: CheckboxCardCheckedState;
+    disabled: boolean;
+};
+/**
+ * The state a press on a checkbox card asks for: the opposite of checked, with
+ * a mixed card becoming checked — a press always resolves the mix. `null` while
+ * the card is disabled, so no change is reported.
+ */
+export declare function checkboxCardToggle(state: CheckboxCardState): boolean | null;

package/dist/checkbox-card/policy.js

@@ -0,0 +1,10 @@
+/**
+ * The state a press on a checkbox card asks for: the opposite of checked, with
+ * a mixed card becoming checked — a press always resolves the mix. `null` while
+ * the card is disabled, so no change is reported.
+ */
+export function checkboxCardToggle(state) {
+    if (state.disabled)
+        return null;
+    return state.checked === "indeterminate" ? true : !state.checked;
+}

package/dist/index.d.ts

@@ -4,6 +4,10 @@ export { resolveRovingTarget, type ResolveRovingTargetOptions, } from "./keyboar
 export { tabsClick, tabsKeydown, tabsTabStop, type TabsActivationMode, type TabsKeyOutcome, type TabsOrientation, type TabsReadingDirection, type TabsState, } from "./tabs/policy.js";
 export { accordionKeydown, accordionToggle, type AccordionKeyOutcome, type AccordionOrientation, type AccordionReadingDirection, type AccordionState, } from "./accordion/policy.js";
 export { toggleGroupKeydown, toggleGroupTabStop, toggleGroupToggle, type ToggleGroupKeyOutcome, type ToggleGroupOrientation, type ToggleGroupReadingDirection, type ToggleGroupState, } from "./toggle-group/policy.js";
+export { radioGroupKeydown, radioGroupSelect, radioGroupTabStop, type RadioGroupKeyOutcome, type RadioGroupOrientation, type RadioGroupReadingDirection, type RadioGroupState, } from "./radio-group/policy.js";
+export { segmentedControlKeydown, segmentedControlSelect, segmentedControlTabStop, type SegmentedControlKeyOutcome, type SegmentedControlOrientation, type SegmentedControlReadingDirection, type SegmentedControlState, } from "./segmented-control/policy.js";
+export { checkboxCardToggle, type CheckboxCardCheckedState, type CheckboxCardState, } from "./checkbox-card/policy.js";
+export { sliderClosestThumb, sliderEdge, sliderKeyValue, sliderPercent, sliderPointerValue, sliderRangeInsets, sliderSetThumb, sliderSnap, sliderThumbInset, type SliderAxis, type SliderEdge, type SliderInset, type SliderOrientation, type SliderReadingDirection, type SliderScale, } from "./slider/policy.js";
 export { collapsibleKeydown, collapsibleToggle, type CollapsibleKeyOutcome, type CollapsibleState, } from "./collapsible/policy.js";
 export { FOCUSABLE_SELECTOR } from "./focus/focusable.js";
 export { MENU_ITEM_SELECTOR, MENU_TYPEAHEAD_RESET_MS, menuKeydown, menuTypeahead, type MenuKeyOutcome, type MenuKeyState, type MenuTypeaheadOutcome, type MenuTypeaheadState, } from "./menu/policy.js";

package/dist/index.js

@@ -4,6 +4,10 @@ export { resolveRovingTarget, } from "./keyboard/resolveRovingTarget.js";
 export { tabsClick, tabsKeydown, tabsTabStop, } from "./tabs/policy.js";
 export { accordionKeydown, accordionToggle, } from "./accordion/policy.js";
 export { toggleGroupKeydown, toggleGroupTabStop, toggleGroupToggle, } from "./toggle-group/policy.js";
+export { radioGroupKeydown, radioGroupSelect, radioGroupTabStop, } from "./radio-group/policy.js";
+export { segmentedControlKeydown, segmentedControlSelect, segmentedControlTabStop, } from "./segmented-control/policy.js";
+export { checkboxCardToggle, } from "./checkbox-card/policy.js";
+export { sliderClosestThumb, sliderEdge, sliderKeyValue, sliderPercent, sliderPointerValue, sliderRangeInsets, sliderSetThumb, sliderSnap, sliderThumbInset, } from "./slider/policy.js";
 export { collapsibleKeydown, collapsibleToggle, } from "./collapsible/policy.js";
 export { FOCUSABLE_SELECTOR } from "./focus/focusable.js";
 export { MENU_ITEM_SELECTOR, MENU_TYPEAHEAD_RESET_MS, menuKeydown, menuTypeahead, } from "./menu/policy.js";

package/dist/radio-group/policy.d.ts

@@ -0,0 +1,52 @@
+/** Which arrow pairs move between items: one axis, or `"both"` for all four
+ * arrows (a grid of cards that wraps). */
+export type RadioGroupOrientation = "horizontal" | "vertical" | "both";
+/** Reading direction. Under `"rtl"` the horizontal arrows are mirrored. */
+export type RadioGroupReadingDirection = "ltr" | "rtl";
+/**
+ * Everything a radio group's selection and keyboard rules depend on, as plain
+ * data — shared by every single-select radio-group component (SegmentedControl,
+ * RadioCard). Each surface builds it from wherever it keeps state and applies
+ * the outcome back the same way. A whole-group disable is every value in
+ * `disabled`.
+ */
+export type RadioGroupState = {
+    /** Every item's value, in DOM order, disabled ones included. */
+    values: readonly string[];
+    /** The values of the disabled items. */
+    disabled: ReadonlySet<string>;
+    /** The selected item's value, or `undefined` while none is selected. */
+    selected: string | undefined;
+    orientation: RadioGroupOrientation;
+    dir: RadioGroupReadingDirection;
+};
+/** What a key press on an item asks for: an item to focus, and the item to
+ * select — `null` when it is already selected, so no change is reported. */
+export type RadioGroupKeyOutcome = {
+    focus: string;
+    select: string | null;
+};
+/**
+ * The item a click on `value` selects: `null` when it is disabled or already
+ * selected. A selected item never lets go, so the selection cannot be cleared
+ * to nothing.
+ */
+export declare function radioGroupSelect(state: Pick<RadioGroupState, "disabled" | "selected">, value: string): string | null;
+/**
+ * The WAI-ARIA radio group's keyboard contract for a key press on the item
+ * `focused`: the arrows follow `orientation` (all four under `"both"`), the
+ * horizontal pair mirrored under RTL, wrap at the ends and skip disabled items,
+ * and each one moves focus **and** selection. While focus sits on a disabled
+ * item they do nothing. There is no Home / End, and Enter / Space are the
+ * native button's click.
+ *
+ * Returns `null` for a key the group does not handle, which tells the caller to
+ * leave the event alone (no `preventDefault`).
+ */
+export declare function radioGroupKeydown(state: RadioGroupState, focused: string, key: string): RadioGroupKeyOutcome | null;
+/**
+ * The item that takes part in the page's Tab order (the roving tab stop): the
+ * selected item, else the first enabled one so the group is still reachable by
+ * keyboard — or none, while nothing is selected and every item is disabled.
+ */
+export declare function radioGroupTabStop(state: Pick<RadioGroupState, "values" | "disabled" | "selected">): string | undefined;

package/dist/radio-group/policy.js

@@ -0,0 +1,35 @@
+import { getKeyToActionMap } from "../keyboard/getKeyToActionMap.js";
+import { resolveRovingTarget } from "../keyboard/resolveRovingTarget.js";
+/**
+ * The item a click on `value` selects: `null` when it is disabled or already
+ * selected. A selected item never lets go, so the selection cannot be cleared
+ * to nothing.
+ */
+export function radioGroupSelect(state, value) {
+    return state.disabled.has(value) || state.selected === value ? null : value;
+}
+/**
+ * The WAI-ARIA radio group's keyboard contract for a key press on the item
+ * `focused`: the arrows follow `orientation` (all four under `"both"`), the
+ * horizontal pair mirrored under RTL, wrap at the ends and skip disabled items,
+ * and each one moves focus **and** selection. While focus sits on a disabled
+ * item they do nothing. There is no Home / End, and Enter / Space are the
+ * native button's click.
+ *
+ * Returns `null` for a key the group does not handle, which tells the caller to
+ * leave the event alone (no `preventDefault`).
+ */
+export function radioGroupKeydown(state, focused, key) {
+    const action = getKeyToActionMap({ orientation: state.orientation, dir: state.dir })[key];
+    const navigable = state.values.filter((value) => !state.disabled.has(value));
+    const result = resolveRovingTarget({ action, navigable, currentKey: focused });
+    return result && { focus: result.target, select: radioGroupSelect(state, result.target) };
+}
+/**
+ * The item that takes part in the page's Tab order (the roving tab stop): the
+ * selected item, else the first enabled one so the group is still reachable by
+ * keyboard — or none, while nothing is selected and every item is disabled.
+ */
+export function radioGroupTabStop(state) {
+    return state.selected ?? state.values.find((value) => !state.disabled.has(value));
+}

package/dist/segmented-control/policy.d.ts

@@ -0,0 +1,51 @@
+/** Layout axis of the control: which arrow pair moves between segments. */
+export type SegmentedControlOrientation = "horizontal" | "vertical";
+/** Reading direction. Under `"rtl"` the horizontal arrows are mirrored. */
+export type SegmentedControlReadingDirection = "ltr" | "rtl";
+/**
+ * Everything SegmentedControl's selection and keyboard 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. A whole-control disable is every value in `disabled`.
+ */
+export type SegmentedControlState = {
+    /** Every segment's value, in DOM order, disabled ones included. */
+    values: readonly string[];
+    /** The values of the disabled segments. */
+    disabled: ReadonlySet<string>;
+    /** The selected segment's value, or `undefined` while none is selected. */
+    selected: string | undefined;
+    orientation: SegmentedControlOrientation;
+    dir: SegmentedControlReadingDirection;
+};
+/** What a key press on a segment asks for: a segment to focus, and the segment
+ * to select — `null` when it is already selected, so no change is reported. */
+export type SegmentedControlKeyOutcome = {
+    focus: string;
+    select: string | null;
+};
+/**
+ * The segment a click on `value` selects: `null` when it is disabled or
+ * already selected. A selected segment never lets go, so — unlike a toggle
+ * group — the selection cannot be cleared to nothing. The radio group's rule.
+ */
+export declare function segmentedControlSelect(state: Pick<SegmentedControlState, "disabled" | "selected">, value: string): string | null;
+/**
+ * SegmentedControl's keyboard contract — the WAI-ARIA radio group's — for a key
+ * press on the segment `focused`: the arrows follow `orientation`, mirrored
+ * under RTL, wrap at the ends and skip disabled segments, and each one moves
+ * focus **and** selection. While focus sits on a disabled segment they do
+ * nothing. There is no Home / End, and Enter / Space are the native button's
+ * click.
+ *
+ * Returns `null` for a key the control does not handle, which tells the caller
+ * to leave the event alone (no `preventDefault`).
+ */
+export declare function segmentedControlKeydown(state: SegmentedControlState, focused: string, key: string): SegmentedControlKeyOutcome | null;
+/**
+ * The segment that takes part in the page's Tab order (the roving tab stop):
+ * the selected segment, else the first enabled one so the control is still
+ * reachable by keyboard — or none, while nothing is selected and every segment
+ * is disabled.
+ */
+export declare function segmentedControlTabStop(state: Pick<SegmentedControlState, "values" | "disabled" | "selected">): string | undefined;

package/dist/segmented-control/policy.js

@@ -0,0 +1,32 @@
+import { radioGroupKeydown, radioGroupSelect, radioGroupTabStop } from "../radio-group/policy.js";
+/**
+ * The segment a click on `value` selects: `null` when it is disabled or
+ * already selected. A selected segment never lets go, so — unlike a toggle
+ * group — the selection cannot be cleared to nothing. The radio group's rule.
+ */
+export function segmentedControlSelect(state, value) {
+    return radioGroupSelect(state, value);
+}
+/**
+ * SegmentedControl's keyboard contract — the WAI-ARIA radio group's — for a key
+ * press on the segment `focused`: the arrows follow `orientation`, mirrored
+ * under RTL, wrap at the ends and skip disabled segments, and each one moves
+ * focus **and** selection. While focus sits on a disabled segment they do
+ * nothing. There is no Home / End, and Enter / Space are the native button's
+ * click.
+ *
+ * Returns `null` for a key the control does not handle, which tells the caller
+ * to leave the event alone (no `preventDefault`).
+ */
+export function segmentedControlKeydown(state, focused, key) {
+    return radioGroupKeydown(state, focused, key);
+}
+/**
+ * The segment that takes part in the page's Tab order (the roving tab stop):
+ * the selected segment, else the first enabled one so the control is still
+ * reachable by keyboard — or none, while nothing is selected and every segment
+ * is disabled.
+ */
+export function segmentedControlTabStop(state) {
+    return radioGroupTabStop(state);
+}

package/dist/slider/policy.d.ts

@@ -0,0 +1,77 @@
+/** Layout axis of the slider. */
+export type SliderOrientation = "horizontal" | "vertical";
+/** Reading direction. Under `"rtl"` a horizontal slider runs right to left. */
+export type SliderReadingDirection = "ltr" | "rtl";
+/** Which way a slider runs: its axis, reading direction, and whether it is inverted. */
+export type SliderAxis = {
+    orientation: SliderOrientation;
+    dir: SliderReadingDirection;
+    /** Run from the opposite end: max at the start edge. */
+    inverted: boolean;
+};
+/** The values a slider takes: `min` to `max` in `step`s. */
+export type SliderScale = {
+    min: number;
+    max: number;
+    step: number;
+};
+/** A physical edge of the track. */
+export type SliderEdge = "left" | "right" | "top" | "bottom";
+/** A distance from one edge of the track, as a percentage of its length. */
+export type SliderInset = {
+    edge: SliderEdge;
+    percent: number;
+};
+/** `value` rounded to the nearest step counted from `min`, at the step's own precision. */
+export declare function sliderSnap(value: number, min: number, step: number): number;
+/** Where `value` sits between `min` and `max`, as a percentage clamped to 0–100. */
+export declare function sliderPercent(value: number, min: number, max: number): number;
+/**
+ * The edge a slider measures from — where its `min` sits: the left (right under
+ * RTL) of a horizontal track, the bottom of a vertical one, and the opposite
+ * edge when inverted.
+ */
+export declare function sliderEdge({ orientation, dir, inverted }: SliderAxis): SliderEdge;
+/** Where a thumb at `value` sits: its distance from the start edge. */
+export declare function sliderThumbInset(value: number, { min, max }: Pick<SliderScale, "min" | "max">, axis: SliderAxis): SliderInset;
+/**
+ * Where the filled range sits: from the start edge to a single thumb, or between
+ * the outermost of several — as its two insets, from the start edge and from the
+ * opposite one.
+ */
+export declare function sliderRangeInsets(values: readonly number[], { min, max }: Pick<SliderScale, "min" | "max">, axis: SliderAxis): {
+    start: SliderInset;
+    end: SliderInset;
+};
+/**
+ * The value under a pointer at `point` on a track whose box is `rect`: read
+ * along the axis from the start edge, clamped to the track, snapped to the step
+ * and kept within the scale.
+ */
+export declare function sliderPointerValue(point: {
+    x: number;
+    y: number;
+}, rect: {
+    left: number;
+    width: number;
+    bottom: number;
+    height: number;
+}, { min, max, step, orientation, dir, inverted }: SliderScale & SliderAxis): number;
+/**
+ * The WAI-ARIA slider keys for a thumb at `value`: the arrows step one `step`
+ * (up and toward the end increase, mirrored under RTL and when inverted),
+ * Page Up / Page Down ten, Home / End jump to `min` / `max`. The result is
+ * snapped to the step but not clamped — the thumb's own bounds do that. `null`
+ * for any other key.
+ */
+export declare function sliderKeyValue(key: string, value: number, { min, max, step, orientation, dir, inverted }: SliderScale & SliderAxis): number | null;
+/**
+ * Every thumb's value after moving thumb `index` to `value`: kept within the
+ * scale and between its neighbours, `minStepsBetweenThumbs` steps apart. `null`
+ * when the thumb would not move, so no change is reported.
+ */
+export declare function sliderSetThumb(values: readonly number[], index: number, value: number, { min, max, step, minStepsBetweenThumbs }: SliderScale & {
+    minStepsBetweenThumbs: number;
+}): number[] | null;
+/** The index of the thumb nearest `value`, the first on a tie. */
+export declare function sliderClosestThumb(value: number, values: readonly number[]): number;

package/dist/slider/policy.js

@@ -0,0 +1,102 @@
+const OPPOSITE = { left: "right", right: "left", top: "bottom", bottom: "top" };
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/** `value` rounded to the nearest step counted from `min`, at the step's own precision. */
+export function sliderSnap(value, min, step) {
+    const snapped = min + Math.round((value - min) / step) * step;
+    const decimals = String(step).split(".")[1]?.length ?? 0;
+    return Number(snapped.toFixed(decimals));
+}
+/** Where `value` sits between `min` and `max`, as a percentage clamped to 0–100. */
+export function sliderPercent(value, min, max) {
+    return clamp(((value - min) / (max - min)) * 100, 0, 100);
+}
+/**
+ * The edge a slider measures from — where its `min` sits: the left (right under
+ * RTL) of a horizontal track, the bottom of a vertical one, and the opposite
+ * edge when inverted.
+ */
+export function sliderEdge({ orientation, dir, inverted }) {
+    const start = orientation === "vertical" ? "bottom" : dir === "rtl" ? "right" : "left";
+    return inverted ? OPPOSITE[start] : start;
+}
+/** Where a thumb at `value` sits: its distance from the start edge. */
+export function sliderThumbInset(value, { min, max }, axis) {
+    return { edge: sliderEdge(axis), percent: sliderPercent(value, min, max) };
+}
+/**
+ * Where the filled range sits: from the start edge to a single thumb, or between
+ * the outermost of several — as its two insets, from the start edge and from the
+ * opposite one.
+ */
+export function sliderRangeInsets(values, { min, max }, axis) {
+    const edge = sliderEdge(axis);
+    const percents = values.map((value) => sliderPercent(value, min, max));
+    const start = values.length > 1 ? Math.min(...percents) : 0;
+    return { start: { edge, percent: start }, end: { edge: OPPOSITE[edge], percent: 100 - Math.max(...percents) } };
+}
+/**
+ * The value under a pointer at `point` on a track whose box is `rect`: read
+ * along the axis from the start edge, clamped to the track, snapped to the step
+ * and kept within the scale.
+ */
+export function sliderPointerValue(point, rect, { min, max, step, orientation, dir, inverted }) {
+    const vertical = orientation === "vertical";
+    const fromStart = vertical ? (rect.bottom - point.y) / rect.height : (point.x - rect.left) / rect.width;
+    const reversed = vertical ? inverted : (dir === "rtl") !== inverted;
+    const percent = clamp(reversed ? 1 - fromStart : fromStart, 0, 1);
+    return clamp(sliderSnap(min + percent * (max - min), min, step), min, max);
+}
+/**
+ * The WAI-ARIA slider keys for a thumb at `value`: the arrows step one `step`
+ * (up and toward the end increase, mirrored under RTL and when inverted),
+ * Page Up / Page Down ten, Home / End jump to `min` / `max`. The result is
+ * snapped to the step but not clamped — the thumb's own bounds do that. `null`
+ * for any other key.
+ */
+export function sliderKeyValue(key, value, { min, max, step, orientation, dir, inverted }) {
+    if (key === "Home")
+        return min;
+    if (key === "End")
+        return max;
+    let increases;
+    if (key === "PageUp" || key === "PageDown") {
+        increases = key === "PageUp";
+    }
+    else if (key === "ArrowUp" || key === "ArrowDown") {
+        increases = (key === "ArrowUp") !== (orientation === "vertical" && inverted);
+    }
+    else if (key === "ArrowRight" || key === "ArrowLeft") {
+        const rightIncreases = orientation === "vertical" || (dir === "ltr") !== inverted;
+        increases = (key === "ArrowRight") === rightIncreases;
+    }
+    else {
+        return null;
+    }
+    const magnitude = key.startsWith("Page") ? step * 10 : step;
+    return sliderSnap(value + (increases ? magnitude : -magnitude), min, step);
+}
+/**
+ * Every thumb's value after moving thumb `index` to `value`: kept within the
+ * scale and between its neighbours, `minStepsBetweenThumbs` steps apart. `null`
+ * when the thumb would not move, so no change is reported.
+ */
+export function sliderSetThumb(values, index, value, { min, max, step, minStepsBetweenThumbs }) {
+    const gap = minStepsBetweenThumbs * step;
+    const lower = index > 0 ? values[index - 1] + gap : min;
+    const upper = index < values.length - 1 ? values[index + 1] - gap : max;
+    const next = clamp(value, lower, upper);
+    if (values[index] === next)
+        return null;
+    return values.map((entry, i) => (i === index ? next : entry));
+}
+/** The index of the thumb nearest `value`, the first on a tie. */
+export function sliderClosestThumb(value, values) {
+    let closest = 0;
+    values.forEach((thumb, index) => {
+        if (Math.abs(thumb - value) < Math.abs(values[closest] - value))
+            closest = index;
+    });
+    return closest;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitiv-ui/core",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "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",