@hypen-space/core 0.4.980 → 0.5.3

package/src/types.ts

@@ -28,10 +28,22 @@ export type Patch = {
     | "attachEvent"
     | "detachEvent"
     | "detach"
-    | "attach";
+    | "attach"
+    | "setSemantics";
   id?: string;
   elementType?: string;
   props?: Record<string, any>;
+  /**
+   * Accessibility semantics derived by the engine for this node. Carried on
+   * `create` (first paint) and on `setSemantics` (reactive change — a
+   * templated accessible name or bound state whose source path changed).
+   * A `setSemantics` always carries the node's **complete** resolved block;
+   * renderers re-apply it with the same translation they run at create,
+   * clearing anything the new block no longer sets. Absent on `create` when
+   * the node has nothing derivable; absent on `setSemantics` when the node
+   * lost all semantics (→ clear everything).
+   */
+  semantics?: Semantics;
   name?: string;
   value?: any;
   text?: string;
@@ -40,6 +52,124 @@ export type Patch = {
   eventName?: string;
 };
 
+/**
+ * Platform-neutral accessibility semantics for a node, derived in the engine
+ * and carried on `create` patches. Each renderer maps this onto its native
+ * accessibility model (ARIA attributes on DOM, `Modifier.semantics` on
+ * Compose, accessibility traits on SwiftUI).
+ *
+ * Every field is optional; an absent field means "nothing derivable".
+ */
+export type Semantics = {
+  /**
+   * What this node is, as a platform-neutral role token (e.g. `"button"`).
+   * Mirrors the ARIA role vocabulary. Emitted only where the role is
+   * structurally certain from the component type.
+   */
+  role?: string;
+  /** Heading level (1–6) when known. */
+  level?: number;
+  /** Whether the node represents in-progress content (maps to `aria-busy`). */
+  busy?: boolean;
+  /**
+   * Live-region politeness (`.liveRegion("polite" | "assertive")`) →
+   * `aria-live` on DOM and the Canvas shadow tree. The engine validates the
+   * token, so only those two values arrive. Travels untranslated to the
+   * native renderers (no direct analog wired yet).
+   */
+  live?: string;
+  /**
+   * Accessible name derived from the element's text content, for roles that
+   * require one. On DOM this is usually left unapplied — the browser derives
+   * the name from visible content — but renderers without that affordance
+   * (Canvas shadow tree, iOS, Android) use it directly.
+   */
+  name?: string;
+  /**
+   * `true` when the element's role requires a name but none could be derived
+   * (e.g. an icon-only button). Surfaced by dev-mode conformance checks; the
+   * fix is an explicit label.
+   */
+  nameMissing?: boolean;
+  /**
+   * `true` when {@link name} came from an explicit author `.label(...)` rather
+   * than derived content. DOM applies an explicit name as `aria-label` (an
+   * intentional override) but leaves a derived name to the visible content.
+   */
+  nameExplicit?: boolean;
+  /**
+   * `true` when the element was marked decorative via `.hidden()`. It is
+   * removed from the accessibility tree (`aria-hidden`).
+   */
+  hidden?: boolean;
+  /**
+   * Supplementary description (`.description(...)`) — extra context beyond the
+   * name. Applied as `aria-description` on DOM.
+   */
+  description?: string;
+  /** Disclosure state → `aria-expanded`. */
+  expanded?: boolean;
+  /** Toggle-button state → `aria-pressed`. */
+  pressed?: boolean;
+  /** Selected state (e.g. a tab) → `aria-selected`. */
+  selected?: boolean;
+  /** Current-item token (page/step/…) → `aria-current`. */
+  current?: string;
+  /**
+   * Checked state for a `Checkbox`/`Switch` bound via `.bind(@state.x)` →
+   * `aria-checked`. Resolved at reconcile from the control's bind-target value.
+   */
+  checked?: boolean;
+  /**
+   * Validity state for a form control (`.invalid(bool | @state.hasError)`) →
+   * `aria-invalid`. A bound value resolves at reconcile and stays live via
+   * `setSemantics` re-emits. DOM only for now.
+   */
+  invalid?: boolean;
+  /**
+   * Cross-node relationship: id of the element this node controls →
+   * `aria-controls`. Web-leaning (DOM only); id references do not survive to
+   * the string-hint native APIs. See the guide's "Platform support" section
+   * (`hypen-docs/content/docs/guide/accessibility.mdx`).
+   */
+  controls?: string;
+  /**
+   * Cross-node relationship: id of the element that describes this node →
+   * `aria-describedby`. Web-leaning (DOM only), as with `controls`.
+   */
+  describedby?: string;
+  /**
+   * The author-supplied stable id of this node (`.id("details-panel")`) —
+   * the anchor id-reference relationships resolve against. Applied as the
+   * DOM `id` attribute.
+   */
+  id?: string;
+  /**
+   * Cross-node relationship: id of the element that labels this node →
+   * `aria-labelledby` (the tabpanel→tab half of the Tabs pattern). DOM only.
+   */
+  labelledby?: string;
+  /**
+   * Reactive cross-node reference: id of the currently-active descendant →
+   * `aria-activedescendant` (the roving focus pointer of composite widgets).
+   * Usually bound (`.activedescendant(@state.focusedId)`); kept live via
+   * `setSemantics` re-emits. DOM only.
+   */
+  activeDescendant?: string;
+  /**
+   * Cross-node relationship: id of an element that is logically this node's
+   * child but rendered elsewhere (a portaled popup) → `aria-owns`. DOM only.
+   */
+  owns?: string;
+  /**
+   * Base text direction (`.dir("rtl" | "ltr" | "auto")`) → the HTML `dir`
+   * attribute on DOM. The engine validates the token, so only those three
+   * values arrive. Native renderers translate to their layout-direction
+   * APIs (follow-up; the value already travels on the block).
+   */
+  dir?: string;
+};
+
 export type Action = {
   name: string;
   payload?: any;

package/src/validate.ts

@@ -0,0 +1,37 @@
+/**
+ * Patch-stream validation. A `create` patch whose `elementType` is neither a
+ * known primitive nor a resolved component is a silent resolver miss — the
+ * renderer drops the node, no error surfaces. `validatePatches` turns that into
+ * a one-line test/CI assertion.
+ */
+
+import type { Patch } from "./types.js";
+
+export interface PatchValidationResult {
+  /** Distinct `create` `elementType`s not in `knownTypes` (i.e. dropped nodes). */
+  unknownTypes: string[];
+}
+
+/**
+ * Distinct `create` `elementType`s not in `knownTypes`.
+ *
+ * `knownTypes` is caller-supplied (engine primitives + the app's resolvable
+ * component names) rather than read from the engine: the wasm-bindgen build
+ * exposes no primitive list, and hardcoding the built-ins would drift from Rust.
+ */
+export function validatePatches(
+  patches: Patch[],
+  knownTypes: Iterable<string>,
+): PatchValidationResult {
+  const known = knownTypes instanceof Set ? knownTypes : new Set(knownTypes);
+  const unknown = new Set<string>();
+
+  for (const patch of patches) {
+    if (patch.type !== "create") continue;
+    const elementType = patch.elementType;
+    if (typeof elementType !== "string") continue;
+    if (!known.has(elementType)) unknown.add(elementType);
+  }
+
+  return { unknownTypes: [...unknown] };
+}