@hypen-space/web 0.2.0

package/src/canvas/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Canvas Renderer Types
+ *
+ * Shared type definitions for the canvas renderer
+ */
+
+export interface VirtualNode {
+  id: string;
+  type: string;
+  props: Record<string, any>;
+  children: VirtualNode[];
+  parent: VirtualNode | null;
+
+  // Computed layout
+  layout?: Layout;
+
+  // Rendering state
+  visible: boolean;
+  opacity: number;
+
+  // Interaction state
+  clickable: boolean;
+  hoverable: boolean;
+  focusable: boolean;
+  focused: boolean;
+  hovered: boolean;
+}
+
+export interface Layout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+
+  // Box model
+  margin: BoxSpacing;
+  padding: BoxSpacing;
+  border: BorderStyle;
+
+  // Content area (after padding)
+  contentX: number;
+  contentY: number;
+  contentWidth: number;
+  contentHeight: number;
+}
+
+export interface BoxSpacing {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface BorderStyle {
+  width: number;
+  color: string;
+  radius: number;
+}
+
+export interface Rectangle {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface FontStyle {
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: string | number;
+  lineHeight?: number;
+}
+
+export interface TextStyle extends FontStyle {
+  color: string;
+  textAlign: "left" | "center" | "right";
+  verticalAlign: "top" | "middle" | "bottom";
+}
+
+export interface TextMetrics {
+  width: number;
+  height: number;
+  lines: string[];
+  lineHeight: number;
+}
+
+export interface CanvasRendererOptions {
+  // Display
+  devicePixelRatio?: number;
+  backgroundColor?: string;
+
+  // Features
+  enableAccessibility?: boolean;
+  enableHitTesting?: boolean;
+  enableInputOverlay?: boolean;
+
+  // Performance
+  enableDirtyRects?: boolean;
+  enableLayerCaching?: boolean;
+  maxLayerCacheSize?: number;
+
+  // Debug
+  showLayoutBounds?: boolean;
+  showDirtyRects?: boolean;
+  logPerformance?: boolean;
+}
+
+export interface PainterFunction {
+  (ctx: CanvasRenderingContext2D, node: VirtualNode): void;
+}
+
+export interface LayoutFunction {
+  (node: VirtualNode, availableWidth: number, availableHeight: number): {
+    width: number;
+    height: number;
+  };
+}
+
+export interface DirtyRect extends Rectangle {
+  frameId: number;
+}
+
+
+
+
+
+
+
+
+
+
+

package/src/canvas/utils.ts

@@ -0,0 +1,218 @@
+/**
+ * Canvas Renderer Utilities
+ *
+ * Common utility functions
+ */
+
+import type { BoxSpacing, Rectangle, Point, VirtualNode } from "./types.js";
+
+/**
+ * Parse spacing value (margin, padding)
+ * Supports: number, "10", "10 20", "10 20 30 40"
+ */
+export function parseSpacing(value: any): BoxSpacing {
+  if (typeof value === "number") {
+    return { top: value, right: value, bottom: value, left: value };
+  }
+
+  if (typeof value === "string") {
+    const parts = value.split(/\s+/).map((v) => parseFloat(v) || 0);
+    if (parts.length === 1) {
+      return { top: parts[0], right: parts[0], bottom: parts[0], left: parts[0] };
+    }
+    if (parts.length === 2) {
+      return { top: parts[0], right: parts[1], bottom: parts[0], left: parts[1] };
+    }
+    if (parts.length === 4) {
+      return { top: parts[0], right: parts[1], bottom: parts[2], left: parts[3] };
+    }
+  }
+
+  if (typeof value === "object" && value !== null) {
+    return {
+      top: parseFloat(value.top) || 0,
+      right: parseFloat(value.right) || 0,
+      bottom: parseFloat(value.bottom) || 0,
+      left: parseFloat(value.left) || 0,
+    };
+  }
+
+  return { top: 0, right: 0, bottom: 0, left: 0 };
+}
+
+/**
+ * Parse size value (width, height)
+ * Returns pixel value or null for "auto"
+ */
+export function parseSize(value: any): number | null {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    if (value === "auto") return null;
+    const num = parseFloat(value);
+    return isNaN(num) ? null : num;
+  }
+  return null;
+}
+
+/**
+ * Check if point is inside rectangle
+ */
+export function isPointInRect(point: Point, rect: Rectangle): boolean {
+  return (
+    point.x >= rect.x &&
+    point.x <= rect.x + rect.width &&
+    point.y >= rect.y &&
+    point.y <= rect.y + rect.height
+  );
+}
+
+/**
+ * Check if point is inside rounded rectangle
+ */
+export function isPointInRoundedRect(
+  point: Point,
+  rect: Rectangle,
+  radius: number
+): boolean {
+  const { x, y, width, height } = rect;
+
+  // Quick reject if outside bounding box
+  if (!isPointInRect(point, rect)) return false;
+
+  // No radius means simple rectangle
+  if (radius <= 0) return true;
+
+  const px = point.x;
+  const py = point.y;
+
+  // Check corners
+  // Top-left
+  if (px < x + radius && py < y + radius) {
+    return Math.pow(px - (x + radius), 2) + Math.pow(py - (y + radius), 2) <= Math.pow(radius, 2);
+  }
+
+  // Top-right
+  if (px > x + width - radius && py < y + radius) {
+    return (
+      Math.pow(px - (x + width - radius), 2) + Math.pow(py - (y + radius), 2) <=
+      Math.pow(radius, 2)
+    );
+  }
+
+  // Bottom-left
+  if (px < x + radius && py > y + height - radius) {
+    return (
+      Math.pow(px - (x + radius), 2) + Math.pow(py - (y + height - radius), 2) <=
+      Math.pow(radius, 2)
+    );
+  }
+
+  // Bottom-right
+  if (px > x + width - radius && py > y + height - radius) {
+    return (
+      Math.pow(px - (x + width - radius), 2) + Math.pow(py - (y + height - radius), 2) <=
+      Math.pow(radius, 2)
+    );
+  }
+
+  // Inside rectangle
+  return true;
+}
+
+/**
+ * Merge rectangles into bounding box
+ */
+export function mergeRects(rects: Rectangle[]): Rectangle | null {
+  if (rects.length === 0) return null;
+  if (rects.length === 1) return rects[0];
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (const rect of rects) {
+    minX = Math.min(minX, rect.x);
+    minY = Math.min(minY, rect.y);
+    maxX = Math.max(maxX, rect.x + rect.width);
+    maxY = Math.max(maxY, rect.y + rect.height);
+  }
+
+  return {
+    x: minX,
+    y: minY,
+    width: maxX - minX,
+    height: maxY - minY,
+  };
+}
+
+/**
+ * Create a canvas font string from font style
+ */
+export function createFontString(
+  fontSize: number,
+  fontWeight: string | number,
+  fontFamily: string
+): string {
+  return `${fontWeight} ${fontSize}px ${fontFamily}`;
+}
+
+/**
+ * Walk tree depth-first
+ */
+export function walkTree(node: VirtualNode, callback: (node: VirtualNode) => void): void {
+  callback(node);
+  for (const child of node.children) {
+    walkTree(child, callback);
+  }
+}
+
+/**
+ * Find node by ID in tree
+ */
+export function findNodeById(root: VirtualNode, id: string): VirtualNode | null {
+  if (root.id === id) return root;
+
+  for (const child of root.children) {
+    const found = findNodeById(child, id);
+    if (found) return found;
+  }
+
+  return null;
+}
+
+/**
+ * Get absolute bounds of node (including transformations)
+ */
+export function getAbsoluteBounds(node: VirtualNode): Rectangle | null {
+  if (!node.layout) return null;
+
+  let x = node.layout.x;
+  let y = node.layout.y;
+
+  // Walk up tree to accumulate offsets
+  let current = node.parent;
+  while (current && current.layout) {
+    x += current.layout.contentX;
+    y += current.layout.contentY;
+    current = current.parent;
+  }
+
+  return {
+    x,
+    y,
+    width: node.layout.width,
+    height: node.layout.height,
+  };
+}
+
+
+
+
+
+
+
+
+
+
+

package/src/dom/README.md

@@ -0,0 +1,265 @@
+# DOM Renderer
+
+Browser-only module for rendering Hypen UI to the DOM.
+
+## Structure
+
+```
+src/dom/
+├── index.ts                 # Main exports
+├── renderer.ts              # DOMRenderer class
+├── events.ts                # Event management
+├── components/              # Component handlers
+│   ├── index.ts            # Component registry
+│   ├── column.ts
+│   ├── row.ts
+│   ├── text.ts
+│   ├── image.ts
+│   ├── button.ts
+│   ├── container.ts
+│   ├── center.ts
+│   ├── list.ts
+│   └── input.ts
+├── applicators/             # Style applicators
+│   ├── index.ts            # Applicator registry
+│   ├── padding.ts
+│   ├── margin.ts
+│   ├── color.ts
+│   ├── border.ts
+│   ├── size.ts
+│   ├── font.ts
+│   └── layout.ts
+└── canvas/                  # Canvas support
+    └── index.ts            # Canvas component & applicators
+```
+
+## Usage
+
+### Browser Import
+
+```typescript
+import { Engine, app, HypenModuleInstance } from "@hypen/core";
+import { DOMRenderer } from "@hypen/core/dom";
+
+const engine = new Engine();
+await engine.init();
+
+const renderer = new DOMRenderer(document.body, engine);
+engine.setRenderCallback((patches) => {
+  renderer.applyPatches(patches);
+});
+```
+
+### Server Import
+
+```typescript
+// This will fail in Node.js/Bun (no DOM)
+import { DOMRenderer } from "@hypen/core/dom"; // ❌ Error
+
+// Use server-safe renderer instead
+import { ConsoleRenderer } from "@hypen/core"; // ✅ Works
+```
+
+## Components
+
+All components are registered by default:
+
+- **Column** - Vertical flex container
+- **Row** - Horizontal flex container
+- **Text** - Text content
+- **Image** - Image element
+- **Button** - Button element
+- **Container/Box** - Generic div
+- **Center** - Centered content
+- **List** - Scrollable stack with gap
+- **Input** - Input field
+- **Canvas** - Canvas element
+
+### Custom Components
+
+```typescript
+const renderer = new DOMRenderer(document.body, engine);
+const registry = renderer.getComponentRegistry();
+
+registry.register("mycomponent", {
+  create(): HTMLElement {
+    const el = document.createElement("div");
+    el.classList.add("my-component");
+    return el;
+  },
+  applyProps(el: HTMLElement, props: Record<string, any>): void {
+    if (props.title) {
+      el.setAttribute("title", props.title);
+    }
+  },
+});
+```
+
+## Applicators
+
+Style applicators are registered by default:
+
+**Spacing:**
+- `padding` - All sides or {left, right, top, bottom}
+- `margin` - All sides or {left, right, top, bottom}
+- `gap` - Flex/grid gap
+
+**Colors:**
+- `color` - Text color
+- `backgroundColor` - Background color
+- `borderColor` - Border color
+- `opacity` - Opacity (0-1)
+
+**Border:**
+- `borderWidth` - Border width
+- `borderStyle` - Border style (solid, dashed, etc.)
+- `borderRadius` - Border radius
+
+**Size:**
+- `width`, `height` - Element size
+- `minWidth`, `minHeight` - Minimum size
+- `maxWidth`, `maxHeight` - Maximum size
+
+**Font:**
+- `fontSize` - Font size
+- `fontWeight` - Font weight (normal, bold, 100-900)
+- `fontFamily` - Font family
+- `textAlign` - Text alignment
+- `lineHeight` - Line height
+
+**Layout (Flexbox):**
+- `horizontalAlign` - justify-content
+- `verticalAlign` - align-items
+- `flex` - Flex shorthand
+- `flexGrow`, `flexShrink` - Flex properties
+
+**Misc:**
+- `cursor` - Cursor style
+- `overflow` - Overflow behavior
+
+### Custom Applicators
+
+```typescript
+const renderer = new DOMRenderer(document.body, engine);
+const applicators = renderer.getApplicatorRegistry();
+
+applicators.register("shadow", (el, value) => {
+  el.style.boxShadow = `0 ${value}px ${value * 2}px rgba(0,0,0,0.2)`;
+});
+```
+
+## Events
+
+Events are automatically wired up when patches include `attachEvent`:
+
+```typescript
+// Hypen DSL:
+Button("@actions.increment") { Text("+") }
+
+// Becomes:
+// 1. Create button
+// 2. Attach "click" event
+// 3. On click, dispatch "increment" action to engine
+```
+
+Supported events:
+- Mouse: `click`, `dblclick`, `mousedown`, `mouseup`, `mouseenter`, `mouseleave`
+- Keyboard: `keydown`, `keyup`, `keypress`
+- Input: `input`, `change`, `focus`, `blur`
+- Form: `submit`
+- Touch: `touchstart`, `touchend`, `touchmove`
+
+Event data includes:
+- `type` - Event type
+- `timestamp` - When it occurred
+- `clientX`, `clientY` - Mouse position (mouse events)
+- `key`, `code` - Key info (keyboard events)
+- `value` - Input value (form elements)
+
+## Canvas
+
+Canvas components have special applicators for drawing:
+
+```typescript
+// Register canvas applicators
+const renderer = new DOMRenderer(document.body, engine);
+const applicators = renderer.getApplicatorRegistry();
+
+// Canvas-specific applicators
+applicators.register("fillStyle", (el, value) => {
+  const canvas = el as HTMLCanvasElement;
+  const ctx = canvas.getContext("2d");
+  if (ctx) ctx.fillStyle = value;
+});
+```
+
+Built-in canvas applicators:
+- `fillStyle` - Fill color
+- `strokeStyle` - Stroke color
+- `lineWidth` - Line width
+
+## Extensibility
+
+### Adding a New Component
+
+1. Create `src/dom/components/mycomponent.ts`:
+
+```typescript
+import type { ComponentHandler } from "./index.js";
+
+export const myComponentHandler: ComponentHandler = {
+  create(): HTMLElement {
+    const el = document.createElement("div");
+    el.dataset.hypenType = "mycomponent";
+    return el;
+  },
+  applyProps(el, props) {
+    // Handle props
+  },
+};
+```
+
+2. Register in `src/dom/components/index.ts`:
+
+```typescript
+const { myComponentHandler } = require("./mycomponent.js");
+this.register("mycomponent", myComponentHandler);
+```
+
+### Adding a New Applicator
+
+1. Create `src/dom/applicators/myapplicator.ts`:
+
+```typescript
+import type { ApplicatorHandler } from "./index.js";
+
+export const myApplicatorHandler: ApplicatorHandler = (el, value) => {
+  el.style.someProperty = String(value);
+};
+```
+
+2. Register in `src/dom/applicators/index.ts`:
+
+```typescript
+const { myApplicatorHandler } = require("./myapplicator.js");
+this.register("myapplicator", myApplicatorHandler);
+```
+
+## Performance
+
+- **Minimal DOM operations** - Only patches are applied
+- **Efficient updates** - Only changed props are updated
+- **Event delegation** - Events managed per-element
+- **Keyed reconciliation** - Use `key` prop for lists
+
+## Browser Support
+
+- Modern browsers with ES6+ support
+- Requires: `Proxy`, `Map`, `Set`, `Promise`
+- No IE11 support (use Babel + polyfills if needed)
+
+## See Also
+
+- [Main README](../../README.md) - Full SDK documentation
+- [REFACTORING.md](../../REFACTORING.md) - State management details
+- [IMPLEMENTATION.md](../../IMPLEMENTATION.md) - Implementation guide