@hypen-space/web 0.2.0

package/src/canvas/README.md

@@ -0,0 +1,376 @@
+# Canvas Renderer
+
+Browser-only module for rendering Hypen UI to a `<canvas>` element.
+
+## Overview
+
+The Canvas Renderer is a complete alternative to the DOM renderer that draws all UI elements directly to a canvas using the Canvas 2D API. This provides:
+
+- **Performance**: For very large UIs, canvas can be faster than DOM
+- **Control**: Pixel-perfect control over rendering
+- **Portability**: Can be adapted to other canvas-based platforms (WebGL, native canvas, etc.)
+- **Consistency**: Same rendering behavior across all browsers
+
+## Quick Start
+
+```typescript
+import { Engine, app } from "@hypen/core";
+import { CanvasRenderer } from "@hypen/core/canvas";
+
+// Setup canvas
+const canvas = document.getElementById("app") as HTMLCanvasElement;
+
+// Initialize engine
+const engine = new Engine();
+await engine.init();
+
+// Create canvas renderer
+const renderer = new CanvasRenderer(canvas, engine);
+
+// Set render callback
+engine.setRenderCallback((patches) => {
+  renderer.applyPatches(patches);
+});
+
+// Render UI
+await engine.renderSource(`
+  Column {
+    Text("Hello, Canvas!")
+    Button("@actions.click") { Text("Click me") }
+  }
+`);
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  CanvasRenderer                          │
+│  - Orchestrates layout, paint, events   │
+│  - Maintains virtual node tree          │
+│  - Schedules redraws                    │
+└─────────────────────────────────────────┘
+           ↓         ↓         ↓
+    ┌──────────┐ ┌──────┐ ┌───────┐
+    │  Layout  │ │ Paint│ │Events │
+    │  Engine  │ │System│ │Manager│
+    └──────────┘ └──────┘ └───────┘
+```
+
+### Virtual Node Tree
+
+Unlike the DOM renderer which creates real HTML elements, the canvas renderer maintains an internal virtual node tree:
+
+```typescript
+interface VirtualNode {
+  id: string
+  type: string
+  props: Record<string, any>
+  children: VirtualNode[]
+  layout?: Layout        // Computed position/size
+  visible: boolean
+  opacity: number
+  clickable: boolean
+  hovered: boolean
+  focused: boolean
+}
+```
+
+## Core Systems
+
+### 1. Layout Engine (`layout.ts`)
+
+Implements a flexbox-like layout system:
+
+- **Flexbox model**: Row/Column with `flex`, `gap`, alignment
+- **Box model**: Margin, padding, border
+- **Sizing**: width, height, min/max constraints
+- **Text layout**: Automatic text measurement and wrapping
+
+**Supported Properties:**
+- `flexDirection`: "row" | "column"
+- `justifyContent`: "flex-start" | "center" | "flex-end" | "space-between" | "space-around"
+- `alignItems`: "flex-start" | "center" | "flex-end" | "stretch"
+- `gap`: spacing between children
+- `padding`, `margin`: box spacing
+- `width`, `height`, `minWidth`, `maxWidth`, etc.
+
+### 2. Paint System (`paint.ts`)
+
+Draws virtual nodes to canvas:
+
+- **Background**: solid colors, border radius
+- **Border**: width, color, radius
+- **Text**: font rendering with alignment and wrapping
+- **Components**: Button, Input, Image, etc.
+
+**Custom Painters:**
+```typescript
+renderer.registerPainter("MyComponent", (ctx, node) => {
+  // Custom drawing code
+  ctx.fillStyle = node.props.color;
+  ctx.fillRect(
+    node.layout!.x,
+    node.layout!.y,
+    node.layout!.width,
+    node.layout!.height
+  );
+});
+```
+
+### 3. Event System (`events.ts`)
+
+Maps canvas events to virtual nodes:
+
+- **Hit Testing**: Determines which node was clicked/hovered
+- **Mouse Events**: click, mousedown, mouseup, mouseenter, mouseleave
+- **Keyboard Events**: keydown, keyup (for focused elements)
+- **Hover States**: Automatic cursor changes and hover effects
+
+**How It Works:**
+1. Mouse event occurs on canvas
+2. Convert to canvas coordinates
+3. Walk virtual tree to find node at coordinates (back to front)
+4. Dispatch action to engine if node has handler
+
+### 4. Text System (`text.ts`)
+
+Handles text measurement and rendering:
+
+- **Text Measurement**: Accurate width/height calculation
+- **Line Wrapping**: Automatic word wrapping to fit width
+- **Font Loading**: Ensures fonts are loaded before rendering
+- **Text Alignment**: left, center, right, top, middle, bottom
+- **Caching**: Text metrics are cached for performance
+
+### 5. Input Overlay (`input.ts`)
+
+Since canvas can't handle text input natively, we use DOM overlays:
+
+**Strategy:**
+1. When canvas input is focused, create a real `<input>` element
+2. Position it exactly over the canvas input (invisible to user)
+3. Style it to match the canvas input appearance
+4. Capture input and update state
+5. Remove overlay when focus is lost
+
+**Supports:**
+- Single-line text input
+- Multi-line textarea
+- Number input
+- Custom styling
+
+### 6. Accessibility (`accessibility.ts`)
+
+Maintains a shadow DOM tree for screen readers:
+
+**Strategy:**
+1. Create hidden DOM tree that mirrors canvas structure
+2. Use semantic HTML (button, input, etc.)
+3. Update shadow DOM when patches are applied
+4. Support keyboard navigation
+5. ARIA labels and roles
+
+This makes the canvas renderer fully accessible without impacting visual rendering.
+
+## Supported Components
+
+All Hypen components work with the canvas renderer:
+
+### Layout Components
+- **Column**: Vertical flex container
+- **Row**: Horizontal flex container
+- **Container/Box**: Generic container
+
+### Text Components
+- **Text**: Text with automatic wrapping
+
+### Interactive Components
+- **Button**: Clickable button with hover states
+- **Input**: Single-line text input
+- **Textarea**: Multi-line text input (future)
+
+### Media Components
+- **Image**: Image rendering (basic support)
+
+## Configuration Options
+
+```typescript
+const renderer = new CanvasRenderer(canvas, engine, {
+  // Display
+  devicePixelRatio: window.devicePixelRatio,  // HiDPI support
+  backgroundColor: "#ffffff",                  // Canvas background
+  
+  // Features
+  enableAccessibility: true,      // Shadow DOM for screen readers
+  enableHitTesting: true,         // Mouse event handling
+  enableInputOverlay: true,       // DOM overlays for text input
+  
+  // Performance (future)
+  enableDirtyRects: false,        // Only redraw changed regions
+  enableLayerCaching: false,      // Cache static subtrees
+  maxLayerCacheSize: 10,          // Max cached layers
+  
+  // Debug
+  showLayoutBounds: false,        // Draw red boxes around nodes
+  showDirtyRects: false,          // Highlight redrawn regions
+  logPerformance: false,          // Log FPS and render time
+});
+```
+
+## Examples
+
+See `examples/canvas-counter.ts` for a complete example.
+
+### Running Examples
+
+```bash
+# Using Bun
+bun examples/canvas-counter.ts
+
+# Or open HTML file directly
+open examples/canvas-counter.html
+```
+
+## Performance
+
+### Current Performance
+- **Typical UI**: 60fps with < 100 nodes
+- **Layout**: ~2-5ms for moderate trees
+- **Paint**: ~5-10ms for moderate trees
+- **Text**: Cached measurements are nearly free
+
+### Optimization Opportunities
+- ✅ Text metrics caching (implemented)
+- ⬜ Dirty rectangle tracking (planned)
+- ⬜ Layer caching (planned)
+- ⬜ Offscreen canvases (planned)
+- ⬜ WebGL backend (future)
+
+## Limitations
+
+### Current Limitations
+- ❌ No rich text (bold/italic within text)
+- ❌ No text selection/copy
+- ❌ No gradients
+- ❌ No shadows
+- ❌ No transforms (rotate/scale/skew)
+- ❌ Limited image support
+
+### Future Improvements
+All of these are planned for future releases!
+
+## Comparison: Canvas vs DOM
+
+| Feature | Canvas Renderer | DOM Renderer |
+|---------|----------------|--------------|
+| Performance (large UIs) | ✅ Better | ⚠️ Slower |
+| Text input | ⚠️ Overlay | ✅ Native |
+| Accessibility | ⚠️ Shadow DOM | ✅ Native |
+| Browser DevTools | ❌ No inspection | ✅ Full support |
+| CSS styling | ❌ Props only | ✅ CSS support |
+| Animations | ⚠️ Manual | ✅ CSS animations |
+| Memory usage | ✅ Lower | ⚠️ Higher |
+| Initial render | ✅ Faster | ⚠️ Slower |
+
+## When to Use Canvas Renderer
+
+**Use Canvas Renderer when:**
+- Building dashboards with many elements (100+)
+- Need consistent cross-browser rendering
+- Building games or creative tools
+- Performance is critical
+- Building for canvas-based platforms
+
+**Use DOM Renderer when:**
+- Building standard web apps
+- Need rich text formatting
+- Need CSS animations
+- Want browser DevTools support
+- Accessibility is paramount
+
+## API Reference
+
+### CanvasRenderer
+
+```typescript
+class CanvasRenderer implements Renderer {
+  constructor(
+    canvas: HTMLCanvasElement,
+    engine: Engine,
+    options?: Partial<CanvasRendererOptions>
+  )
+  
+  // Renderer interface
+  applyPatches(patches: Patch[]): void
+  getNode(id: string): VirtualNode | undefined
+  clear(): void
+  
+  // Canvas-specific
+  registerPainter(type: string, painter: PainterFunction): void
+  setOptions(options: Partial<CanvasRendererOptions>): void
+  destroy(): void
+}
+```
+
+### Custom Painters
+
+```typescript
+type PainterFunction = (
+  ctx: CanvasRenderingContext2D,
+  node: VirtualNode
+) => void;
+
+renderer.registerPainter("Circle", (ctx, node) => {
+  const layout = node.layout!;
+  const radius = Math.min(layout.width, layout.height) / 2;
+  const centerX = layout.x + layout.width / 2;
+  const centerY = layout.y + layout.height / 2;
+  
+  ctx.beginPath();
+  ctx.arc(centerX, centerY, radius, 0, Math.PI * 2);
+  ctx.fillStyle = node.props.color || "#000";
+  ctx.fill();
+});
+```
+
+## Testing
+
+The canvas renderer includes comprehensive tests:
+
+```bash
+# Run tests
+bun test src/canvas
+
+# Run with coverage
+bun test --coverage src/canvas
+```
+
+## Contributing
+
+The canvas renderer is under active development. Contributions welcome!
+
+**Current Priorities:**
+1. Text selection support
+2. Gradient/shadow support
+3. Performance optimizations (dirty rects, layer caching)
+4. Advanced text (rich text, ligatures)
+5. More component painters
+
+## See Also
+
+- [Main README](../../README.md) - SDK documentation
+- [DOM Renderer](../dom/README.md) - DOM renderer documentation
+- [Plan](./plan.md) - Implementation plan and roadmap
+- [Canvas API Docs](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API)
+
+
+
+
+
+
+
+
+
+
+

