@hypen-space/web 0.4.980 → 0.5.3

package/src/dom/components/input.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const inputHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("input");
+  create(): HTMLElement {
+    const el = document.createElement("input");
     el.dataset.hypenType = "input";
     // Reset the default user-agent chrome so `.tw("bg-gray-100 rounded-lg")`
     // on an Input reads the same as any other styled element. Without

package/src/dom/components/link.ts

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

package/src/dom/components/list.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const listHandler: 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"; // Default to vertical (like Android)
     // Default to flex-start to match Android/iOS behavior

package/src/dom/components/paragraph.ts

@@ -5,16 +5,15 @@
 import type { ComponentHandler } from "./index.js";
 
 export const paragraphHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("p");
+  create(): HTMLElement {
+    const el = document.createElement("p");
     el.dataset.hypenType = "paragraph";
     return el;
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
     // 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/progressbar.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const progressBarHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const wrapper = doc.createElement("div");
+  create(): HTMLElement {
+    const wrapper = document.createElement("div");
     wrapper.dataset.hypenType = "progressbar";
     wrapper.style.width = "100%";
     wrapper.style.height = "8px";
@@ -14,7 +14,7 @@ export const progressBarHandler: ComponentHandler = {
     wrapper.style.borderRadius = "4px";
     wrapper.style.overflow = "hidden";
 
-    const bar = doc.createElement("div");
+    const bar = document.createElement("div");
     bar.dataset.hypenBar = "true";
     bar.style.height = "100%";
     bar.style.backgroundColor = "#2196F3";

package/src/dom/components/route.ts

@@ -9,8 +9,8 @@ import { frameworkLoggers } from "@hypen-space/core/logger";
 const log = frameworkLoggers.router;
 
 export const routeHandler: 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.width = "100%";

package/src/dom/components/router.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const routerHandler: 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.width = "100%";

package/src/dom/components/row.ts

@@ -6,13 +6,13 @@
 
 import type { ComponentHandler } from "./index.js";
 
-// Inject global styles for Row with flex/weighted children (per-document)
-const injectedDocs = new WeakSet<Document>();
-function ensureRowStyles(doc: Document): void {
-  if (injectedDocs.has(doc)) return;
-  injectedDocs.add(doc);
+// Inject global styles for Row with flex/weighted children
+let rowStylesInjected = false;
+function ensureRowStyles(): void {
+  if (rowStylesInjected) return;
+  rowStylesInjected = true;
 
-  const style = doc.createElement("style");
+  const style = document.createElement("style");
   style.id = "hypen-row-styles";
   style.textContent = `
     /* Row expands to fill width when it has children with flex/weight */
@@ -21,14 +21,14 @@ function ensureRowStyles(doc: Document): void {
       width: 100%;
     }
   `;
-  doc.head.appendChild(style);
+  document.head.appendChild(style);
 }
 
 export const rowHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    ensureRowStyles(doc);
+  create(): HTMLElement {
+    ensureRowStyles();
 
-    const el = doc.createElement("div");
+    const el = document.createElement("div");
     el.style.display = "flex";
     el.style.flexDirection = "row";
     // Wrap to content by default (match iOS/Android behavior)

package/src/dom/components/select.ts

@@ -5,14 +5,13 @@
 import type { ComponentHandler } from "./index.js";
 
 export const selectHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("select");
+  create(): HTMLElement {
+    const el = document.createElement("select");
     el.dataset.hypenType = "select";
     return el as any as HTMLElement;
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
-    const doc = el.ownerDocument as Document;
     const select = el as HTMLSelectElement;
 
     // Value property
@@ -37,7 +36,7 @@ export const selectHandler: ComponentHandler = {
       
       // Add new options
       props.options.forEach((opt: any) => {
-        const option = doc.createElement("option");
+        const option = document.createElement("option");
         
         if (typeof opt === "string") {
           option.value = opt;

package/src/dom/components/slider.ts

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

package/src/dom/components/spacer.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const spacerHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("div");
+  create(): HTMLElement {
+    const el = document.createElement("div");
     el.style.flex = "1";
     el.dataset.hypenType = "spacer";
     return el;

package/src/dom/components/spinner.ts

@@ -4,32 +4,50 @@
 
 import type { ComponentHandler } from "./index.js";
 
+const STYLE_ID = "hypen-spinner-styles";
+
+/**
+ * Inject the shared spin keyframes once (same singleton pattern as
+ * ensureA11yStyles). Safe to call repeatedly and in non-DOM environments.
+ */
+function ensureSpinnerStyles(): void {
+  if (typeof document === "undefined" || !document.head) {
+    return;
+  }
+
+  if (typeof document.getElementById === "function" && document.getElementById(STYLE_ID)) {
+    return;
+  }
+
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+    @keyframes hypen-spin {
+      0% { transform: rotate(0deg); }
+      100% { transform: rotate(360deg); }
+    }
+  `;
+  document.head.appendChild(style);
+}
+
 export const spinnerHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const wrapper = doc.createElement("div");
+  create(): HTMLElement {
+    ensureSpinnerStyles();
+
+    const wrapper = document.createElement("div");
     wrapper.dataset.hypenType = "spinner";
     wrapper.style.display = "inline-block";
 
-    const spinner = doc.createElement("div");
+    const spinner = document.createElement("div");
     spinner.style.width = "40px";
     spinner.style.height = "40px";
     spinner.style.border = "4px solid #f3f3f3";
     spinner.style.borderTop = "4px solid #3498db";
     spinner.style.borderRadius = "50%";
-    spinner.style.animation = "spin 1s linear infinite";
-
-    // Add keyframe animation
-    const style = doc.createElement("style");
-    style.textContent = `
-      @keyframes spin {
-        0% { transform: rotate(0deg); }
-        100% { transform: rotate(360deg); }
-      }
-    `;
-    
-    wrapper.appendChild(style);
+    spinner.style.animation = "hypen-spin 1s linear infinite";
+
     wrapper.appendChild(spinner);
-    
+
     return wrapper;
   },
 

package/src/dom/components/stack.ts

@@ -4,13 +4,13 @@
 
 import type { ComponentHandler } from "./index.js";
 
-// Inject global styles once per document
-const injectedDocs = new WeakSet<Document>();
-function ensureStackStyles(doc: Document): void {
-  if (injectedDocs.has(doc)) return;
-  injectedDocs.add(doc);
+// Inject global styles once
+let stackStylesInjected = false;
+function ensureStackStyles(): void {
+  if (stackStylesInjected) return;
+  stackStylesInjected = true;
 
-  const style = doc.createElement("style");
+  const style = document.createElement("style");
   style.id = "hypen-stack-styles";
   style.textContent = `
     [data-hypen-type="stack"] {
@@ -29,14 +29,14 @@ function ensureStackStyles(doc: Document): void {
       /* Don't set justify-self/align-self here - let parent's justify-items/align-items control */
     }
   `;
-  doc.head.appendChild(style);
+  document.head.appendChild(style);
 }
 
 export const stackHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    ensureStackStyles(doc);
+  create(): HTMLElement {
+    ensureStackStyles();
 
-    const el = doc.createElement("div");
+    const el = document.createElement("div");
     el.dataset.hypenType = "stack";
 
     return el;

package/src/dom/components/switch.ts

@@ -5,15 +5,15 @@
 import type { ComponentHandler } from "./index.js";
 
 export const switchHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const wrapper = doc.createElement("label");
+  create(): HTMLElement {
+    const wrapper = document.createElement("label");
     wrapper.dataset.hypenType = "switch";
     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.hypenSwitch = "true";
     
@@ -28,7 +28,7 @@ export const switchHandler: ComponentHandler = {
     input.style.transition = "background-color 0.2s";
     
     // Add pseudo-element styling via CSS
-    const style = doc.createElement("style");
+    const style = document.createElement("style");
     style.textContent = `
       input[data-hypen-switch="true"]::before {
         content: "";
@@ -55,7 +55,6 @@ export const switchHandler: 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;
 
@@ -79,7 +78,7 @@ export const switchHandler: 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/tabs.ts

@@ -0,0 +1,76 @@
+/**
+ * Composite-widget hosts: Tabs / Tab / TabPanel / Option.
+ *
+ * These exist so the composite element types render *focusable, styleable*
+ * hosts instead of falling through to the unknown-component fallback (a
+ * `display: contents` div, which cannot reliably hold keyboard focus). The
+ * accessibility roles come from the engine-derived Semantics block
+ * (tablist/tab/tabpanel/option), not from these handlers; keyboard roving is
+ * wired by the renderer when it sees `role="tablist"` (see operability.ts).
+ */
+
+import type { ComponentHandler } from "./index.js";
+
+/** Tabs → a plain row container; role="tablist" arrives via semantics. */
+export const tabsHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("div");
+    el.dataset.hypenType = "tabs";
+    el.style.display = "flex";
+    el.style.flexDirection = "row";
+    return el;
+  },
+};
+
+/**
+ * Tab → a native `<button>` so focus and Enter/Space activation come free;
+ * the engine's `role="tab"` overrides the implicit button role (see the
+ * IMPLICIT_ROLE override logic in semantics.ts).
+ */
+export const tabHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("button");
+    el.setAttribute("type", "button");
+    el.dataset.hypenType = "tab";
+    return el;
+  },
+
+  applyProps(el: HTMLElement, props: Record<string, any>): void {
+    const text = props["0"] ?? props.text;
+    if (text !== undefined) {
+      el.dataset.textTemplate = String(text);
+      el.textContent = String(text);
+    }
+  },
+};
+
+/**
+ * TabPanel → a focusable region (`tabindex=0`) so a Tab keypress from the
+ * tablist lands inside the panel even when it has no focusable content
+ * (WAI-ARIA APG recommendation).
+ */
+export const tabPanelHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("div");
+    el.dataset.hypenType = "tabpanel";
+    el.tabIndex = 0;
+    return el;
+  },
+};
+
+/** Option → a plain div host; role="option" arrives via semantics. */
+export const optionHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("div");
+    el.dataset.hypenType = "option";
+    return el;
+  },
+
+  applyProps(el: HTMLElement, props: Record<string, any>): void {
+    const text = props["0"] ?? props.text;
+    if (text !== undefined) {
+      el.dataset.textTemplate = String(text);
+      el.textContent = String(text);
+    }
+  },
+};

package/src/dom/components/text.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const textHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("span");
+  create(): HTMLElement {
+    const el = document.createElement("span");
     // Use inline-block for proper flex child behavior
     el.style.display = "inline-block";
     // Tight line-height to match iOS/Android
@@ -20,11 +20,8 @@ export const textHandler: ComponentHandler = {
   },
 
   applyProps(el: HTMLElement, props: Record<string, any>): void {
-    // Text content from first positional arg or "text" prop. Use `??` (not
-    // `||`) so the literal number `0`, `false`, and the empty string still
-    // render — `||` falls through on falsy values and a bound `0` was
-    // disappearing entirely on web while iOS rendered it correctly.
-    const text = props["0"] ?? props.text;
+    // Text content from first positional arg or "text" prop
+    const text = props["0"] || props.text;
     if (text !== undefined) {
       // Store the original text template for state interpolation
       el.dataset.textTemplate = String(text);

package/src/dom/components/textarea.ts

@@ -5,8 +5,8 @@
 import type { ComponentHandler } from "./index.js";
 
 export const textareaHandler: ComponentHandler = {
-  create(doc: Document): HTMLElement {
-    const el = doc.createElement("textarea");
+  create(): HTMLElement {
+    const el = document.createElement("textarea");
     el.dataset.hypenType = "textarea";
     // Same user-agent reset as Input — otherwise `.tw(...)` styling draws
     // over a native dark border and inset shadow.

package/src/dom/components/video.ts

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

package/src/dom/components/visuallyhidden.ts

@@ -0,0 +1,30 @@
+/**
+ * VisuallyHidden Component
+ *
+ * Renders content that is invisible on screen but remains in the accessibility
+ * tree for screen readers — the standard "sr-only" pattern. Useful for giving
+ * an icon-only control readable text, announcing context, etc.
+ */
+
+import type { ComponentHandler } from "./index.js";
+
+export const visuallyHiddenHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("span");
+    el.dataset.hypenType = "visuallyhidden";
+
+    // Standard visually-hidden (sr-only) styles: removed from the visual
+    // layout but still read by assistive technology.
+    el.style.position = "absolute";
+    el.style.width = "1px";
+    el.style.height = "1px";
+    el.style.padding = "0";
+    el.style.margin = "-1px";
+    el.style.overflow = "hidden";
+    el.style.clip = "rect(0, 0, 0, 0)";
+    el.style.whiteSpace = "nowrap";
+    el.style.border = "0";
+
+    return el;
+  },
+};

package/src/dom/debug.ts

@@ -76,8 +76,6 @@ export class RerenderTracker {
    * Create or update the heatmap overlay for an element
    */
   private updateHeatmap(id: string, element: HTMLElement, renderCount: number, patchType: string): void {
-    const doc = element.ownerDocument as Document;
-    const win = doc.defaultView ?? window;
     // Calculate opacity based on render count (increment by heatmapIncrement% each time)
     const opacity = Math.min(
       (renderCount * this.config.heatmapIncrement) / 100,
@@ -87,7 +85,7 @@ export class RerenderTracker {
     log.debug(`Updating heatmap for ${id}, count: ${renderCount}, opacity: ${opacity}`);
 
     // For inline elements or text, use a simpler approach: background color + outline
-    const isInline = win.getComputedStyle(element).display.includes('inline');
+    const isInline = window.getComputedStyle(element).display.includes('inline');
 
     if (isInline || element.tagName === 'SPAN') {
       // Store original styles if not already stored
@@ -107,8 +105,8 @@ export class RerenderTracker {
       element.setAttribute('data-hypen-renders', `${renderCount}× ${patchType}`);
 
       // Add CSS for the badge if not already added
-      if (!doc.getElementById('hypen-debug-styles')) {
-        const style = doc.createElement('style');
+      if (!document.getElementById('hypen-debug-styles')) {
+        const style = document.createElement('style');
         style.id = 'hypen-debug-styles';
         style.textContent = `
           [data-hypen-renders]::before {
@@ -129,7 +127,7 @@ export class RerenderTracker {
             text-shadow: none;
           }
         `;
-        doc.head.appendChild(style);
+        document.head.appendChild(style);
       }
 
       // Store in overlays map for cleanup
@@ -150,7 +148,7 @@ export class RerenderTracker {
       let overlay = this.overlays.get(id);
 
       if (!overlay) {
-        overlay = doc.createElement("div");
+        overlay = document.createElement("div");
         overlay.className = "hypen-debug-overlay";
         overlay.style.cssText = `
           position: absolute;
@@ -173,7 +171,7 @@ export class RerenderTracker {
           visibility: visible !important;
         `;
 
-        const currentPosition = win.getComputedStyle(element).position;
+        const currentPosition = window.getComputedStyle(element).position;
         if (currentPosition === 'static') {
           element.style.position = 'relative';
         }

package/src/dom/index.ts

@@ -9,11 +9,3 @@ export { ComponentRegistry } from "./components/index.js";
 export { ApplicatorRegistry } from "./applicators/index.js";
 export { EventManager } from "./events.js";
 export { RerenderTracker, type DebugConfig, defaultDebugConfig } from "./debug.js";
-export {
-  createDomClient as createHypenClient,
-  createDomClient,
-  type DomClient as HypenClient,
-  type DomClient,
-  type DomClientOptions as HypenClientOptions,
-  type DomClientOptions,
-} from "../client.js";