@primitiv-ui/core 0.1.53 → 0.1.55

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,6 @@ 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";
+export { popoverKeydown, popoverPressDismisses, type PopoverKeyOutcome, type PopoverPress, } from "./popover/policy.js";

package/dist/index.js

@@ -4,3 +4,6 @@ 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";
+export { popoverKeydown, popoverPressDismisses, } from "./popover/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/dist/popover/policy.d.ts

@@ -0,0 +1,31 @@
+/** What a key press inside an open popover asks for: the open state to move to. */
+export type PopoverKeyOutcome = {
+    open: false;
+};
+/**
+ * The popover's keyboard contract for a key press inside its panel: Escape
+ * closes it (and the caller hands focus back to the trigger, since focus moved
+ * into the panel on open). Returns `null` for any other key, which tells the
+ * caller to leave the event alone.
+ */
+export declare function popoverKeydown(key: string): PopoverKeyOutcome | null;
+/** Where a press landed, relative to an open popover, and whether the browser handles it. */
+export type PopoverPress = {
+    /** Whether the popover is open. */
+    open: boolean;
+    /** Whether the browser light-dismisses `popover="auto"` itself (the Popover API exists). */
+    nativeLightDismiss: boolean;
+    /** Whether the press landed on (or in) the trigger. */
+    inTrigger: boolean;
+    /** Whether the press landed inside a popover — this one, or one nested in it. */
+    inPopover: boolean;
+};
+/**
+ * Whether a press dismisses the popover. A browser with the Popover API
+ * light-dismisses an `auto` popover on an outside press and reports it with a
+ * `toggle` event, so this only answers where it does not; answering there too
+ * would catch the very click that opened the popover from an outside control
+ * and close it again. A press on the trigger toggles it instead, and one inside
+ * any popover is inside.
+ */
+export declare function popoverPressDismisses({ open, nativeLightDismiss, inTrigger, inPopover }: PopoverPress): boolean;

package/dist/popover/policy.js

@@ -0,0 +1,20 @@
+/**
+ * The popover's keyboard contract for a key press inside its panel: Escape
+ * closes it (and the caller hands focus back to the trigger, since focus moved
+ * into the panel on open). Returns `null` for any other key, which tells the
+ * caller to leave the event alone.
+ */
+export function popoverKeydown(key) {
+    return key === "Escape" ? { open: false } : null;
+}
+/**
+ * Whether a press dismisses the popover. A browser with the Popover API
+ * light-dismisses an `auto` popover on an outside press and reports it with a
+ * `toggle` event, so this only answers where it does not; answering there too
+ * would catch the very click that opened the popover from an outside control
+ * and close it again. A press on the trigger toggles it instead, and one inside
+ * any popover is inside.
+ */
+export function popoverPressDismisses({ open, nativeLightDismiss, inTrigger, inPopover }) {
+    return open && !nativeLightDismiss && !inTrigger && !inPopover;
+}

package/package.json

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