@stealthscale/component-a11y 0.1.0 → 0.1.3

package/dist/shared-UZQEmdYt.js

@@ -0,0 +1,584 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { n as recipe$1, r as recipe, t as recipe$2 } from "./recipes-BM8WGKWH.js";
+import { c } from "react/compiler-runtime";
+import { createContext, use, useEffect, useId, useRef, useState } from "react";
+import { useCallbackRef, useControllableState } from "@stealthscale/hooks";
+import { createRecipeContext, createSlotRecipeContext } from "@stealthscale/theme";
+import { jsx } from "react/jsx-runtime";
+//#region src/roving-focus/context.ts
+/**
+* Binds the roving-focus slot recipe to React.
+*
+* @remarks
+*   The binding is a separate module from the recipe, because the theme compiler imports the recipe
+*   at build time and must not load the React runtime. The root resolves the variants, and each
+*   item reads its slot class from the root's context.
+*/
+/**
+* Creates the roving-focus recipe's `withProvider` binding for the root and `withContext` for the
+* items.
+*/
+const { withContext: withContext$1, withProvider: withProvider$1 } = createSlotRecipeContext(recipe);
+//#endregion
+//#region src/roving-focus/use-roving-focus.ts
+/**
+* Implements a roving tabindex: Tab enters the group once, and the arrow keys move focus inside it.
+*
+* @remarks
+*   A toolbar, a tab list and a menu bar each take one stop in the page's tab order. Items register
+*   themselves, because the root cannot see through the components its children are composed
+*   from. Registration follows effect order, which differs from source order once an item renders
+*   conditionally, so the registry sorts by document position and the arrows follow the order on
+*   screen.
+*/
+/**
+* Maps each block-axis arrow key to its step.
+*/
+const DOWN_THE_PAGE = {
+	ArrowDown: 1,
+	ArrowUp: -1
+};
+/**
+* Maps each inline-axis arrow key to its step in a left-to-right group.
+*/
+const ALONG_THE_LINE = {
+	ArrowLeft: -1,
+	ArrowRight: 1
+};
+/**
+* Context that a root publishes its group on and every item below it reads.
+*/
+const RovingFocusContext = createContext(void 0);
+/**
+* Compares two registrations by document position, for sorting in on-screen order.
+*/
+function byDocumentPosition(first, second) {
+	return (first.element.compareDocumentPosition(second.element) & Node.DOCUMENT_POSITION_FOLLOWING) === 0 ? 1 : -1;
+}
+/**
+* Translates a key press into the movement it requests.
+*
+* @param key - The `key` value of the keyboard event.
+* @param orientation - The axes the group responds to.
+* @param forward - 1 in a left-to-right group and -1 in a right-to-left one, applied to the
+*   inline arrows only.
+* @returns The requested step or end, or undefined when the group does not handle the key.
+*/
+function intentOf(key, orientation, forward) {
+	if (key === "Home") return "start";
+	if (key === "End") return "end";
+	const block = DOWN_THE_PAGE[key];
+	if (block !== void 0) return orientation === "horizontal" ? void 0 : block;
+	const inline = ALONG_THE_LINE[key];
+	if (inline !== void 0) return orientation === "vertical" ? void 0 : inline * forward;
+}
+/**
+* Returns the destination item as the bounds of a one-item slice of the registration list.
+*
+* @remarks
+*   Slice bounds keep the caller free of a branch. An index is typed as possibly undefined even
+*   when it is in range, and slicing an empty list returns an empty list, so a group with no items
+*   needs no special case.
+* @param list - The registrations in document order.
+* @param intent - The step or end the key requested.
+* @param from - The identifier of the item with the tab stop.
+* @param wrap - Whether a step past one end continues at the other.
+* @returns The start and end bounds of a slice that contains the destination item.
+*/
+function spanOf(list, intent, from, wrap) {
+	const last = list.length - 1;
+	const at = list.findIndex((item) => item.id === from);
+	const here = at === -1 ? 0 : at;
+	const to = intent === "start" ? 0 : intent === "end" ? last : wrap ? (here + intent + list.length) % list.length : Math.min(last, Math.max(0, here + intent));
+	return [to, to + 1];
+}
+/**
+* Creates a registry backed by a ref.
+*
+* @remarks
+*   Rendering depends on the active identifier and not on the list, so a list in state would
+*   re-render the whole group each time an item mounted, with no visible change.
+*/
+function useRegistry() {
+	const $ = c(5);
+	let t0;
+	if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+		t0 = [];
+		$[0] = t0;
+	} else t0 = $[0];
+	const items = useRef(t0);
+	let t1;
+	if ($[1] === Symbol.for("react.memo_cache_sentinel")) {
+		t1 = (registration) => {
+			items.current = [...items.current, registration];
+		};
+		$[1] = t1;
+	} else t1 = $[1];
+	const add = t1;
+	let t2;
+	if ($[2] === Symbol.for("react.memo_cache_sentinel")) {
+		t2 = (node) => items.current.some((item) => item.element.contains(node));
+		$[2] = t2;
+	} else t2 = $[2];
+	const contains = t2;
+	let t3;
+	if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
+		t3 = () => items.current.toSorted(byDocumentPosition);
+		$[3] = t3;
+	} else t3 = $[3];
+	const ordered = t3;
+	let t4;
+	if ($[4] === Symbol.for("react.memo_cache_sentinel")) {
+		const remove = (id) => {
+			items.current = items.current.filter((item_0) => item_0.id !== id);
+		};
+		t4 = {
+			add,
+			contains,
+			ordered,
+			remove
+		};
+		$[4] = t4;
+	} else t4 = $[4];
+	return t4;
+}
+/**
+* Tracks which item has the tab stop, and defers to the caller when the group is controlled.
+*/
+function useTabStop(props) {
+	const $ = c(12);
+	const { activeId: driven, defaultActiveId, onActiveIdChange } = props;
+	let t0;
+	if ($[0] !== defaultActiveId || $[1] !== driven || $[2] !== onActiveIdChange) {
+		t0 = {
+			defaultValue: defaultActiveId,
+			onChange: onActiveIdChange,
+			value: driven
+		};
+		$[0] = defaultActiveId;
+		$[1] = driven;
+		$[2] = onActiveIdChange;
+		$[3] = t0;
+	} else t0 = $[3];
+	const [activeId, setActiveId] = useControllableState(t0);
+	const stop = useRef(activeId);
+	let t1;
+	let t2;
+	if ($[4] !== activeId) {
+		t1 = () => {
+			stop.current = activeId;
+		};
+		t2 = [activeId];
+		$[4] = activeId;
+		$[5] = t1;
+		$[6] = t2;
+	} else {
+		t1 = $[5];
+		t2 = $[6];
+	}
+	useEffect(t1, t2);
+	let t3;
+	if ($[7] !== setActiveId) {
+		t3 = (next) => {
+			stop.current = next;
+			setActiveId(next);
+		};
+		$[7] = setActiveId;
+		$[8] = t3;
+	} else t3 = $[8];
+	const claim = useCallbackRef(t3);
+	let t4;
+	if ($[9] !== activeId || $[10] !== claim) {
+		t4 = {
+			activeId,
+			claim,
+			stop
+		};
+		$[9] = activeId;
+		$[10] = claim;
+		$[11] = t4;
+	} else t4 = $[11];
+	return t4;
+}
+/**
+* Moves one tab stop across the items that register with the group.
+*
+* @remarks
+*   The first item to register takes the stop, so Tab reaches the group from its first render.
+*   When the item with the stop unmounts, the stop passes to the first remaining item in document
+*   order, so the group stays in the tab order.
+* @returns The context value for the items and the key handler for the root.
+*/
+function useRovingFocus(props) {
+	const $ = c(22);
+	const { orientation, wrap } = props;
+	const { add, contains, ordered, remove } = useRegistry();
+	const { activeId, claim, stop } = useTabStop(props);
+	let t0;
+	if ($[0] !== add || $[1] !== claim || $[2] !== ordered || $[3] !== remove || $[4] !== stop.current) {
+		t0 = (registration) => {
+			add(registration);
+			if (stop.current === void 0) claim(registration.id);
+			return () => {
+				remove(registration.id);
+				if (stop.current === registration.id) claim(ordered()[0]?.id);
+			};
+		};
+		$[0] = add;
+		$[1] = claim;
+		$[2] = ordered;
+		$[3] = remove;
+		$[4] = stop.current;
+		$[5] = t0;
+	} else t0 = $[5];
+	const register = useCallbackRef(t0);
+	let t1;
+	if ($[6] !== claim || $[7] !== contains || $[8] !== ordered || $[9] !== orientation || $[10] !== stop.current || $[11] !== wrap) {
+		t1 = (event) => {
+			if (event.ctrlKey || event.metaKey || event.altKey) return;
+			const { target } = event;
+			if (!(target instanceof Node) || !contains(target)) return;
+			const rightToLeft = globalThis.getComputedStyle(event.currentTarget).direction === "rtl";
+			const intent = intentOf(event.key, orientation, rightToLeft ? -1 : 1);
+			if (intent === void 0) return;
+			for (const moving of ordered().slice(...spanOf(ordered(), intent, stop.current, wrap))) {
+				claim(moving.id);
+				moving.element.focus();
+			}
+			event.preventDefault();
+		};
+		$[6] = claim;
+		$[7] = contains;
+		$[8] = ordered;
+		$[9] = orientation;
+		$[10] = stop.current;
+		$[11] = wrap;
+		$[12] = t1;
+	} else t1 = $[12];
+	const onKeyDown = useCallbackRef(t1);
+	let t2;
+	if ($[13] !== claim) {
+		t2 = (id) => {
+			claim(id);
+		};
+		$[13] = claim;
+		$[14] = t2;
+	} else t2 = $[14];
+	const onFocus = useCallbackRef(t2);
+	let t3;
+	if ($[15] !== activeId || $[16] !== onFocus || $[17] !== register) {
+		t3 = {
+			activeId,
+			onFocus,
+			register
+		};
+		$[15] = activeId;
+		$[16] = onFocus;
+		$[17] = register;
+		$[18] = t3;
+	} else t3 = $[18];
+	const t4 = t3;
+	let t5;
+	if ($[19] !== onKeyDown || $[20] !== t4) {
+		t5 = {
+			group: t4,
+			onKeyDown
+		};
+		$[19] = onKeyDown;
+		$[20] = t4;
+		$[21] = t5;
+	} else t5 = $[21];
+	return t5;
+}
+//#endregion
+//#region src/roving-focus/item.tsx
+/**
+* Renders one item of a roving focus group.
+*
+* @remarks
+*   One item has `tabIndex` 0 and every other has -1, so the group is one stop in the tab order. A
+*   disabled item does not register, so the arrows step past it. It also refuses the stop when a
+*   pointer focuses it, because a stop on an unregistered item is unreachable by the arrows and
+*   removes the group from the tab order. The element is in state and not in a ref, so the
+*   registering effect runs again once the node exists. The group keys on the registration, so
+*   the item writes the DOM `id` only when the caller passes one, and a control rendered as an item
+*   keeps an id it needs, such as the one a menu trigger references. The item with the stop has
+*   `data-stop` and not `data-active`, because the theme styles `[data-active]` as a pressed
+*   control.
+*/
+/**
+* Renders a `div` element with the item slot's classes.
+*/
+const Shell$1 = withContext$1("div", "item");
+/**
+* Renders an item with `tabIndex` 0 while it has the tab stop and -1 otherwise.
+*
+* @throws {@link Error} When rendered outside a root.
+*/
+function Item(props) {
+	const $ = c(26);
+	let handed;
+	let named;
+	let rest;
+	let t0;
+	if ($[0] !== props) {
+		({disabled: t0, id: named, ref: handed, ...rest} = props);
+		$[0] = props;
+		$[1] = handed;
+		$[2] = named;
+		$[3] = rest;
+		$[4] = t0;
+	} else {
+		handed = $[1];
+		named = $[2];
+		rest = $[3];
+		t0 = $[4];
+	}
+	const disabled = t0 === void 0 ? false : t0;
+	const group = use(RovingFocusContext);
+	if (group === void 0) throw new Error("RovingFocus.Item must be rendered inside RovingFocus.Root.");
+	const generated = useId();
+	const id = named ?? generated;
+	const { activeId, onFocus, register } = group;
+	const [element, setElement] = useState(null);
+	let t1;
+	if ($[5] !== handed) {
+		t1 = (node) => {
+			setElement(node);
+			if (typeof handed === "function") handed(node);
+			else if (handed !== null && handed !== void 0) handed.current = node;
+		};
+		$[5] = handed;
+		$[6] = t1;
+	} else t1 = $[6];
+	const attach = useCallbackRef(t1);
+	let t2;
+	if ($[7] !== disabled || $[8] !== id || $[9] !== onFocus) {
+		t2 = () => {
+			if (!disabled) onFocus(id);
+		};
+		$[7] = disabled;
+		$[8] = id;
+		$[9] = onFocus;
+		$[10] = t2;
+	} else t2 = $[10];
+	const claim = useCallbackRef(t2);
+	let t3;
+	let t4;
+	if ($[11] !== disabled || $[12] !== element || $[13] !== id || $[14] !== register) {
+		t3 = () => {
+			if (element === null || disabled) return;
+			return register({
+				element,
+				id
+			});
+		};
+		t4 = [
+			disabled,
+			element,
+			id,
+			register
+		];
+		$[11] = disabled;
+		$[12] = element;
+		$[13] = id;
+		$[14] = register;
+		$[15] = t3;
+		$[16] = t4;
+	} else {
+		t3 = $[15];
+		t4 = $[16];
+	}
+	useEffect(t3, t4);
+	const t5 = disabled || void 0;
+	const t6 = disabled ? "" : void 0;
+	const t7 = activeId === id ? "" : void 0;
+	const t8 = !disabled && activeId === id ? 0 : -1;
+	let t9;
+	if ($[17] !== attach || $[18] !== claim || $[19] !== named || $[20] !== rest || $[21] !== t5 || $[22] !== t6 || $[23] !== t7 || $[24] !== t8) {
+		t9 = /* @__PURE__ */ jsx(Shell$1, {
+			"aria-disabled": t5,
+			"data-disabled": t6,
+			"data-stop": t7,
+			id: named,
+			onFocus: claim,
+			ref: attach,
+			tabIndex: t8,
+			...rest
+		});
+		$[17] = attach;
+		$[18] = claim;
+		$[19] = named;
+		$[20] = rest;
+		$[21] = t5;
+		$[22] = t6;
+		$[23] = t7;
+		$[24] = t8;
+		$[25] = t9;
+	} else t9 = $[25];
+	return t9;
+}
+//#endregion
+//#region src/roving-focus/root.tsx
+/**
+* Renders a `div` element with the root slot's classes.
+*/
+const Shell = withProvider$1("div", "root");
+/**
+* Keeps one tab stop for the items below it and moves the stop on the arrow keys.
+*/
+function Root(props) {
+	const $ = c(26);
+	let activeId;
+	let children;
+	let defaultActiveId;
+	let onActiveIdChange;
+	let rest;
+	let t0;
+	let t1;
+	if ($[0] !== props) {
+		({activeId, children, defaultActiveId, onActiveIdChange, orientation: t0, wrap: t1, ...rest} = props);
+		$[0] = props;
+		$[1] = activeId;
+		$[2] = children;
+		$[3] = defaultActiveId;
+		$[4] = onActiveIdChange;
+		$[5] = rest;
+		$[6] = t0;
+		$[7] = t1;
+	} else {
+		activeId = $[1];
+		children = $[2];
+		defaultActiveId = $[3];
+		onActiveIdChange = $[4];
+		rest = $[5];
+		t0 = $[6];
+		t1 = $[7];
+	}
+	const orientation = t0 === void 0 ? "horizontal" : t0;
+	const wrap = t1 === void 0 ? false : t1;
+	let t2;
+	if ($[8] !== activeId || $[9] !== defaultActiveId || $[10] !== onActiveIdChange || $[11] !== orientation || $[12] !== wrap) {
+		t2 = {
+			activeId,
+			defaultActiveId,
+			onActiveIdChange,
+			orientation,
+			wrap
+		};
+		$[8] = activeId;
+		$[9] = defaultActiveId;
+		$[10] = onActiveIdChange;
+		$[11] = orientation;
+		$[12] = wrap;
+		$[13] = t2;
+	} else t2 = $[13];
+	const { group, onKeyDown } = useRovingFocus(t2);
+	let t3;
+	if ($[14] !== orientation || $[15] !== rest.role) {
+		t3 = rest.role !== void 0 && orientation !== "both" ? { "aria-orientation": orientation } : void 0;
+		$[14] = orientation;
+		$[15] = rest.role;
+		$[16] = t3;
+	} else t3 = $[16];
+	const told = t3;
+	let t4;
+	if ($[17] !== children || $[18] !== onKeyDown || $[19] !== orientation || $[20] !== rest || $[21] !== told) {
+		t4 = /* @__PURE__ */ jsx(Shell, {
+			onKeyDown,
+			orientation,
+			...told,
+			...rest,
+			children
+		});
+		$[17] = children;
+		$[18] = onKeyDown;
+		$[19] = orientation;
+		$[20] = rest;
+		$[21] = told;
+		$[22] = t4;
+	} else t4 = $[22];
+	let t5;
+	if ($[23] !== group || $[24] !== t4) {
+		t5 = /* @__PURE__ */ jsx(RovingFocusContext, {
+			value: group,
+			children: t4
+		});
+		$[23] = group;
+		$[24] = t4;
+		$[25] = t5;
+	} else t5 = $[25];
+	return t5;
+}
+//#endregion
+//#region src/roving-focus/index.ts
+var roving_focus_exports = /* @__PURE__ */ __exportAll({
+	Item: () => Item,
+	Root: () => Root
+});
+//#endregion
+//#region src/skip-nav/context.ts
+/**
+* Binds the skip-nav slot recipe to React.
+*
+* @remarks
+*   The binding is a separate module from the recipe, because the theme compiler imports the recipe
+*   at build time and must not load the React runtime. The link and the target each use
+*   `withProvider`, because neither is rendered inside the other.
+*/
+/**
+* Creates the skip-nav recipe's `withProvider` binding.
+*/
+const { withProvider } = createSlotRecipeContext(recipe$1);
+//#endregion
+//#region src/skip-nav/link.ts
+/**
+* Fragment identifier that the link's `href` and the target's `id` default to.
+*/
+const SKIP_NAV_TARGET = "content";
+/**
+* Renders an `a` element with the link slot's classes, pointing at `#content` by default.
+*/
+const Link = withProvider("a", "link", { defaultProps: { href: `#${SKIP_NAV_TARGET}` } });
+//#endregion
+//#region src/skip-nav/target.ts
+/**
+* Renders a `div` element with the target slot's classes, `id="content"` and `tabIndex` -1 by
+* default.
+*/
+const Target = withProvider("div", "target", { defaultProps: {
+	id: SKIP_NAV_TARGET,
+	tabIndex: -1
+} });
+//#endregion
+//#region src/skip-nav/index.ts
+var skip_nav_exports = /* @__PURE__ */ __exportAll({
+	Link: () => Link,
+	SKIP_NAV_TARGET: () => SKIP_NAV_TARGET,
+	Target: () => Target
+});
+//#endregion
+//#region src/visually-hidden/context.ts
+/**
+* Binds the visually-hidden recipe to React.
+*
+* @remarks
+*   The binding is a separate module from the recipe, because the theme compiler imports the recipe
+*   at build time and must not load the React runtime.
+*/
+/**
+* Creates the visually-hidden recipe's `withContext` binding and its `PropsProvider`.
+*
+* @remarks
+*   `PropsProvider` sets variants on every element bound below it. The package exports it as
+*   `VisuallyHiddenPropsProvider`.
+*/
+const { PropsProvider, withContext } = createRecipeContext(recipe$2);
+//#endregion
+//#region src/visually-hidden/visually-hidden.ts
+/**
+* Renders a `span` element with the classes of the visually-hidden recipe.
+*/
+const VisuallyHidden = withContext("span");
+//#endregion
+export { Link as a, Item as c, Target as i, PropsProvider as n, roving_focus_exports as o, skip_nav_exports as r, Root as s, VisuallyHidden as t };

