@hypen-space/web 0.5.2 → 0.5.3

package/dist/canvas/accessibility.d.ts

@@ -3,27 +3,130 @@
  *
  * Maintain shadow DOM for screen readers
  */
+import type { Semantics } from "@hypen-space/core/types";
 import type { VirtualNode } from "./types.js";
 /**
- * Accessibility Manager
+ * Apply engine-derived accessibility semantics to a shadow-tree element.
+ *
+ * Unlike the DOM renderer, the canvas paints pixels — the accessible name is
+ * *not* otherwise exposed — so the derived name is applied directly as
+ * `aria-label` (whether derived or explicit). Roles are set only on generic
+ * hosts that don't convey them natively. `hidden` is handled by the caller
+ * (the node is omitted from the shadow tree entirely).
+ *
+ * Called at shadow-node create and again on every reactive `setSemantics`
+ * re-apply. Idempotent and clearing: attributes set on a previous pass that
+ * the new block no longer produces are removed.
+ */
+export declare function applyShadowSemantics(element: HTMLElement, semantics?: Semantics): void;
+/**
+ * Accessibility Mirror — positioned transparent semantics overlay
+ *
+ * A live DOM mirror of the virtual tree, rendered INVISIBLY over the canvas
+ * with every element absolutely positioned at its painted bounds (the
+ * Flutter-web / Google-Docs approach). Canvas *fallback content* was tried
+ * first and rejected on evidence: Chromium exposes fallback elements to the
+ * accessibility tree (names, roles, focus all work) but gives them ZERO
+ * geometry — and screen-reader browse modes (VoiceOver cursor, rotor, touch
+ * exploration) are geometry-driven, so they skip boundless elements. A
+ * rendered-but-transparent overlay gets real boxes, which makes browse mode
+ * work and puts native focus rings exactly over the painted controls.
+ *
+ * Real DOM focus on mirror elements is the single source of truth for
+ * `node.focused`; the overlay is `pointer-events: none` throughout so the
+ * canvas keeps all pointer interaction.
+ *
+ * The mirror is synced **incrementally** from the same patch stream that
+ * drives the canvas (`create/insert/move/remove/detach/attach/...`), so
+ * mirror elements keep their identity across re-renders — a screen reader's
+ * virtual cursor or a keyboard user's focus survives reactive updates
+ * instead of being destroyed by a rebuild. Element positions are refreshed
+ * after each canvas render via {@link syncPositions}.
  */
 export declare class AccessibilityLayer {
-    private shadowRoot;
+    private mirrorRoot;
     private nodeMap;
     private enabled;
-    constructor(container: HTMLElement | null, enabled?: boolean);
+    /** Whether the environment can host a mirror at all. */
+    private supported;
+    private canvas;
+    /**
+     * Last box written to each mirror element, so the per-frame position sync
+     * only touches elements whose geometry actually changed — style writes on
+     * n absolutely-positioned elements per frame are what they cost.
+     */
+    private lastSyncedBounds;
+    private lastRootRect;
+    private boundReposition;
+    constructor(canvas: HTMLElement | null, enabled?: boolean);
+    private mount;
+    private unmount;
+    /** Pin the overlay root to the canvas's page rect. */
+    private repositionRoot;
+    /**
+     * Mirror a `create` patch: build the element (detached — a subsequent
+     * `insert` places it). Elements mirror the virtual tree 1:1; visibility
+     * and decorative hiding are expressed with `display:none` (which removes
+     * the subtree from the AT tree) instead of omission, so sibling order
+     * always matches the virtual tree and `beforeId` mapping stays exact.
+     *
+     * The mirror's accessibility metadata (role, name, busy, hidden) comes
+     * from the engine-derived {@link Semantics} block — the single source of
+     * truth shared with every other renderer — not from ad-hoc prop sniffing.
+     * Form *values* (input value/placeholder) still come from props, as those
+     * aren't semantics.
+     */
+    createNode(node: VirtualNode): void;
+    /**
+     * Mirror an `insert` or `attach` patch. Re-inserting an element that is
+     * already in the tree moves it (native `insertBefore` semantics), so
+     * `move` routes here too. An `attach` reinserts the exact element kept
+     * alive by {@link detachNode} — AT identity survives router navigation.
+     */
+    insertNode(parentId: string, id: string, beforeId?: string): void;
+    /**
+     * Mirror a `remove` patch: drop the element and purge the subtree's
+     * id mappings.
+     */
+    removeNode(node: VirtualNode): void;
+    private purge;
+    /**
+     * Mirror a `detach` patch: unlink the element but keep the subtree and
+     * all id mappings alive so a later `attach` reinserts the same elements
+     * (router subtree cache parity).
+     */
+    detachNode(id: string): void;
+    /**
+     * Full rebuild from a virtual tree. Only used when re-enabling the mirror
+     * (`setEnabled(true)`) and by `clear()` — steady-state sync is incremental.
+     */
+    rebuild(root: VirtualNode | null): void;
+    private mountSubtree;
+    /**
+     * `display:none` removes the subtree from the accessibility tree — used
+     * both for `visible: false` and for decorative (`semantics.hidden`) nodes.
+     */
+    private syncVisibility;
     /**
-     * Sync shadow DOM with virtual tree
+     * Write each mirror element's box to its node's painted (scroll-aware)
+     * bounds — called by the renderer after every canvas render, so AT
+     * geometry follows layout changes and container scrolling. Positions are
+     * parent-relative (every mirror element is absolutely positioned).
      */
-    syncTree(root: VirtualNode): void;
+    syncPositions(root: VirtualNode | null): void;
     /**
-     * Create shadow DOM element for virtual node
+     * `scrollX`/`scrollY` accumulate the ancestors' scroll offsets down the
+     * recursion (the same subtraction `getScrollAwareBounds` derives by
+     * walking up), keeping the pass O(n) instead of O(n·depth). Writes are
+     * skipped when the element's box is unchanged since the last sync.
      */
-    private createShadowNode;
+    private syncNodePosition;
     /**
-     * Get text content from node tree
+     * Choose the semantic HTML tag for a node's shadow element and set its
+     * non-accessibility content (text, input value/placeholder). Roles/names are
+     * applied separately from the semantics block.
      */
-    private getNodeText;
+    private createShadowElement;
     /**
      * Focus node in shadow DOM
      */
@@ -36,10 +139,14 @@ export declare class AccessibilityLayer {
      * Get shadow element by node ID
      */
     getElement(nodeId: string): HTMLElement | undefined;
+    /** The fallback-content root element (for focus delegation wiring). */
+    getRoot(): HTMLElement | null;
+    isEnabled(): boolean;
     /**
-     * Enable or disable accessibility layer
+     * Enable or disable the mirror. Re-enabling rebuilds from the given
+     * virtual tree (incremental sync has no history to replay).
      */
-    setEnabled(enabled: boolean): void;
+    setEnabled(enabled: boolean, root?: VirtualNode | null): void;
     /**
      * Cleanup
      */