@hypen-space/web 0.4.980 → 0.5.3

package/src/dom/applicators/events.ts

@@ -21,6 +21,8 @@ import {
   unregisterEvent,
   getKeyTarget,
   setKeyTarget,
+  getMeta,
+  setMeta,
 } from "../element-data.js";
 
 const log = frameworkLoggers.events;
@@ -197,6 +199,7 @@ function createEventHandler(
   eventType: string,
   options: EventHandlerOptions = {}
 ): ApplicatorHandler {
+  const actionMetaKey = `event:${eventType}`;
   return (element: HTMLElement, value: unknown) => {
     const { actionName, payload: customPayload } = extractActionDetails(value);
 
@@ -205,14 +208,18 @@ function createEventHandler(
       return;
     }
 
+    // Store the current action on the element; the persistent listener reads
+    // it per event, so re-applying with a different action (e.g. a keyed-
+    // reused node) replaces the dispatch target instead of stacking listeners.
+    setMeta(element, actionMetaKey, { actionName, customPayload });
+
     const disposables = getElementDisposables(element);
 
     // Track that we've registered this event type
     // The disposable stack handles cleanup automatically
-    const eventKey = `${eventType}:${actionName}`;
+    const eventKey = eventType;
     if (getRegisteredEvents(element).has(eventKey)) {
-      // Already registered - skip to avoid duplicates
-      // This can happen during re-renders
+      // Listener already installed — the meta update above retargets it
       return;
     }
     registerEvent(element, eventKey);
@@ -222,6 +229,12 @@ function createEventHandler(
 
     // Create the event listener
     const listener = (event: Event) => {
+      const current = getMeta<{ actionName: string; customPayload: Record<string, unknown> }>(
+        element,
+        actionMetaKey,
+      );
+      if (!current) return;
+
       // Handle throttling
       if (options.throttleMs && throttleTimer) {
         return;
@@ -240,8 +253,8 @@ function createEventHandler(
 
       // Build payload
       const payload =
-        Object.keys(customPayload).length > 0
-          ? { ...customPayload }
+        Object.keys(current.customPayload).length > 0
+          ? { ...current.customPayload }
           : options.extractPayload
             ? options.extractPayload(event, element)
             : extractEventData(event, element);
@@ -250,9 +263,9 @@ function createEventHandler(
       const engine = getEngine(element);
       if (engine) {
         try {
-          engine.dispatchAction(actionName, payload);
+          engine.dispatchAction(current.actionName, payload);
         } catch (err) {
-          log.error(`Error dispatching action "${actionName}":`, err);
+          log.error(`Error dispatching action "${current.actionName}":`, err);
         }
       }
     };
@@ -274,6 +287,24 @@ function createEventHandler(
   };
 }
 
+/**
+ * Dispatch the action encoded in an applicator value (e.g. `"@actions.save"`)
+ * to the element's engine. Shared by click wiring and keyboard activation so
+ * both routes dispatch identically. No-op if the value carries no action or
+ * the element has no engine.
+ */
+export function triggerElementAction(element: HTMLElement, value: unknown): void {
+  const { actionName, payload } = extractActionDetails(value);
+  if (!actionName) return;
+  const engine = getEngine(element);
+  if (!engine) return;
+  try {
+    engine.dispatchAction(actionName, payload);
+  } catch (err) {
+    log.error(`Error dispatching action "${actionName}":`, err);
+  }
+}
+
 /**
  * Create a keyboard event handler that filters by key
  */
@@ -496,6 +527,7 @@ export const eventHandlers: Record<string, ApplicatorHandler> = {
   // Mouse hover events
   onMouseEnter: createEventHandler("mouseenter", { extractPayload: mousePayload }),
   onMouseLeave: createEventHandler("mouseleave", { extractPayload: mousePayload }),
+  onHover: createEventHandler("mouseenter", { extractPayload: mousePayload }), // Alias for onMouseEnter
 
   // Two-way binding for .bind(@state.x)
   bind: ((element: HTMLElement, value: unknown) => {

package/src/dom/applicators/font.ts

@@ -5,17 +5,8 @@
 import type { ApplicatorHandler } from "./types.js";
 import { toCssLength } from "./size.js";
 
-// Track loaded Google Fonts per-document to avoid duplicate link tags
-const loadedGoogleFonts = new WeakMap<Document, Set<string>>();
-
-function getLoadedSet(doc: Document): Set<string> {
-  let set = loadedGoogleFonts.get(doc);
-  if (!set) {
-    set = new Set<string>();
-    loadedGoogleFonts.set(doc, set);
-  }
-  return set;
-}
+// Track loaded Google Fonts to avoid duplicate link tags
+const loadedGoogleFonts = new Set<string>();
 
 // System font keywords that shouldn't be loaded from Google Fonts
 const systemFontKeywords = new Set([
@@ -36,42 +27,40 @@ function isSystemFont(fontName: string): boolean {
 }
 
 /**
- * Load a Google Font by injecting a link tag into the given document.
+ * Load a Google Font by injecting a link tag.
  * @param fontName - The Google Font name (e.g., "Roboto", "Open Sans")
- * @param doc - The Document to inject into.
  */
-function loadGoogleFont(fontName: string, doc: Document): void {
+function loadGoogleFont(fontName: string): void {
   const normalized = fontName.trim();
-  const loaded = getLoadedSet(doc);
 
   // Skip if already loaded or is a system font
-  if (loaded.has(normalized) || isSystemFont(normalized)) {
+  if (loadedGoogleFonts.has(normalized) || isSystemFont(normalized)) {
     return;
   }
 
   // Mark as loading to avoid duplicates
-  loaded.add(normalized);
+  loadedGoogleFonts.add(normalized);
 
   // Create link element for Google Fonts
-  const link = doc.createElement("link");
+  const link = document.createElement("link");
   link.rel = "stylesheet";
   link.href = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(normalized)}:wght@100;200;300;400;500;600;700;800;900&display=swap`;
 
   // Add to document head
-  doc.head.appendChild(link);
+  document.head.appendChild(link);
 }
 
 /**
  * Parse a fontFamily value and load any Google Fonts.
  * Returns a CSS-safe font-family string.
  */
-function processFontFamily(value: string, doc: Document): string {
+function processFontFamily(value: string): string {
   // Split by comma to handle font stacks
   const fonts = value.split(",").map(f => f.trim().replace(/["']/g, ""));
 
   for (const font of fonts) {
     if (!isSystemFont(font)) {
-      loadGoogleFont(font, doc);
+      loadGoogleFont(font);
     }
   }
 
@@ -97,7 +86,7 @@ export const fontHandlers: Record<string, ApplicatorHandler> = {
   fontFamily: (el, value) => {
     const fontValue = String(value);
     // Process font family and load Google Fonts as needed
-    el.style.fontFamily = processFontFamily(fontValue, el.ownerDocument as Document);
+    el.style.fontFamily = processFontFamily(fontValue);
   },
 
   textAlign: (el, value) => {
@@ -138,20 +127,18 @@ export const fontHandlers: Record<string, ApplicatorHandler> = {
 export const GoogleFonts = {
   /**
    * Preload a Google Font before it's used.
-   * Defaults to the global `document` if no doc is provided.
    */
-  preload: (fontName: string, doc: Document = document) => loadGoogleFont(fontName, doc),
+  preload: loadGoogleFont,
 
   /**
-   * Check if a font has been loaded in the given document (defaults to global).
+   * Check if a font has been loaded.
    */
-  isLoaded: (fontName: string, doc: Document = document) =>
-    getLoadedSet(doc).has(fontName.trim()),
+  isLoaded: (fontName: string) => loadedGoogleFonts.has(fontName.trim()),
 
   /**
-   * Get list of loaded fonts for the given document (defaults to global).
+   * Get list of loaded fonts.
    */
-  getLoadedFonts: (doc: Document = document) => Array.from(getLoadedSet(doc)),
+  getLoadedFonts: () => Array.from(loadedGoogleFonts),
 
   /**
    * Popular Google Fonts for reference.

package/src/dom/applicators/index.ts

@@ -40,53 +40,39 @@ import { advancedLayoutHandlers } from "./advanced-layout.js";
 import { backgroundHandlers } from "./background.js";
 import { displayHandlers } from "./display.js";
 import { transitionHandlers } from "./transition.js";
+import { BREAKPOINTS as VARIANT_BREAKPOINTS, VALID_STATES } from "../../variants.js";
+import { ariaHandlers } from "./aria.js";
 
 /**
- * Tailwind breakpoint values for responsive variants
+ * Tailwind breakpoint values for responsive variants.
+ * Derived from the shared `variants.ts` table (single source of truth across
+ * DOM + Canvas renderers) and expressed as CSS `px` strings for media queries.
  */
-const BREAKPOINTS: Record<string, string> = {
-  sm: '640px',
-  md: '768px',
-  lg: '1024px',
-  xl: '1280px',
-  '2xl': '1536px',
-};
+const BREAKPOINTS: Record<string, string> = Object.fromEntries(
+  Object.entries(VARIANT_BREAKPOINTS).map(([name, px]) => [name, `${px}px`]),
+);
 
 /**
- * Per-document stylesheet for variant CSS rules
+ * Singleton stylesheet for variant CSS rules
  */
-const variantStyleSheets = new Map<Document, CSSStyleSheet>();
+let variantStyleSheet: CSSStyleSheet | null = null;
 
 /**
- * Track inserted rules to avoid duplicates (per-document)
+ * Track inserted rules to avoid duplicates
  */
-const insertedRules = new Map<Document, Set<string>>();
+const insertedRules = new Set<string>();
 
 /**
- * Get or create the variant stylesheet for a document
+ * Get or create the variant stylesheet
  */
-function getVariantStyleSheet(doc: Document): CSSStyleSheet {
-  let sheet = variantStyleSheets.get(doc);
-  if (!sheet) {
-    const style = doc.createElement('style');
+function getVariantStyleSheet(): CSSStyleSheet {
+  if (!variantStyleSheet) {
+    const style = document.createElement('style');
     style.id = 'hypen-variants';
-    doc.head.appendChild(style);
-    sheet = style.sheet as CSSStyleSheet;
-    variantStyleSheets.set(doc, sheet);
+    document.head.appendChild(style);
+    variantStyleSheet = style.sheet as CSSStyleSheet;
   }
-  return sheet;
-}
-
-/**
- * Get or create the inserted-rules dedup set for a document
- */
-function getInsertedRules(doc: Document): Set<string> {
-  let set = insertedRules.get(doc);
-  if (!set) {
-    set = new Set<string>();
-    insertedRules.set(doc, set);
-  }
-  return set;
+  return variantStyleSheet;
 }
 
 /**
@@ -341,6 +327,36 @@ export class ApplicatorRegistry {
     const atIndex = name.indexOf('@');
     const colonIndex = name.indexOf(':');
 
+    // Combined responsive + state variant: backgroundColor@md:hover.
+    // Canonical key order is `<prop>@<bp>:<state>`, so the breakpoint sits
+    // between '@' and ':'. Emitted as a pseudo-class rule nested in a media
+    // query so it applies only when BOTH the width matches AND the state holds.
+    if (atIndex !== -1 && colonIndex !== -1 && colonIndex > atIndex) {
+      const prop = name.slice(0, atIndex);
+      const breakpoint = name.slice(atIndex + 1, colonIndex);
+      const state = name.slice(colonIndex + 1);
+      const minWidth = BREAKPOINTS[breakpoint];
+
+      if (minWidth && VALID_STATES.includes(state)) {
+        const cssName = this.toKebabCase(prop);
+        const cssValue = this.formatCssValue(cssName, value);
+        const className = `hypen-${cssName.replace(/[^a-zA-Z0-9-]/g, '')}-${breakpoint}-${state}-${hashValue(value)}`;
+        const ruleKey = `${className}:${cssValue}`;
+
+        if (!insertedRules.has(ruleKey)) {
+          const sheet = getVariantStyleSheet();
+          sheet.insertRule(
+            `@media (min-width: ${minWidth}) { .${className}:${state} { ${cssName}: ${cssValue}; } }`,
+            sheet.cssRules.length
+          );
+          insertedRules.add(ruleKey);
+        }
+
+        element.classList.add(className);
+      }
+      return;
+    }
+
     // Responsive variant: padding@md, width@lg, etc.
     if (atIndex !== -1) {
       const prop = name.slice(0, atIndex);
@@ -348,21 +364,19 @@ export class ApplicatorRegistry {
       const minWidth = BREAKPOINTS[breakpoint];
 
       if (minWidth) {
-        const doc = element.ownerDocument as Document;
-        const dedup = getInsertedRules(doc);
         const cssName = this.toKebabCase(prop);
         const cssValue = this.formatCssValue(cssName, value);
         const className = `hypen-${cssName.replace(/[^a-zA-Z0-9-]/g, '')}-${breakpoint}-${hashValue(value)}`;
         const ruleKey = `${className}:${cssValue}`;
 
         // Avoid duplicate rule insertion
-        if (!dedup.has(ruleKey)) {
-          const sheet = getVariantStyleSheet(doc);
+        if (!insertedRules.has(ruleKey)) {
+          const sheet = getVariantStyleSheet();
           sheet.insertRule(
             `@media (min-width: ${minWidth}) { .${className} { ${cssName}: ${cssValue}; } }`,
             sheet.cssRules.length
           );
-          dedup.add(ruleKey);
+          insertedRules.add(ruleKey);
         }
 
         element.classList.add(className);
@@ -375,24 +389,21 @@ export class ApplicatorRegistry {
       const prop = name.slice(0, colonIndex);
       const state = name.slice(colonIndex + 1);
 
-      // Only handle known CSS pseudo-states
-      const validStates = ['hover', 'focus', 'active', 'disabled', 'focus-visible', 'focus-within'];
-      if (validStates.includes(state)) {
-        const doc = element.ownerDocument as Document;
-        const dedup = getInsertedRules(doc);
+      // Only handle known CSS pseudo-states (shared with the Canvas resolver)
+      if (VALID_STATES.includes(state)) {
         const cssName = this.toKebabCase(prop);
         const cssValue = this.formatCssValue(cssName, value);
         const className = `hypen-${cssName.replace(/[^a-zA-Z0-9-]/g, '')}-${state}-${hashValue(value)}`;
         const ruleKey = `${className}:${cssValue}`;
 
         // Avoid duplicate rule insertion
-        if (!dedup.has(ruleKey)) {
-          const sheet = getVariantStyleSheet(doc);
+        if (!insertedRules.has(ruleKey)) {
+          const sheet = getVariantStyleSheet();
           sheet.insertRule(
             `.${className}:${state} { ${cssName}: ${cssValue}; }`,
             sheet.cssRules.length
           );
-          dedup.add(ruleKey);
+          insertedRules.add(ruleKey);
         }
 
         element.classList.add(className);
@@ -510,5 +521,9 @@ export class ApplicatorRegistry {
     for (const [name, handler] of Object.entries(transitionHandlers)) {
       this.register(name, handler as ApplicatorHandler);
     }
+
+    for (const [name, handler] of Object.entries(ariaHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
   }
 }

package/src/dom/canvas/index.ts

@@ -8,8 +8,8 @@ import type { ComponentHandler } from "../components/index.js";
 import type { ApplicatorHandler } from "../applicators/index.js";
 
 export const canvasHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("canvas");
+  create(): HTMLElement {
+    const el = document.createElement("canvas");
     el.dataset.hypenType = "canvas";
     return el as any as HTMLElement;
   },

package/src/dom/components/app.ts

@@ -8,8 +8,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const appHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     el.style.display = "flex";
     el.style.flexDirection = "column";
     el.style.minHeight = "100vh";

package/src/dom/components/audio.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const audioHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("audio");
+  create(): HTMLElement {
+    const el = document.createElement("audio");
     el.dataset.hypenType = "audio";
     return el as any as HTMLElement;
   },

package/src/dom/components/avatar.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const avatarHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     el.dataset.hypenType = "avatar";
     el.style.display = "inline-flex";
     el.style.alignItems = "center";
@@ -23,11 +23,10 @@ export const avatarHandler: ComponentHandler = {
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
-    const doc = el.ownerDocument as Document;
     // Image source - support named arg with .0 suffix, positional arg, or plain name
     const src = props["src.0"] || props["0"] || props.src || props.source;
     if (src !== undefined) {
-      const img = doc.createElement("img");
+      const img = document.createElement("img");
       img.src = String(src);
       img.style.width = "100%";
       img.style.height = "100%";

package/src/dom/components/badge.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const badgeHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("span");
+  create(): HTMLElement {
+    const el = document.createElement("span");
     el.dataset.hypenType = "badge";
     el.style.display = "inline-block";
     el.style.padding = "4px 8px";
@@ -35,8 +35,7 @@ export const badgeHandler: ComponentHandler = {
     }
 
     // Text content
-    // `??` (not `||`) so the literal `0`, `false`, `""` still render.
-    const text = props["0"] ?? props.text;
+    const text = props["0"] || props.text;
     if (text !== undefined) {
       el.textContent = String(text);
     }

package/src/dom/components/button.ts

@@ -9,8 +9,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const buttonHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("button");
+  create(): HTMLElement {
+    const el = document.createElement("button");
     // Reset default button styles for cross-platform consistency
     el.style.border = "none";
     el.style.background = "none";

package/src/dom/components/card.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const cardHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     el.dataset.hypenType = "card";
     el.style.backgroundColor = "#ffffff";
     el.style.borderRadius = "8px";

package/src/dom/components/center.ts

@@ -9,8 +9,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const centerHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     el.style.display = "flex";
     el.style.alignItems = "center";
     el.style.justifyContent = "center";

package/src/dom/components/checkbox.ts

@@ -5,15 +5,15 @@
 import type { ComponentHandler } from "./index.js";
 
 export const checkboxHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const wrapper = doc.createElement("label");
+  create(): HTMLElement {
+    const wrapper = document.createElement("label");
     wrapper.dataset.hypenType = "checkbox";
     wrapper.style.display = "inline-flex";
     wrapper.style.alignItems = "center";
     wrapper.style.gap = "8px";
     wrapper.style.cursor = "pointer";
 
-    const input = doc.createElement("input");
+    const input = document.createElement("input");
     input.type = "checkbox";
     input.dataset.hypenCheckbox = "true";
     
@@ -23,7 +23,6 @@ export const checkboxHandler: ComponentHandler = {
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
-    const doc = el.ownerDocument as Document;
     const input = el.querySelector('input[type="checkbox"]') as HTMLInputElement;
     if (!input) return;
 
@@ -47,7 +46,7 @@ export const checkboxHandler: ComponentHandler = {
       textNodes.forEach(node => node.remove());
       
       // Add new label text
-      el.appendChild(doc.createTextNode(String(label)));
+      el.appendChild(document.createTextNode(String(label)));
     }
   },
 };

package/src/dom/components/column.ts

@@ -17,8 +17,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const columnHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     el.style.display = "flex";
     el.style.flexDirection = "column";
     el.style.alignItems = "stretch";

package/src/dom/components/container.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const containerHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     // Simple block container - wraps to content by default
     // Use .fillMaxWidth(true) to stretch
     el.dataset.hypenType = "container";

package/src/dom/components/divider.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const dividerHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("hr");
+  create(): HTMLElement {
+    const el = document.createElement("hr");
     el.dataset.hypenType = "divider";
     el.style.border = "none";
     el.style.borderTop = "1px solid #e0e0e0";

package/src/dom/components/grid.ts

@@ -6,13 +6,13 @@
 
 import type { ComponentHandler } from "./index.js";
 
-// Inject global styles for grid children (per-document)
-const injectedDocs = new WeakSet<Document>();
-function ensureGridStyles(doc: Document): void {
-  if (injectedDocs.has(doc)) return;
-  injectedDocs.add(doc);
+// Inject global styles for grid children
+let gridStylesInjected = false;
+function ensureGridStyles(): void {
+  if (gridStylesInjected) return;
+  gridStylesInjected = true;
 
-  const style = doc.createElement("style");
+  const style = document.createElement("style");
   style.id = "hypen-grid-styles";
   style.textContent = `
     /* Grid children stretch to fill cells by default (matches Android behavior) */
@@ -21,14 +21,14 @@ function ensureGridStyles(doc: Document): void {
       align-self: stretch;
     }
   `;
-  doc.head.appendChild(style);
+  document.head.appendChild(style);
 }
 
 export const gridHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    ensureGridStyles(doc);
+  create(): HTMLElement {
+    ensureGridStyles();
 
-    const el = doc.createElement("div");
+    const el = document.createElement("div");
     el.style.display = "grid";
     el.dataset.hypenType = "grid";
     return el;

package/src/dom/components/heading.ts

@@ -5,18 +5,17 @@
 import type { ComponentHandler } from "./index.js";
 
 export const headingHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("h2");
+  create(): HTMLElement {
+    const el = document.createElement("h2");
     el.dataset.hypenType = "heading";
     return el;
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
-    const doc = el.ownerDocument as Document;
     // Level property (1-6)
     if (props.level !== undefined) {
       const level = Math.max(1, Math.min(6, Number(props.level)));
-      const newEl = doc.createElement(`h${level}`);
+      const newEl = document.createElement(`h${level}`);
       newEl.dataset.hypenType = "heading";
       
       // Copy content and attributes
@@ -32,8 +31,7 @@ export const headingHandler: ComponentHandler = {
     }
 
     // Text content
-    // `??` (not `||`) so the literal `0`, `false`, `""` still render.
-    const text = props["0"] ?? props.text;
+    const text = props["0"] || props.text;
     if (text !== undefined) {
       el.textContent = String(text);
     }