@primitiv-ui/core 0.1.52 → 0.1.54

package/dist/focus/focusable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Elements that can receive keyboard focus and take part in the natural tab
+ * order. Two consumers rely on it: moving initial focus into a surface when it
+ * opens (e.g. `Popover`), and locating the boundary elements of a focus trap
+ * (e.g. `Modal`). `[tabindex="-1"]` is excluded because such elements are only
+ * programmatically focusable, not tabbable.
+ */
+export declare const FOCUSABLE_SELECTOR: string;

package/dist/focus/focusable.js

@@ -0,0 +1,15 @@
+/**
+ * Elements that can receive keyboard focus and take part in the natural tab
+ * order. Two consumers rely on it: moving initial focus into a surface when it
+ * opens (e.g. `Popover`), and locating the boundary elements of a focus trap
+ * (e.g. `Modal`). `[tabindex="-1"]` is excluded because such elements are only
+ * programmatically focusable, not tabbable.
+ */
+export const FOCUSABLE_SELECTOR = [
+    "a[href]",
+    "button:not([disabled])",
+    "input:not([disabled])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    '[tabindex]:not([tabindex="-1"])',
+].join(",");

package/dist/index.d.ts

@@ -4,3 +4,5 @@ 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 { collapsibleKeydown, collapsibleToggle, type CollapsibleKeyOutcome, type CollapsibleState, } from "./collapsible/policy.js";
+export { FOCUSABLE_SELECTOR } from "./focus/focusable.js";
+export { modalPointerOutside, modalTabKeydown, type ModalBox, type ModalTabOutcome, type ModalTabState, } from "./modal/policy.js";

package/dist/index.js

@@ -4,3 +4,5 @@ export { resolveRovingTarget, } from "./keyboard/resolveRovingTarget.js";
 export { tabsClick, tabsKeydown, tabsTabStop, } from "./tabs/policy.js";
 export { accordionKeydown, accordionToggle, } from "./accordion/policy.js";
 export { collapsibleKeydown, collapsibleToggle, } from "./collapsible/policy.js";
+export { FOCUSABLE_SELECTOR } from "./focus/focusable.js";
+export { modalPointerOutside, modalTabKeydown, } from "./modal/policy.js";

package/dist/modal/policy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a key press inside an open modal dialog needs to know: the key, whether
+ * Shift was held, how many focusable elements the dialog holds, and which of
+ * them (by index, in tab order) has focus — `-1` when focus is on none of them.
+ */
+export type ModalTabState = {
+    key: string;
+    shiftKey: boolean;
+    /** The index of the focused element among the focusables, or `-1`. */
+    active: number;
+    /** How many focusable elements the dialog holds. */
+    count: number;
+};
+/**
+ * What a Tab press inside the dialog asks for: prevent the browser's default
+ * and focus the focusable at `focus`, or, when `focus` is `null`, focus
+ * nothing (there is nothing inside to focus).
+ */
+export type ModalTabOutcome = {
+    focus: number | null;
+};
+/**
+ * The modal dialog's focus trap (WAI-ARIA APG Modal Dialog). A native modal
+ * `<dialog>` makes the page behind it inert but does not wrap: Tab past the last
+ * element escapes to the browser chrome. So only the two boundary presses are
+ * taken over — Tab on the last focusable moves to the first, Shift+Tab on the
+ * first moves to the last — and a dialog with nothing focusable blocks Tab so
+ * focus cannot leak out. Every interior press is left to the browser, whose
+ * inert-aware order keeps radio groups and the like working.
+ *
+ * Returns `null` for anything to leave alone (no `preventDefault`).
+ */
+export declare function modalTabKeydown({ key, shiftKey, active, count }: ModalTabState): ModalTabOutcome | null;
+/** A box in viewport coordinates, as `getBoundingClientRect()` reports one. */
+export type ModalBox = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * Whether a pointer at `point` landed outside the dialog's `box`. A modal
+ * `<dialog>` paints its own `::backdrop` in the top layer, so a press on the
+ * dimmed page targets the dialog itself; its coordinates are the only way to
+ * tell the backdrop from the dialog. The box's edges count as inside.
+ */
+export declare function modalPointerOutside(box: ModalBox, point: {
+    x: number;
+    y: number;
+}): boolean;

package/dist/modal/policy.js

@@ -0,0 +1,32 @@
+/**
+ * The modal dialog's focus trap (WAI-ARIA APG Modal Dialog). A native modal
+ * `<dialog>` makes the page behind it inert but does not wrap: Tab past the last
+ * element escapes to the browser chrome. So only the two boundary presses are
+ * taken over — Tab on the last focusable moves to the first, Shift+Tab on the
+ * first moves to the last — and a dialog with nothing focusable blocks Tab so
+ * focus cannot leak out. Every interior press is left to the browser, whose
+ * inert-aware order keeps radio groups and the like working.
+ *
+ * Returns `null` for anything to leave alone (no `preventDefault`).
+ */
+export function modalTabKeydown({ key, shiftKey, active, count }) {
+    if (key !== "Tab")
+        return null;
+    if (count === 0)
+        return { focus: null };
+    const last = count - 1;
+    if (!shiftKey && active === last)
+        return { focus: 0 };
+    if (shiftKey && active === 0)
+        return { focus: last };
+    return null;
+}
+/**
+ * Whether a pointer at `point` landed outside the dialog's `box`. A modal
+ * `<dialog>` paints its own `::backdrop` in the top layer, so a press on the
+ * dimmed page targets the dialog itself; its coordinates are the only way to
+ * tell the backdrop from the dialog. The box's edges count as inside.
+ */
+export function modalPointerOutside(box, point) {
+    return point.x < box.left || point.x > box.right || point.y < box.top || point.y > box.bottom;
+}

package/package.json

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