package/src/canvas/accessibility.ts

@@ -0,0 +1,218 @@
+/**
+ * Accessibility Layer
+ *
+ * Maintain shadow DOM for screen readers
+ */
+
+import type { VirtualNode } from "./types.js";
+import { walkTree } from "./utils.js";
+
+/**
+ * Accessibility Manager
+ */
+export class AccessibilityLayer {
+  private shadowRoot: HTMLElement;
+  private nodeMap = new Map<string, HTMLElement>();
+  private enabled: boolean;
+
+  constructor(container: HTMLElement | null, enabled: boolean = true) {
+    this.enabled = enabled && typeof document !== "undefined";
+
+    // Create shadow root container (only in browser)
+    if (this.enabled && typeof document !== "undefined") {
+      this.shadowRoot = document.createElement("div");
+      this.shadowRoot.setAttribute("role", "application");
+      this.shadowRoot.setAttribute("aria-label", "Hypen Canvas Application");
+      this.shadowRoot.style.position = "absolute";
+      this.shadowRoot.style.left = "-9999px";
+      this.shadowRoot.style.width = "1px";
+      this.shadowRoot.style.height = "1px";
+      this.shadowRoot.style.overflow = "hidden";
+
+      if (container) {
+        container.appendChild(this.shadowRoot);
+      }
+    } else {
+      // Fallback for non-browser environments
+      this.shadowRoot = {} as HTMLElement;
+    }
+  }
+
+  /**
+   * Sync shadow DOM with virtual tree
+   */
+  syncTree(root: VirtualNode): void {
+    if (!this.enabled) return;
+
+    // Clear existing
+    this.shadowRoot.innerHTML = "";
+    this.nodeMap.clear();
+
+    // Build shadow DOM
+    const shadowNode = this.createShadowNode(root);
+    if (shadowNode) {
+      this.shadowRoot.appendChild(shadowNode);
+    }
+  }
+
+  /**
+   * Create shadow DOM element for virtual node
+   */
+  private createShadowNode(node: VirtualNode): HTMLElement | null {
+    if (!node.visible) return null;
+
+    let element: HTMLElement;
+
+    // Create appropriate HTML element
+    switch (node.type.toLowerCase()) {
+      case "button":
+        element = document.createElement("button");
+        element.textContent = this.getNodeText(node);
+        if (node.props.onclick) {
+          element.setAttribute("aria-label", "Clickable button");
+        }
+        break;
+
+      case "input":
+        element = document.createElement("input");
+        (element as HTMLInputElement).type = node.props.type || "text";
+        (element as HTMLInputElement).value = node.props.value || "";
+        if (node.props.placeholder) {
+          (element as HTMLInputElement).placeholder = node.props.placeholder;
+        }
+        break;
+
+      case "textarea":
+        element = document.createElement("textarea");
+        (element as HTMLTextAreaElement).value = node.props.value || "";
+        if (node.props.placeholder) {
+          (element as HTMLTextAreaElement).placeholder = node.props.placeholder;
+        }
+        break;
+
+      case "image":
+        element = document.createElement("img");
+        (element as HTMLImageElement).src = node.props.src || "";
+        (element as HTMLImageElement).alt = node.props.alt || "Image";
+        break;
+
+      case "text":
+        element = document.createElement("span");
+        element.textContent = String(node.props[0] || node.props.text || "");
+        break;
+
+      case "column":
+      case "row":
+      case "container":
+      case "box":
+        element = document.createElement("div");
+        element.setAttribute("role", node.type === "column" ? "group" : "group");
+        break;
+
+      default:
+        element = document.createElement("div");
+    }
+
+    // Set common attributes
+    element.setAttribute("data-hypen-id", node.id);
+
+    if (node.props["aria-label"]) {
+      element.setAttribute("aria-label", node.props["aria-label"]);
+    }
+
+    if (node.focusable) {
+      element.tabIndex = 0;
+    }
+
+    // Store mapping
+    this.nodeMap.set(node.id, element);
+
+    // Add children
+    for (const child of node.children) {
+      const childElement = this.createShadowNode(child);
+      if (childElement) {
+        element.appendChild(childElement);
+      }
+    }
+
+    return element;
+  }
+
+  /**
+   * Get text content from node tree
+   */
+  private getNodeText(node: VirtualNode): string {
+    if (node.type === "text") {
+      return String(node.props[0] || node.props.text || "");
+    }
+
+    let text = "";
+    for (const child of node.children) {
+      text += this.getNodeText(child);
+    }
+    return text;
+  }
+
+  /**
+   * Focus node in shadow DOM
+   */
+  focusNode(nodeId: string): void {
+    if (!this.enabled) return;
+
+    const element = this.nodeMap.get(nodeId);
+    if (element) {
+      element.focus();
+    }
+  }
+
+  /**
+   * Update single node
+   */
+  updateNode(node: VirtualNode): void {
+    if (!this.enabled) return;
+
+    const element = this.nodeMap.get(node.id);
+    if (!element) return;
+
+    // Update text content
+    if (node.type === "text") {
+      element.textContent = String(node.props[0] || node.props.text || "");
+    }
+
+    // Update input value
+    if (node.type === "input" || node.type === "textarea") {
+      (element as HTMLInputElement | HTMLTextAreaElement).value = node.props.value || "";
+    }
+
+    // Update visibility
+    element.style.display = node.visible ? "" : "none";
+  }
+
+  /**
+   * Get shadow element by node ID
+   */
+  getElement(nodeId: string): HTMLElement | undefined {
+    return this.nodeMap.get(nodeId);
+  }
+
+  /**
+   * Enable or disable accessibility layer
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+    if (!enabled && this.shadowRoot.parentElement) {
+      this.shadowRoot.remove();
+    }
+  }
+
+  /**
+   * Cleanup
+   */
+  destroy(): void {
+    if (this.shadowRoot.parentElement) {
+      this.shadowRoot.remove();
+    }
+    this.nodeMap.clear();
+  }
+}
+