@primitiv-ui/core 0.1.58 → 0.1.60

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { getKeyToActionMap, type RovingKeyAction } from "./keyboard/getKeyToActi
 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";
 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 { segmentedControlKeydown, segmentedControlSelect, segmentedControlTabStop, type SegmentedControlKeyOutcome, type SegmentedControlOrientation, type SegmentedControlReadingDirection, type SegmentedControlState, } from "./segmented-control/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

@@ -3,6 +3,8 @@ export { getKeyToActionMap } from "./keyboard/getKeyToActionMap.js";
 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 { segmentedControlKeydown, segmentedControlSelect, segmentedControlTabStop, } from "./segmented-control/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/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.
+ */
+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,36 @@
+import { getKeyToActionMap } from "../keyboard/getKeyToActionMap.js";
+import { resolveRovingTarget } from "../keyboard/resolveRovingTarget.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.
+ */
+export function segmentedControlSelect(state, value) {
+    return state.disabled.has(value) || state.selected === value ? null : 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) {
+    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: segmentedControlSelect(state, result.target) };
+}
+/**
+ * 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 state.selected ?? state.values.find((value) => !state.disabled.has(value));
+}

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

@@ -0,0 +1,50 @@
+/** Layout axis of the group: which arrow pair moves between items. */
+export type ToggleGroupOrientation = "horizontal" | "vertical";
+/** Reading direction. Under `"rtl"` the horizontal arrows are mirrored. */
+export type ToggleGroupReadingDirection = "ltr" | "rtl";
+/**
+ * Everything ToggleGroup's toggle 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.
+ */
+export type ToggleGroupState = {
+    /** Every item's value, in DOM order, disabled ones included. */
+    values: readonly string[];
+    /** The values of the disabled items. */
+    disabled: ReadonlySet<string>;
+    /** The values of the pressed items. */
+    pressed: readonly string[];
+    /** Whether more than one item may be pressed at once (`type="multiple"`). */
+    multiple: boolean;
+    orientation: ToggleGroupOrientation;
+    dir: ToggleGroupReadingDirection;
+};
+/** What a key press on an item asks for: an item to move focus to, or an item
+ * to toggle — never both. */
+export type ToggleGroupKeyOutcome = {
+    focus: string | null;
+    toggle: string | null;
+};
+/**
+ * The pressed items after toggling `value`: a pressed item lets go — in single
+ * mode that leaves nothing pressed; one that is off is pressed and, unless
+ * `multiple`, replaces the pressed one. `null` for a disabled item, which never
+ * toggles, so no change is reported. The same rule as an accordion's open items.
+ */
+export declare function toggleGroupToggle(state: Pick<ToggleGroupState, "disabled" | "pressed" | "multiple">, value: string): string[] | null;
+/**
+ * ToggleGroup's keyboard contract for a key press on the item `focused`: arrows
+ * follow `orientation`, mirrored under RTL, wrap at the ends and skip disabled
+ * items; Home / End jump to the ends. They move focus only — Enter / Space
+ * toggle the focused item. Returns `null` for a key the group does not handle,
+ * which tells the caller to leave the event alone (no `preventDefault`).
+ */
+export declare function toggleGroupKeydown(state: ToggleGroupState, focused: string, key: string): ToggleGroupKeyOutcome | null;
+/**
+ * The item that takes part in the page's Tab order (the roving tab stop): the
+ * item focus last moved to, else the first pressed item, else the first item —
+ * always an enabled one that is still there, so Tab reaches the group.
+ */
+export declare function toggleGroupTabStop(state: Pick<ToggleGroupState, "values" | "disabled" | "pressed"> & {
+    focused: string | undefined;
+}): string | undefined;

package/dist/toggle-group/policy.js

@@ -0,0 +1,30 @@
+import { accordionKeydown, accordionToggle } from "../accordion/policy.js";
+/**
+ * The pressed items after toggling `value`: a pressed item lets go — in single
+ * mode that leaves nothing pressed; one that is off is pressed and, unless
+ * `multiple`, replaces the pressed one. `null` for a disabled item, which never
+ * toggles, so no change is reported. The same rule as an accordion's open items.
+ */
+export function toggleGroupToggle(state, value) {
+    return accordionToggle({ disabled: state.disabled, expanded: state.pressed, multiple: state.multiple }, value);
+}
+/**
+ * ToggleGroup's keyboard contract for a key press on the item `focused`: arrows
+ * follow `orientation`, mirrored under RTL, wrap at the ends and skip disabled
+ * items; Home / End jump to the ends. They move focus only — Enter / Space
+ * toggle the focused item. Returns `null` for a key the group does not handle,
+ * which tells the caller to leave the event alone (no `preventDefault`).
+ */
+export function toggleGroupKeydown(state, focused, key) {
+    return accordionKeydown({ ...state, expanded: state.pressed }, focused, key);
+}
+/**
+ * The item that takes part in the page's Tab order (the roving tab stop): the
+ * item focus last moved to, else the first pressed item, else the first item —
+ * always an enabled one that is still there, so Tab reaches the group.
+ */
+export function toggleGroupTabStop(state) {
+    const enabled = state.values.filter((value) => !state.disabled.has(value));
+    // `undefined` is never an enabled value, so a missing focus or first item drops out.
+    return [state.focused, ...state.pressed, enabled[0]].find((value) => enabled.includes(value));
+}

package/package.json

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