package/dist/theme.d.ts

@@ -1,11 +1,10 @@
 //#region src/theme.d.ts
 /**
- * Publishes the preset that registers every recipe in this package, for an application's compiler
- * to install.
+ * Declares the preset an application's compiler installs to pick up this package's recipes.
  *
  * @remarks
- *   The list is written by hand. The package's own specification reports a recipe file the list
- *   leaves out, so no generator runs here.
+ *   The list is maintained by hand. Nothing generates it, because the package's own specification
+ *   fails when a recipe file in `src/` is missing from the preset.
  */
 declare const _default: import("@stealthscale/theme/authoring").Preset;
 //#endregion

package/dist/theme.js

@@ -1,13 +1,12 @@
-import { n as recipe$2, r as recipe$1, t as recipe } from "./recipe-BKojQp6r.js";
+import { n as recipe$2, r as recipe$1, t as recipe } from "./recipes-BM8WGKWH.js";
 import { definePreset } from "@stealthscale/theme/authoring";
 //#region src/theme.ts
 /**
-* Publishes the preset that registers every recipe in this package, for an application's compiler
-* to install.
+* Declares the preset an application's compiler installs to pick up this package's recipes.
 *
 * @remarks
-*   The list is written by hand. The package's own specification reports a recipe file the list
-*   leaves out, so no generator runs here.
+*   The list is maintained by hand. Nothing generates it, because the package's own specification
+*   fails when a recipe file in `src/` is missing from the preset.
 */
 var theme_default = definePreset({
 	name: "@stealthscale/component-a11y",

package/locales/en/specimen/roving-focus.json

@@ -0,0 +1,35 @@
+{
+  "about": "Keeps one tab stop for a set of controls. Tab reaches the set, and the arrow keys move focus inside it.",
+  "bold": "Bold",
+  "both": {
+    "about": "Eight filters in a 320px room, wrapping onto three lines. With `orientation=\"both\"` every arrow key moves focus to the next or previous filter.",
+    "title": "Both"
+  },
+  "draw": "Draw",
+  "erase": "Erase",
+  "filters": "Filters",
+  "formatting": "Formatting",
+  "italic": "Italic",
+  "select": "Select",
+  "statuses": {
+    "disputed": "Disputed",
+    "draft": "Draft",
+    "overdue": "Overdue",
+    "paid": "Paid",
+    "pending": "Pending",
+    "refunded": "Refunded",
+    "scheduled": "Scheduled",
+    "void": "Void"
+  },
+  "title": "Roving focus",
+  "toolbar": {
+    "about": "A formatting toolbar with `wrap`. Tab reaches Bold, the item with the tab stop, and the second cell renders its focused state. ArrowRight moves to Italic, and on Underline it moves back to Bold.",
+    "title": "Toolbar"
+  },
+  "tools": "Tools",
+  "underline": "Underline",
+  "vertical": {
+    "about": "A vertical toolbar. ArrowDown and ArrowUp move focus, and ArrowLeft and ArrowRight reach the page.",
+    "title": "Vertical"
+  }
+}

package/locales/en/specimen/skip-nav.json

@@ -0,0 +1,14 @@
+{
+  "about": "Moves keyboard focus past a repeated block of content. `SkipNav.Link` is hidden until keyboard focus, and `SkipNav.Target` receives focus when the link is followed.",
+  "all": "All",
+  "filters": "Filters",
+  "overdue": "Overdue",
+  "pair": {
+    "about": "An invoice list whose skip link moves focus past the filters to the results. Press Tab into the scene: the link appears at the start corner of the list, and Enter moves focus to the results.",
+    "title": "Link and target"
+  },
+  "paid": "Paid",
+  "results": "24 invoices match the filters.",
+  "skip": "Skip to invoices",
+  "title": "Skip nav"
+}

package/locales/en/specimen/visually-hidden.json

@@ -0,0 +1,17 @@
+{
+  "about": "Renders content that a screen reader announces and the browser does not paint.",
+  "close": "Close",
+  "create": "New invoice",
+  "focusable": {
+    "about": "A page section whose first control, Keyboard shortcuts, is hidden until keyboard focus. Press Tab into the scene: `focusable` fixes the control to the start corner of the section.",
+    "title": "Focusable"
+  },
+  "invoices": "Invoices",
+  "name": {
+    "about": "An icon-only close button. The icon has `aria-hidden`, and the hidden text Close is the button's accessible name.",
+    "title": "Accessible name"
+  },
+  "shortcuts": "Keyboard shortcuts",
+  "summary": "24 invoices, 3 of them overdue.",
+  "title": "Visually hidden"
+}