@primitiv-ui/core 0.1.55 → 0.1.57

package/dist/index.d.ts

@@ -5,5 +5,8 @@ export { tabsClick, tabsKeydown, tabsTabStop, type TabsActivationMode, type Tabs
 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 { MENU_ITEM_SELECTOR, MENU_TYPEAHEAD_RESET_MS, menuKeydown, menuTypeahead, type MenuKeyOutcome, type MenuKeyState, type MenuTypeaheadOutcome, type MenuTypeaheadState, } from "./menu/policy.js";
 export { modalPointerOutside, modalTabKeydown, type ModalBox, type ModalTabOutcome, type ModalTabState, } from "./modal/policy.js";
+export { panelPlacement, type PanelPlacement, type PlacementBox } from "./placement/placement.js";
 export { popoverKeydown, popoverPressDismisses, type PopoverKeyOutcome, type PopoverPress, } from "./popover/policy.js";
+export { TOOLTIP_GRACE_MS, tooltipOpenDelay, type TooltipDelayState } from "./tooltip/policy.js";

package/dist/index.js

@@ -5,5 +5,8 @@ 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 { MENU_ITEM_SELECTOR, MENU_TYPEAHEAD_RESET_MS, menuKeydown, menuTypeahead, } from "./menu/policy.js";
 export { modalPointerOutside, modalTabKeydown, } from "./modal/policy.js";
+export { panelPlacement } from "./placement/placement.js";
 export { popoverKeydown, popoverPressDismisses, } from "./popover/policy.js";
+export { TOOLTIP_GRACE_MS, tooltipOpenDelay } from "./tooltip/policy.js";

package/dist/menu/policy.d.ts

@@ -0,0 +1,61 @@
+/** A menu's enabled items, as the selector a host finds them with: every item role, bar the disabled. */
+export declare const MENU_ITEM_SELECTOR: string;
+/** A key press inside an open menu, with where focus is among its enabled items. */
+export type MenuKeyState = {
+    /** The key pressed. */
+    key: string;
+    /** The index of the focused item, or `-1` when focus is on none of them. */
+    active: number;
+    /** How many enabled items the menu holds. */
+    count: number;
+};
+/** What a key press inside a menu asks for. */
+export type MenuKeyOutcome = 
+/** Move focus to the item at this index. */
+{
+    focus: number;
+}
+/** Activate (click) the item at this index. */
+ | {
+    activate: number;
+}
+/** Close the menu (and the caller hands focus back to the trigger). */
+ | {
+    open: false;
+};
+/**
+ * The menu's keyboard contract (WAI-ARIA APG Menu Button): the arrows move
+ * through the items and wrap, Home and End jump to the ends, Enter and Space
+ * activate the focused item, and Escape closes. Returns `null` for any other
+ * key, and for every key in a menu with no enabled items, which tells the
+ * caller to leave the event alone. Typeahead is {@link menuTypeahead}'s.
+ */
+export declare function menuKeydown({ key, active, count }: MenuKeyState): MenuKeyOutcome | null;
+/** How long, in milliseconds, a typeahead query lasts after the last key before it starts afresh. */
+export declare const MENU_TYPEAHEAD_RESET_MS: number;
+/** A key press to search a menu's items by, with the query typed so far. */
+export type MenuTypeaheadState = {
+    /** The query typed so far, lower-cased; empty once it has lapsed. */
+    query: string;
+    /** The key pressed. */
+    key: string;
+    /** Each enabled item's text, in order. */
+    labels: readonly string[];
+    /** The index of the focused item, or `-1` when focus is on none of them. */
+    active: number;
+};
+/** The query after a typeahead key, and the item to focus (`null` when none matches). */
+export type MenuTypeaheadOutcome = {
+    query: string;
+    focus: number | null;
+};
+/**
+ * Typeahead: a printable key extends the query and focuses the first item
+ * whose text starts with it. A single letter, or one letter repeated, starts
+ * after the focused item so repeating it cycles through the matches; a longer
+ * query may match the focused item itself. Returns `null` for a key that is
+ * not a printable character (Space activates), which tells the caller to leave
+ * the event alone. The caller lapses the query after
+ * {@link MENU_TYPEAHEAD_RESET_MS}.
+ */
+export declare function menuTypeahead({ query, key, labels, active }: MenuTypeaheadState): MenuTypeaheadOutcome | null;

package/dist/menu/policy.js

@@ -0,0 +1,55 @@
+/** A menu's enabled items, as the selector a host finds them with: every item role, bar the disabled. */
+export const MENU_ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"]), [role="menuitemcheckbox"]:not([aria-disabled="true"]), [role="menuitemradio"]:not([aria-disabled="true"])';
+/**
+ * The menu's keyboard contract (WAI-ARIA APG Menu Button): the arrows move
+ * through the items and wrap, Home and End jump to the ends, Enter and Space
+ * activate the focused item, and Escape closes. Returns `null` for any other
+ * key, and for every key in a menu with no enabled items, which tells the
+ * caller to leave the event alone. Typeahead is {@link menuTypeahead}'s.
+ */
+export function menuKeydown({ key, active, count }) {
+    if (count === 0)
+        return null;
+    switch (key) {
+        case "ArrowDown":
+            return { focus: (active + 1) % count };
+        case "ArrowUp":
+            return { focus: active <= 0 ? count - 1 : active - 1 };
+        case "Home":
+            return { focus: 0 };
+        case "End":
+            return { focus: count - 1 };
+        case "Enter":
+        case " ":
+            return active < 0 ? null : { activate: active };
+        case "Escape":
+            return { open: false };
+        default:
+            return null;
+    }
+}
+/** How long, in milliseconds, a typeahead query lasts after the last key before it starts afresh. */
+export const MENU_TYPEAHEAD_RESET_MS = 500;
+/**
+ * Typeahead: a printable key extends the query and focuses the first item
+ * whose text starts with it. A single letter, or one letter repeated, starts
+ * after the focused item so repeating it cycles through the matches; a longer
+ * query may match the focused item itself. Returns `null` for a key that is
+ * not a printable character (Space activates), which tells the caller to leave
+ * the event alone. The caller lapses the query after
+ * {@link MENU_TYPEAHEAD_RESET_MS}.
+ */
+export function menuTypeahead({ query, key, labels, active }) {
+    if (key.length !== 1 || key === " ")
+        return null;
+    const next = (query + key).toLowerCase();
+    const repeated = [...next].every((char) => char === next[0]);
+    const search = repeated ? next[0] : next;
+    const start = Math.max(active, 0) + (search.length === 1 ? 1 : 0);
+    for (let i = 0; i < labels.length; i++) {
+        const index = (start + i) % labels.length;
+        if (labels[index].trim().toLowerCase().startsWith(search))
+            return { query: next, focus: index };
+    }
+    return { query: next, focus: null };
+}

package/dist/placement/placement.d.ts

@@ -0,0 +1,25 @@
+/** A box's edges in viewport coordinates, as `getBoundingClientRect()` gives them. */
+export type PlacementBox = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** Where an anchored panel landed. */
+export type PanelPlacement = {
+    /** The side of the anchor the panel is on. */
+    side: "top" | "right" | "bottom" | "left";
+    /**
+     * The third of the panel's facing edge that the anchor's centre is in:
+     * `left` / `center` / `right` on a top or bottom panel, `top` / `center` /
+     * `bottom` on a left or right one. An arrow placed there points at the anchor.
+     */
+    align: "left" | "center" | "right" | "top" | "bottom";
+};
+/**
+ * Where a panel positioned against an anchor actually landed — after the
+ * browser's `position-try-fallbacks` have had their say, so a host can point
+ * an arrow at the anchor whichever way the panel flipped. The side is the one
+ * the panel stands furthest out on.
+ */
+export declare function panelPlacement(panel: PlacementBox, anchor: PlacementBox): PanelPlacement;

package/dist/placement/placement.js

@@ -0,0 +1,22 @@
+/**
+ * Where a panel positioned against an anchor actually landed — after the
+ * browser's `position-try-fallbacks` have had their say, so a host can point
+ * an arrow at the anchor whichever way the panel flipped. The side is the one
+ * the panel stands furthest out on.
+ */
+export function panelPlacement(panel, anchor) {
+    const out = {
+        top: anchor.top - panel.bottom,
+        bottom: panel.top - anchor.bottom,
+        left: anchor.left - panel.right,
+        right: panel.left - anchor.right,
+    };
+    const side = Object.keys(out).reduce((best, key) => (out[key] > out[best] ? key : best));
+    const vertical = side === "top" || side === "bottom";
+    const [start, end, centre] = vertical
+        ? [panel.left, panel.right, (anchor.left + anchor.right) / 2]
+        : [panel.top, panel.bottom, (anchor.top + anchor.bottom) / 2];
+    const third = (centre - start) / (end - start);
+    const align = third < 1 / 3 ? (vertical ? "left" : "top") : third > 2 / 3 ? (vertical ? "right" : "bottom") : "center";
+    return { side, align };
+}

package/dist/tooltip/policy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How long the pointer has, after leaving a tooltip's trigger, to cross onto
+ * the tooltip itself before it closes — so hoverable content can be reached.
+ */
+export declare const TOOLTIP_GRACE_MS: number;
+/** What the open delay depends on. */
+export type TooltipDelayState = {
+    /** Whether a tooltip in the same group closed within the group's skip-delay window. */
+    groupOpen: boolean;
+    /** The delay before opening on hover, in milliseconds. */
+    delay: number;
+};
+/**
+ * The delay before a hovered tooltip opens: its own delay, or none while the
+ * group is still in its skip-delay window — so moving along a row of triggers
+ * opens each next tooltip at once rather than waiting every time.
+ */
+export declare function tooltipOpenDelay({ groupOpen, delay }: TooltipDelayState): number;

package/dist/tooltip/policy.js

@@ -0,0 +1,13 @@
+/**
+ * How long the pointer has, after leaving a tooltip's trigger, to cross onto
+ * the tooltip itself before it closes — so hoverable content can be reached.
+ */
+export const TOOLTIP_GRACE_MS = 100;
+/**
+ * The delay before a hovered tooltip opens: its own delay, or none while the
+ * group is still in its skip-delay window — so moving along a row of triggers
+ * opens each next tooltip at once rather than waiting every time.
+ */
+export function tooltipOpenDelay({ groupOpen, delay }) {
+    return groupOpen ? 0 : delay;
+}

package/package.json

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