@hypen-space/web 0.4.980 → 0.5.3

package/src/dom/route-focus.ts

@@ -0,0 +1,98 @@
+/**
+ * Route-change focus management.
+ *
+ * When the Router swaps routes, keyboard and screen-reader focus is left on
+ * an element that just left the document — the user is stranded and AT
+ * announces nothing. This module defines the focus contract for navigation
+ * (design Open Question #4) and the DOM renderer applies it after each patch
+ * batch:
+ *
+ * 1. A batch is a **navigation** when it contains at least one `detach` (the
+ *    leaving route, unlinked but kept alive by the Router cache) and at least
+ *    one incoming subtree root (an `attach` of a cached route, or a fresh
+ *    `create`+`insert` route build).
+ * 2. On navigation, focus moves to — in order of preference:
+ *    a. the element that held focus when the incoming subtree was detached
+ *       (**focus restore** on cached re-entry), if it is still inside the
+ *       subtree;
+ *    b. the subtree's first heading (`h1`–`h6` / `role="heading"`) or `main`
+ *       landmark — the "start of the new page" for AT users;
+ *    c. the subtree root itself.
+ *    Non-natively-focusable targets get `tabindex="-1"` (programmatic focus
+ *    only — they do not join the Tab order).
+ * 3. Focus-restore memory is keyed by the detached subtree's root NodeId and
+ *    is dropped the moment a `remove` arrives for that id (Router LRU
+ *    eviction) — **focus restore never targets an evicted NodeId**, the
+ *    invariant this contract exists to guarantee.
+ *
+ * The contract is opt-out: `DOMRendererOptions.routeFocus: "off"` disables it
+ * for apps that own focus management themselves.
+ */
+
+/** Tags that are natively focusable without a tabindex. */
+const NATIVELY_FOCUSABLE = new Set(["A", "BUTTON", "INPUT", "TEXTAREA", "SELECT"]);
+
+/** Heading hosts (`<h1>`–`<h6>`). */
+const HEADING_TAGS = new Set(["H1", "H2", "H3", "H4", "H5", "H6"]);
+
+type ElementLike = {
+  tagName?: string;
+  children?: ArrayLike<unknown>;
+  getAttribute?(name: string): string | null;
+};
+
+const matches = (el: ElementLike, pred: (el: ElementLike) => boolean): boolean => {
+  try {
+    return pred(el);
+  } catch {
+    return false;
+  }
+};
+
+const isHeading = (el: ElementLike): boolean =>
+  HEADING_TAGS.has(el.tagName?.toUpperCase() ?? "") ||
+  el.getAttribute?.("role") === "heading";
+
+const isMain = (el: ElementLike): boolean =>
+  el.tagName?.toUpperCase() === "MAIN" || el.getAttribute?.("role") === "main";
+
+/**
+ * Depth-first search over `children` (works on both real DOM collections and
+ * test-double arrays) for the first element matching `pred`.
+ */
+function findFirst(root: ElementLike, pred: (el: ElementLike) => boolean): ElementLike | null {
+  const children = Array.from((root.children ?? []) as ArrayLike<ElementLike>);
+  for (const child of children) {
+    if (matches(child, pred)) return child;
+    const nested = findFirst(child, pred);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+/**
+ * Pick the element that should receive focus inside a freshly-shown route
+ * subtree: first heading, else first `main` landmark, else the root itself.
+ */
+export function findRouteFocusTarget(root: HTMLElement): HTMLElement {
+  const heading = findFirst(root as ElementLike, isHeading);
+  if (heading) return heading as HTMLElement;
+  const main = findFirst(root as ElementLike, isMain);
+  if (main) return main as HTMLElement;
+  return root;
+}
+
+/**
+ * Move focus to `target`, granting it programmatic focusability
+ * (`tabindex="-1"`) when it is neither natively focusable nor already
+ * carrying a tabindex. `-1` keeps it out of the Tab order — this is a
+ * navigation landing point, not a new tab stop.
+ */
+export function focusRouteTarget(target: HTMLElement): void {
+  const tag = target.tagName?.toUpperCase() ?? "";
+  const hasTabindex = target.getAttribute?.("tabindex") != null;
+  if (!NATIVELY_FOCUSABLE.has(tag) && !hasTabindex) {
+    target.setAttribute?.("tabindex", "-1");
+  }
+  target.focus?.();
+}

package/src/dom/semantics.ts

@@ -0,0 +1,199 @@
+/**
+ * Accessibility semantics → DOM.
+ *
+ * The engine derives a platform-neutral {@link Semantics} block (role, heading
+ * level, busy, and in later phases name/state/hidden/…) and ships it on
+ * `create` patches. This module is the DOM translation: it maps that block
+ * onto ARIA / native HTML.
+ *
+ * Guiding rule: **let native HTML do the work; never emit a redundant or
+ * misplaced role.** Most Hypen components render a semantic native element
+ * whose tag already conveys the correct role (`<button>`, `<a>`, `<p>`,
+ * `<img>`, `<input>`, `<select>`, `<textarea>`, `<h1>`–`<h6>`). Some render a
+ * wrapper around the real control (`Checkbox`/`Switch` are a `<label>` around a
+ * nested `<input>`), where putting the role on the wrapper would be flat wrong.
+ *
+ * So we only apply an explicit `role` when the host is a *generic* container
+ * (`<div>`/`<span>`) that conveys nothing on its own — which is exactly the
+ * handful of cases that need it (`Spinner`, `ProgressBar`). Everywhere else the
+ * native element is already correct, and the {@link Semantics} block still
+ * travels to the non-DOM renderers (Canvas shadow, iOS, Android) that lack
+ * native semantics.
+ */
+
+import type { Semantics } from "@hypen-space/core/types";
+
+/**
+ * The implicit ARIA role each native host tag already conveys. An engine
+ * role equal to the implicit one is never applied (redundant-role smell:
+ * `role="button"` on `<button>`), but a *different* engine role is an
+ * intentional override and IS applied — `role="tab"` on a `<button>` host,
+ * `role="combobox"` on an `<input>` (the ARIA 1.2 combobox pattern).
+ *
+ * `LABEL` is special-cased below: it never takes a role at all, because
+ * Checkbox/Switch render a `<label>` *wrapper* whose role belongs to the
+ * nested `<input>` — putting it on the wrapper would be flat wrong.
+ */
+const IMPLICIT_ROLE: Record<string, string> = {
+  A: "link",
+  P: "paragraph",
+  IMG: "img",
+  INPUT: "textbox",
+  TEXTAREA: "textbox",
+  SELECT: "listbox",
+  BUTTON: "button",
+  H1: "heading",
+  H2: "heading",
+  H3: "heading",
+  H4: "heading",
+  H5: "heading",
+  H6: "heading",
+};
+
+/**
+ * Attributes this module set on an element on its previous pass, so a
+ * re-apply (a reactive `setSemantics` patch) can clear exactly what it — and
+ * only it — owns. Tracking per element instead of blanket-removing every
+ * possible ARIA attribute keeps the `.aria()` escape hatch's attributes (and
+ * anything else outside this module) untouched.
+ */
+const appliedAttrs = new WeakMap<HTMLElement, string[]>();
+
+/**
+ * Apply derived accessibility semantics to a DOM element.
+ *
+ * Called at create (first paint) and again on every `setSemantics` patch
+ * with the node's complete re-resolved block. Idempotent, and **clearing**:
+ * an attribute this module set on a previous pass that the new block no
+ * longer produces is removed (a name reverting from explicit to derived
+ * must drop its stale `aria-label`, a cleared `.expanded` its
+ * `aria-expanded`). No-op when `semantics` was never present, so
+ * non-semantic nodes pay nothing.
+ */
+export function applySemantics(element: HTMLElement, semantics?: Semantics): void {
+  if (!semantics && !appliedAttrs.has(element)) return;
+
+  // Everything this pass wants set, collected first so the diff against the
+  // previous pass is a plain list comparison.
+  const next: Array<[string, string]> = [];
+
+  if (semantics) {
+    if (semantics.hidden) {
+      // Decorative: remove from the accessibility tree entirely. Nothing
+      // else applies once hidden.
+      next.push(["aria-hidden", "true"]);
+    } else {
+      // tagName is uppercase in real DOM; normalize so the lookup is robust
+      // against test doubles that preserve the as-created case.
+      const tag = element.tagName?.toUpperCase();
+
+      if (
+        semantics.role &&
+        tag !== "LABEL" &&
+        IMPLICIT_ROLE[tag] !== semantics.role
+      ) {
+        // Applied when the host conveys nothing (div/span) or when the
+        // engine role intentionally overrides the tag's implicit role
+        // (`role="tab"` on a <button>). Skipped when redundant, and always
+        // skipped on <label> wrappers (the role belongs to the nested input).
+        next.push(["role", semantics.role]);
+      }
+
+      // An explicit author label overrides visible content, so it is applied
+      // as aria-label even on native elements. A *derived* name is
+      // deliberately not applied — the browser already exposes it from the
+      // visible content.
+      if (semantics.nameExplicit && semantics.name) {
+        next.push(["aria-label", semantics.name]);
+      }
+
+      if (semantics.description) {
+        next.push(["aria-description", semantics.description]);
+      }
+
+      // Self-state relationship attributes.
+      if (semantics.expanded !== undefined) {
+        next.push(["aria-expanded", String(semantics.expanded)]);
+      }
+      if (semantics.pressed !== undefined) {
+        next.push(["aria-pressed", String(semantics.pressed)]);
+      }
+      if (semantics.selected !== undefined) {
+        next.push(["aria-selected", String(semantics.selected)]);
+      }
+      if (semantics.current) {
+        next.push(["aria-current", semantics.current]);
+      }
+      if (semantics.checked !== undefined) {
+        next.push(["aria-checked", String(semantics.checked)]);
+      }
+      if (semantics.invalid !== undefined) {
+        // Reactive form validity — kept live via `setSemantics` re-emits;
+        // clearing (block drops the field) removes the attribute below.
+        next.push(["aria-invalid", String(semantics.invalid)]);
+      }
+
+      // Cross-node relationships by author-supplied id. DOM-only /
+      // web-leaning: these id-reference relationships have no equivalent in
+      // the string-hint native accessibility APIs, so they do not travel to
+      // Canvas / iOS / Android. See the guide's "Platform support" section
+      // (hypen-docs/content/docs/guide/accessibility.mdx).
+      if (semantics.id) {
+        // The anchor the references below resolve against — a real DOM id.
+        next.push(["id", semantics.id]);
+      }
+      if (semantics.dir) {
+        // Base text direction → the native HTML dir attribute (not ARIA).
+        // Managed like `id`: cleared when a later block drops it.
+        next.push(["dir", semantics.dir]);
+      }
+      if (semantics.controls) {
+        next.push(["aria-controls", semantics.controls]);
+      }
+      if (semantics.describedby) {
+        next.push(["aria-describedby", semantics.describedby]);
+      }
+      if (semantics.labelledby) {
+        next.push(["aria-labelledby", semantics.labelledby]);
+      }
+      if (semantics.activeDescendant) {
+        // Reactive roving-focus pointer — arrives initially on `create` and
+        // stays live via `setSemantics` re-emits as the bound state changes.
+        next.push(["aria-activedescendant", semantics.activeDescendant]);
+      }
+      if (semantics.owns) {
+        next.push(["aria-owns", semantics.owns]);
+      }
+
+      if (semantics.busy) {
+        next.push(["aria-busy", "true"]);
+      }
+
+      if (semantics.live) {
+        // Live-region politeness — engine-validated ("polite" | "assertive").
+        next.push(["aria-live", semantics.live]);
+      }
+    }
+  }
+
+  // Clear what the previous pass set but this one doesn't.
+  const previous = appliedAttrs.get(element);
+  if (previous) {
+    const keep = new Set(next.map(([name]) => name));
+    for (const name of previous) {
+      if (!keep.has(name)) {
+        element.removeAttribute(name);
+      }
+    }
+  }
+
+  for (const [name, value] of next) {
+    element.setAttribute(name, value);
+  }
+
+  if (next.length > 0) {
+    appliedAttrs.set(element, next.map(([name]) => name));
+  } else {
+    appliedAttrs.delete(element);
+  }
+}

package/src/variants.ts

@@ -0,0 +1,249 @@
+/**
+ * Shared variant (responsive breakpoint + interaction state) support.
+ *
+ * The engine emits applicator props using the canonical key format:
+ *
+ *   <camelBase><variant?><argSuffix>
+ *
+ *   - camelBase:  camelCase applicator name, e.g. "padding", "backgroundColor"
+ *   - variant?:   "@<bp>" and/or ":<state>", in that order if combined.
+ *                   bp    in { sm, md, lg, xl, 2xl }
+ *                   state in { hover, focus, active, disabled,
+ *                              focus-visible, focus-within }
+ *                 combined example: "backgroundColor@md:hover" (BOTH md AND hover)
+ *   - argSuffix:  ".<index>" (almost always ".0") or ".<name>" for named args.
+ *
+ * Examples emitted by the engine:
+ *   "padding.0", "padding@md.0", "backgroundColor:hover.0",
+ *   "backgroundColor@md:hover.0".
+ *
+ * IMPORTANT: the variant marker sits BETWEEN the base name and the ".0" arg
+ * suffix. A lookup that forgets the ".0" (e.g. building just "padding@md")
+ * MISSES the real key. Always parse the variant out of the full key.
+ *
+ * Both the DOM applicator path and the Canvas renderer import this module so
+ * breakpoint pixels, state names, and precedence stay byte-compatible across
+ * renderers. The DOM renderer leans on the CSS engine for actual resolution
+ * (media queries + pseudo-classes), so it only needs PARSE_* here; Canvas does
+ * its own paint/layout and therefore also uses the runtime resolver.
+ */
+
+/**
+ * Tailwind breakpoint min-widths (px). Order matters: ascending min-width.
+ * Mirrors the DOM `BREAKPOINTS` table and the iOS reference.
+ */
+export const BREAKPOINTS: Record<string, number> = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+};
+
+/** Breakpoint names in ascending min-width order (sm < md < lg < xl < 2xl). */
+export const BREAKPOINT_ORDER: readonly string[] = ["sm", "md", "lg", "xl", "2xl"];
+
+/** Interaction-state names recognised in variant keys (same set as the DOM). */
+export const VALID_STATES: readonly string[] = [
+  "hover",
+  "focus",
+  "active",
+  "disabled",
+  "focus-visible",
+  "focus-within",
+];
+const VALID_STATE_SET = new Set(VALID_STATES);
+
+/** Parsed shape of a single prop key. */
+export interface ParsedVariantKey {
+  /** camelCase base applicator name, e.g. "backgroundColor". */
+  base: string;
+  /** Breakpoint name (sm/md/lg/xl/2xl) or null if none. */
+  breakpoint: string | null;
+  /** Interaction state name or null if none. */
+  state: string | null;
+  /** Arg suffix without the leading dot (e.g. "0", "to"), or null if none. */
+  arg: string | null;
+}
+
+/**
+ * Parse a prop key into `{ base, breakpoint, state, arg }`.
+ *
+ * Splits the arg suffix first (the LAST `.<token>`), then peels the variant
+ * markers (`@bp` and/or `:state`) off the remainder. An unknown breakpoint or
+ * state is left as part of the base name (caller decides what to do); this
+ * matches the DOM behaviour where an invalid `@invalid` / `:invalid` simply
+ * never matches a real variant.
+ *
+ * Examples:
+ *   "padding.0"                  -> { base:"padding", breakpoint:null, state:null, arg:"0" }
+ *   "padding@md.0"               -> { base:"padding", breakpoint:"md", state:null, arg:"0" }
+ *   "backgroundColor:hover.0"    -> { base:"backgroundColor", breakpoint:null, state:"hover", arg:"0" }
+ *   "backgroundColor@md:hover.0" -> { base:"backgroundColor", breakpoint:"md", state:"hover", arg:"0" }
+ *   "backgroundColor@md:hover"   -> { base:"backgroundColor", breakpoint:"md", state:"hover", arg:null }
+ */
+export function parseVariantKey(key: string): ParsedVariantKey {
+  let work = key;
+  let arg: string | null = null;
+
+  // Peel the arg suffix: the segment after the LAST dot, but only if that dot
+  // comes AFTER any variant markers (so we never split inside "focus-within"
+  // — that has no dot — and never treat "padding" alone as having an arg).
+  const lastDot = work.lastIndexOf(".");
+  if (lastDot > 0) {
+    arg = work.slice(lastDot + 1);
+    work = work.slice(0, lastDot);
+  }
+
+  // Peel the state marker (":state") off the end of the remainder.
+  let state: string | null = null;
+  const colon = work.indexOf(":");
+  if (colon !== -1) {
+    const candidate = work.slice(colon + 1);
+    if (VALID_STATE_SET.has(candidate)) {
+      state = candidate;
+      work = work.slice(0, colon);
+    }
+  }
+
+  // Peel the breakpoint marker ("@bp").
+  let breakpoint: string | null = null;
+  const at = work.indexOf("@");
+  if (at !== -1) {
+    const candidate = work.slice(at + 1);
+    if (candidate in BREAKPOINTS) {
+      breakpoint = candidate;
+      work = work.slice(0, at);
+    }
+  }
+
+  return { base: work, breakpoint, state, arg };
+}
+
+/** The set of interaction states currently active on a node. */
+export interface ActiveStates {
+  hover?: boolean;
+  focus?: boolean;
+  active?: boolean;
+  disabled?: boolean;
+  "focus-visible"?: boolean;
+  "focus-within"?: boolean;
+}
+
+/**
+ * Precedence rank for a parsed variant (higher wins). Combines the breakpoint
+ * tier and the state tier into a single sortable number.
+ *
+ * Precedence (low -> high), later overrides earlier:
+ *   base
+ *     < breakpoints ascending (sm < md < lg < xl < 2xl)
+ *     < disabled < hover < focus < active
+ *
+ * State always outranks any breakpoint (a `:hover` override beats a `@2xl`
+ * sizing override on the same prop), matching the iOS reference where state
+ * overrides are merged AFTER the responsive base. Within the same state tier,
+ * a higher breakpoint still breaks the tie so `@md:hover` beats `:hover`.
+ */
+const STATE_RANK: Record<string, number> = {
+  disabled: 1,
+  hover: 2,
+  // focus-visible / focus-within are focus-flavoured states: they share the
+  // `focus` precedence slot (NOT base/0) so they outrank hover and lose to
+  // active, matching the engine's `state_rank` in portable/variant.rs.
+  focus: 3,
+  "focus-visible": 3,
+  "focus-within": 3,
+  active: 4,
+};
+
+// State tier must be weighted by a value strictly greater than the largest
+// possible breakpoint tier so the bp tiebreak can never leak across state
+// bands (mirrors the engine's STATE_STEP > max-breakpoint invariant). Derived
+// from BREAKPOINT_ORDER.length so adding breakpoints can't silently break it.
+const STATE_WEIGHT = BREAKPOINT_ORDER.length + 1;
+
+function variantRank(breakpoint: string | null, state: string | null): number {
+  const bpTier = breakpoint ? BREAKPOINT_ORDER.indexOf(breakpoint) + 1 : 0; // 0..len
+  const stateTier = state ? STATE_RANK[state] ?? 0 : 0; // 0..4
+  // State tier dominates; breakpoint tier breaks ties within a state tier.
+  return stateTier * STATE_WEIGHT + bpTier;
+}
+
+/**
+ * Is a parsed variant currently applicable, given the viewport width and the
+ * active interaction states? A combined key requires BOTH conditions.
+ */
+function variantApplies(
+  parsed: ParsedVariantKey,
+  width: number,
+  states: ActiveStates,
+): boolean {
+  if (parsed.breakpoint) {
+    const minWidth = BREAKPOINTS[parsed.breakpoint];
+    if (minWidth === undefined || width < minWidth) return false;
+  }
+  if (parsed.state) {
+    if (!states[parsed.state as keyof ActiveStates]) return false;
+  }
+  return true;
+}
+
+/**
+ * Resolve variant-bearing props against the current viewport width and active
+ * interaction states, producing a flat map of `base -> winning value`.
+ *
+ * Input keys are the already-normalised flat applicator keys (variant markers
+ * present, arg suffix already stripped by the applicator-grouping pass), e.g.
+ * `{ padding: 8, "padding@md": 16, "backgroundColor:hover": "red" }`.
+ *
+ * Only bases that actually have at least one applicable variant appear in the
+ * result with an overridden value; a base with only its plain entry resolves to
+ * that plain value. The caller merges the result over the node's base props.
+ */
+export function resolveVariantProps(
+  props: Record<string, unknown>,
+  width: number,
+  states: ActiveStates,
+): Record<string, unknown> {
+  // base -> { value, rank }
+  const winners = new Map<string, { value: unknown; rank: number }>();
+
+  for (const key of Object.keys(props)) {
+    const parsed = parseVariantKey(key);
+    // Only consider entries that carry a variant marker. Plain keys (no bp/state)
+    // are the base and are handled implicitly via rank 0 below so a base with a
+    // single applicable variant still falls back to base when the variant is off.
+    if (!parsed.breakpoint && !parsed.state) {
+      // Seed the base value at rank 0 so variant lookups have a fallback and so
+      // a base that ALSO has variants resolves correctly when none apply.
+      const existing = winners.get(parsed.base);
+      if (!existing || existing.rank === 0) {
+        winners.set(parsed.base, { value: props[key], rank: 0 });
+      }
+      continue;
+    }
+
+    if (!variantApplies(parsed, width, states)) continue;
+
+    const rank = variantRank(parsed.breakpoint, parsed.state);
+    const existing = winners.get(parsed.base);
+    if (!existing || rank >= existing.rank) {
+      winners.set(parsed.base, { value: props[key], rank });
+    }
+  }
+
+  const out: Record<string, unknown> = {};
+  for (const [base, win] of winners) {
+    out[base] = win.value;
+  }
+  return out;
+}
+
+/** True if any key in `props` carries a variant marker (`@bp` or `:state`). */
+export function hasVariantProps(props: Record<string, unknown>): boolean {
+  for (const key of Object.keys(props)) {
+    const parsed = parseVariantKey(key);
+    if (parsed.breakpoint || parsed.state) return true;
+  }
+  return false;
+}

package/dist/canvas/input.d.ts

@@ -1,76 +0,0 @@
-/**
- * Input Overlay System
- *
- * Handle text input using DOM overlay elements
- */
-import type { VirtualNode } from "./types.js";
-/** Minimal engine interface for dispatching bind actions */
-interface BindEngine {
-    dispatchAction(name: string, payload?: unknown): void;
-}
-/**
- * Input Overlay Manager
- */
-export declare class InputOverlay {
-    private container;
-    private overlay;
-    private focusedNode;
-    private onChangeCallback;
-    private bindPath;
-    private engine;
-    constructor(container: HTMLElement | null);
-    /**
-     * Show input overlay for a node.
-     *
-     * Type comparison is case-insensitive — the engine emits `"Input"` /
-     * `"Textarea"`, but the overlay branch was looking for lowercase
-     * `"textarea"` and always created an `<input>` (so multi-line typing
-     * couldn't enter newlines and the visible caret was the wrong height).
-     */
-    showInput(node: VirtualNode, canvasBounds: DOMRect, onChange: (value: string) => void, engine?: BindEngine | null): void;
-    /**
-     * Hide input overlay
-     */
-    hideInput(): void;
-    /**
-     * Update overlay position
-     */
-    updatePosition(node: VirtualNode, canvasBounds: DOMRect): void;
-    /**
-     * Style overlay to match canvas node
-     */
-    private styleOverlay;
-    /**
-     * Position overlay over canvas node.
-     *
-     * `bounds` is in canvas-local CSS pixels (the layout coordinate space
-     * the renderer paints into after `ctx.scale(dpr, dpr)`). The overlay is
-     * mounted on `document.body`, so we add `canvasBounds.left/top`
-     * (page coords from `getBoundingClientRect`) to land at the right
-     * absolute position regardless of where the canvas sits on the page.
-     * Adding `window.scrollX/Y` keeps the overlay pinned to the canvas
-     * even when the page scrolls between focus and reposition.
-     */
-    private positionOverlay;
-    /**
-     * Handle input event
-     */
-    private onInput;
-    /**
-     * Handle blur event
-     */
-    private onBlur;
-    /**
-     * Handle keyboard events
-     */
-    private onKeyDown;
-    /**
-     * Check if input is currently shown
-     */
-    isShown(): boolean;
-    /**
-     * Get current focused node
-     */
-    getFocusedNode(): VirtualNode | null;
-}
-export {};