@hypen-space/web 0.2.0

package/src/dom/applicators/index.ts

@@ -0,0 +1,354 @@
+/**
+ * Applicator Registry
+ *
+ * Handles style applicators (modifiers) for Hypen components
+ */
+
+export type ApplicatorHandler = (element: HTMLElement, value: any) => void;
+
+export class ApplicatorRegistry {
+  private handlers: Map<string, ApplicatorHandler> = new Map();
+  private elementState: WeakMap<HTMLElement, Map<string, any>> = new WeakMap();
+
+  constructor() {
+    this.registerDefaults();
+  }
+
+  /**
+   * Register an applicator handler
+   */
+  register(name: string, handler: ApplicatorHandler): void {
+    this.handlers.set(name, handler);
+  }
+
+  /**
+   * Apply an applicator to an element
+   */
+  apply(element: HTMLElement, name: string, value: any): void {
+    // Parse applicator metadata so we can normalize event arguments and retain legacy behavior
+    const { handlerName, argKey, aggregate, fallbackName } = this.parseApplicatorName(name);
+
+    const handler = this.handlers.get(handlerName);
+    const state = this.getElementState(element);
+    const previous = state.get(handlerName);
+
+    if (aggregate && argKey !== null) {
+      // Merge event payload updates with the previously applied arguments so handlers
+      // always receive the full payload object (prevents stale dispatch data)
+      const merged = this.mergeAggregateState(previous, argKey, this.normalizeValue(value));
+
+      state.set(handlerName, merged);
+
+      if (handler) {
+        handler(element, merged);
+      } else {
+        // Fallback: set as CSS property using the original name if no handler exists
+        this.setStyleProperty(element, fallbackName, value);
+      }
+      return;
+    }
+
+    if (handler) {
+      if (this.isEventApplicator(handlerName)) {
+        const normalizedValue = this.normalizeEventValue(previous, value);
+        state.set(handlerName, normalizedValue);
+        handler(element, normalizedValue);
+      } else {
+        state.set(handlerName, value);
+        handler(element, value);
+      }
+    } else {
+      // Fallback: set as CSS property
+      this.setStyleProperty(element, handlerName, value);
+    }
+  }
+
+  /**
+   * Parse applicator name to handle indexed and event argument formats
+   * e.g., "fontSize.0" -> { handlerName: "fontSize" }
+   *       "onClick.id" -> { handlerName: "onClick", aggregate: true, argKey: "id" }
+   * Keeps compound names like "padding.top" as-is so they can fall back to CSS.
+   */
+  private parseApplicatorName(name: string): {
+    handlerName: string;
+    argKey: string | null;
+    aggregate: boolean;
+    fallbackName: string;
+  } {
+    const dotIndex = name.indexOf('.');
+    if (dotIndex === -1) {
+      return { handlerName: name, argKey: null, aggregate: false, fallbackName: name };
+    }
+
+    const baseName = name.substring(0, dotIndex);
+    const argKey = name.substring(dotIndex + 1);
+
+    if (this.handlers.has(baseName) && this.isEventApplicator(baseName)) {
+      return { handlerName: baseName, argKey, aggregate: true, fallbackName: name };
+    }
+
+    if (/^\d+$/.test(argKey)) {
+      return { handlerName: baseName, argKey: null, aggregate: false, fallbackName: baseName };
+    }
+
+    return { handlerName: name, argKey: null, aggregate: false, fallbackName: name };
+  }
+
+  /**
+   * Get or initialize per-element applicator state used for merging event payloads
+   */
+  private getElementState(element: HTMLElement): Map<string, any> {
+    let state = this.elementState.get(element);
+    if (!state) {
+      state = new Map();
+      this.elementState.set(element, state);
+    }
+    return state;
+  }
+
+  /**
+   * Merge updated event argument into previously stored payload snapshot
+   */
+  private mergeAggregateState(previous: any, argKey: string, value: any): Record<string, any> {
+    const base: Record<string, any> = this.cloneAggregateState(previous);
+
+    if (value === undefined) {
+      delete base[argKey];
+    } else {
+      base[argKey] = value;
+    }
+
+    return base;
+  }
+
+  /**
+   * Convert stored state into a mutable payload object we can merge into
+   */
+  private cloneAggregateState(previous: any): Record<string, any> {
+    if (previous && typeof previous === "object" && !Array.isArray(previous)) {
+      return { ...previous };
+    }
+
+    if (typeof previous === "string") {
+      return { "0": previous };
+    }
+
+    return {};
+  }
+
+  /**
+   * Normalize event value updates so action payload arguments persist across SetProp orderings
+   */
+  private normalizeEventValue(previous: any, value: any): Record<string, any> {
+    const normalizedInput = this.normalizeValue(value);
+    const base = this.cloneAggregateState(previous);
+
+    if (normalizedInput && typeof normalizedInput === "object" && !Array.isArray(normalizedInput)) {
+      const next = { ...base, ...normalizedInput } as Record<string, any>;
+
+      if (!Object.prototype.hasOwnProperty.call(next, "0") && base["0"] !== undefined) {
+        next["0"] = base["0"];
+      }
+
+      return next;
+    }
+
+    if (normalizedInput !== undefined) {
+      base["0"] = normalizedInput;
+    }
+
+    return base;
+  }
+
+  /**
+   * Convert Maps (from WASM) and nested structures into plain JS values we can merge safely
+   */
+  private normalizeValue(value: any): any {
+    if (value instanceof Map) {
+      const obj: Record<string, any> = {};
+      for (const [key, val] of value.entries()) {
+        obj[key] = this.normalizeValue(val);
+      }
+      return obj;
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((item) => this.normalizeValue(item));
+    }
+
+    if (value && typeof value === "object") {
+      const obj: Record<string, any> = {};
+      for (const [key, val] of Object.entries(value)) {
+        obj[key] = this.normalizeValue(val);
+      }
+      return obj;
+    }
+
+    return value;
+  }
+
+  /**
+   * Determine if a handler name follows the event applicator naming convention
+   */
+  private isEventApplicator(name: string): boolean {
+    return /^on[A-Z]/.test(name);
+  }
+
+  /**
+   * Apply multiple applicators
+   */
+  applyAll(element: HTMLElement, applicators: Record<string, any>): void {
+    //console.log(`[ApplicatorRegistry] Applying applicators:`, applicators);
+
+    // Group applicators by their base name (treat applicators like components with arguments)
+    // e.g., "onClick.0", "onClick.id", "onClick.title" -> onClick: {0: ..., id: ..., title: ...}
+    const grouped = new Map<string, Record<string, any>>();
+
+    for (const [name, value] of Object.entries(applicators)) {
+      // Extract base name and argument key
+      const dotIndex = name.indexOf('.');
+      const baseName = dotIndex !== -1 ? name.substring(0, dotIndex) : name;
+      const argKey = dotIndex !== -1 ? name.substring(dotIndex + 1) : null;
+
+      if (!grouped.has(baseName)) {
+        grouped.set(baseName, {});
+      }
+
+      const args = grouped.get(baseName)!;
+      if (argKey !== null) {
+        // This is an argument (e.g., "onClick.0" or "onClick.id")
+        args[argKey] = value;
+      } else {
+        // This is a single-value applicator (e.g., "padding")
+        args['__value'] = value;
+      }
+    }
+
+    // Apply each applicator with its arguments
+    for (const [baseName, args] of grouped.entries()) {
+      // If it's a single value (either __value or just "0"), pass just the value
+      if (Object.keys(args).length === 1) {
+        if ('__value' in args) {
+          this.apply(element, baseName, args['__value']);
+        } else if ('0' in args) {
+          // Single positional argument (e.g., padding.0 -> just pass the value)
+          this.apply(element, baseName, args['0']);
+        } else {
+          // Single named argument? Pass the whole object
+          this.apply(element, baseName, args);
+        }
+      } else {
+        // Multiple arguments - pass the entire args object
+        this.apply(element, baseName, args);
+      }
+    }
+  }
+
+  /**
+   * Set a CSS property with automatic unit handling
+   */
+  private setStyleProperty(element: HTMLElement, name: string, value: any): void {
+    // Convert camelCase to kebab-case
+    const cssName = name.replace(/([A-Z])/g, "-$1").toLowerCase();
+
+    // Add units for numeric values on size properties
+    if (typeof value === "number" && this.needsUnit(cssName)) {
+      element.style.setProperty(cssName, `${value}px`);
+    } else {
+      element.style.setProperty(cssName, String(value));
+    }
+  }
+
+  /**
+   * Check if a property needs a unit
+   */
+  private needsUnit(prop: string): boolean {
+    const unitless = [
+      "opacity",
+      "z-index",
+      "font-weight",
+      "line-height",
+      "flex",
+      "flex-grow",
+      "flex-shrink",
+      "order",
+    ];
+    return !unitless.includes(prop);
+  }
+
+  /**
+   * Register default applicator handlers
+   */
+  private registerDefaults(): void {
+    const { paddingHandler } = require("./padding.js");
+    const { marginHandler } = require("./margin.js");
+    const { colorHandlers } = require("./color.js");
+    const { borderHandlers } = require("./border.js");
+    const { sizeHandlers } = require("./size.js");
+    const { fontHandlers } = require("./font.js");
+    const { layoutHandlers } = require("./layout.js");
+    const { eventHandlers } = require("./events.js");
+    const { typographyHandlers } = require("./typography.js");
+    const { transformHandlers } = require("./transform.js");
+    const { effectsHandlers } = require("./effects.js");
+    const { advancedLayoutHandlers } = require("./advanced-layout.js");
+    const { backgroundHandlers } = require("./background.js");
+    const { displayHandlers } = require("./display.js");
+    const { transitionHandlers } = require("./transition.js");
+
+    this.register("padding", paddingHandler);
+    this.register("margin", marginHandler);
+
+    for (const [name, handler] of Object.entries(colorHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(borderHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(sizeHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(fontHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(layoutHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(eventHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(typographyHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(transformHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(effectsHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(advancedLayoutHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(backgroundHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(displayHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+
+    for (const [name, handler] of Object.entries(transitionHandlers)) {
+      this.register(name, handler as ApplicatorHandler);
+    }
+  }
+}

package/src/dom/applicators/layout.ts

@@ -0,0 +1,92 @@
+/**
+ * Layout Applicators (Flexbox/Grid)
+ */
+
+import type { ApplicatorHandler } from "./index.js";
+
+export const layoutHandlers: Record<string, ApplicatorHandler> = {
+  // Unified alignment API - works for both Column and Row
+  verticalAlignment: (el, value) => {
+    const val = String(value);
+    // Check flex-direction to determine which CSS property to set
+    const flexDirection = getComputedStyle(el).flexDirection;
+    if (flexDirection === "column" || flexDirection === "column-reverse") {
+      // For column: vertical is the main axis (justify-content)
+      el.style.justifyContent = val;
+    } else {
+      // For row: vertical is the cross axis (align-items)
+      el.style.alignItems = val;
+    }
+  },
+
+  horizontalAlignment: (el, value) => {
+    const val = String(value);
+    // Check flex-direction to determine which CSS property to set
+    const flexDirection = getComputedStyle(el).flexDirection;
+    if (flexDirection === "column" || flexDirection === "column-reverse") {
+      // For column: horizontal is the cross axis (align-items)
+      el.style.alignItems = val;
+    } else {
+      // For row: horizontal is the main axis (justify-content)
+      el.style.justifyContent = val;
+    }
+  },
+
+  // Legacy aliases (kept for backward compatibility)
+  horizontalAlign: (el, value) => {
+    el.style.justifyContent = String(value);
+  },
+
+  verticalAlign: (el, value) => {
+    el.style.alignItems = String(value);
+  },
+
+  gap: (el, value) => {
+    el.style.gap = typeof value === "number" ? `${value}px` : String(value);
+  },
+
+  // weight: unified cross-platform API (same as flex)
+  // Use .weight(1) to make element take remaining space in Row/Column
+  weight: (el, value) => {
+    el.style.flex = String(value);
+  },
+
+  // flex: CSS flex shorthand (kept for CSS compatibility)
+  flex: (el, value) => {
+    el.style.flex = String(value);
+  },
+
+  flexGrow: (el, value) => {
+    el.style.flexGrow = String(value);
+  },
+
+  flexShrink: (el, value) => {
+    el.style.flexShrink = String(value);
+  },
+
+  cursor: (el, value) => {
+    el.style.cursor = String(value);
+  },
+
+  overflow: (el, value) => {
+    el.style.overflow = String(value);
+  },
+
+  scrollable: (el, value) => {
+    if (value === true || value === "true") {
+      el.style.overflow = "auto";
+    } else if (value === false || value === "false") {
+      el.style.overflow = "hidden";
+    } else if (value === "vertical") {
+      el.style.overflowX = "hidden";
+      el.style.overflowY = "auto";
+    } else if (value === "horizontal") {
+      el.style.overflowX = "auto";
+      el.style.overflowY = "hidden";
+    } else if (value === "both") {
+      el.style.overflow = "auto";
+    } else {
+      el.style.overflow = String(value);
+    }
+  },
+};

package/src/dom/applicators/margin.ts

@@ -0,0 +1,18 @@
+/**
+ * Margin Applicator
+ */
+
+import type { ApplicatorHandler } from "./index.js";
+
+export const marginHandler: ApplicatorHandler = (el, value) => {
+  if (typeof value === "number") {
+    el.style.margin = `${value}px`;
+  } else if (typeof value === "object") {
+    if (value.left !== undefined) el.style.marginLeft = `${value.left}px`;
+    if (value.right !== undefined) el.style.marginRight = `${value.right}px`;
+    if (value.top !== undefined) el.style.marginTop = `${value.top}px`;
+    if (value.bottom !== undefined) el.style.marginBottom = `${value.bottom}px`;
+  } else {
+    el.style.margin = String(value);
+  }
+};

package/src/dom/applicators/padding.ts

@@ -0,0 +1,18 @@
+/**
+ * Padding Applicator
+ */
+
+import type { ApplicatorHandler } from "./index.js";
+
+export const paddingHandler: ApplicatorHandler = (el, value) => {
+  if (typeof value === "number") {
+    el.style.padding = `${value}px`;
+  } else if (typeof value === "object") {
+    if (value.left !== undefined) el.style.paddingLeft = `${value.left}px`;
+    if (value.right !== undefined) el.style.paddingRight = `${value.right}px`;
+    if (value.top !== undefined) el.style.paddingTop = `${value.top}px`;
+    if (value.bottom !== undefined) el.style.paddingBottom = `${value.bottom}px`;
+  } else {
+    el.style.padding = String(value);
+  }
+};

package/src/dom/applicators/size.ts

@@ -0,0 +1,31 @@
+/**
+ * Size Applicators
+ */
+
+import type { ApplicatorHandler } from "./index.js";
+
+export const sizeHandlers: Record<string, ApplicatorHandler> = {
+  width: (el, value) => {
+    el.style.width = typeof value === "number" ? `${value}px` : String(value);
+  },
+
+  height: (el, value) => {
+    el.style.height = typeof value === "number" ? `${value}px` : String(value);
+  },
+
+  minWidth: (el, value) => {
+    el.style.minWidth = typeof value === "number" ? `${value}px` : String(value);
+  },
+
+  minHeight: (el, value) => {
+    el.style.minHeight = typeof value === "number" ? `${value}px` : String(value);
+  },
+
+  maxWidth: (el, value) => {
+    el.style.maxWidth = typeof value === "number" ? `${value}px` : String(value);
+  },
+
+  maxHeight: (el, value) => {
+    el.style.maxHeight = typeof value === "number" ? `${value}px` : String(value);
+  },
+};

package/src/dom/applicators/transform.ts

@@ -0,0 +1,93 @@
+/**
+ * Transform Applicators
+ */
+
+import type { ApplicatorHandler } from "./index.js";
+
+export const transformHandlers: Record<string, ApplicatorHandler> = {
+  transform: (el, value) => {
+    el.style.transform = String(value);
+  },
+
+  transformOrigin: (el, value) => {
+    el.style.transformOrigin = String(value);
+  },
+
+  translateX: (el, value) => {
+    const current = el.style.transform || "";
+    const val = typeof value === "number" ? `${value}px` : String(value);
+    el.style.transform = current ? `${current} translateX(${val})` : `translateX(${val})`;
+  },
+
+  translateY: (el, value) => {
+    const current = el.style.transform || "";
+    const val = typeof value === "number" ? `${value}px` : String(value);
+    el.style.transform = current ? `${current} translateY(${val})` : `translateY(${val})`;
+  },
+
+  translateZ: (el, value) => {
+    const current = el.style.transform || "";
+    const val = typeof value === "number" ? `${value}px` : String(value);
+    el.style.transform = current ? `${current} translateZ(${val})` : `translateZ(${val})`;
+  },
+
+  rotate: (el, value) => {
+    const current = el.style.transform || "";
+    const val = String(value);
+    el.style.transform = current ? `${current} rotate(${val})` : `rotate(${val})`;
+  },
+
+  rotateX: (el, value) => {
+    const current = el.style.transform || "";
+    const val = String(value);
+    el.style.transform = current ? `${current} rotateX(${val})` : `rotateX(${val})`;
+  },
+
+  rotateY: (el, value) => {
+    const current = el.style.transform || "";
+    const val = String(value);
+    el.style.transform = current ? `${current} rotateY(${val})` : `rotateY(${val})`;
+  },
+
+  rotateZ: (el, value) => {
+    const current = el.style.transform || "";
+    const val = String(value);
+    el.style.transform = current ? `${current} rotateZ(${val})` : `rotateZ(${val})`;
+  },
+
+  scale: (el, value) => {
+    const current = el.style.transform || "";
+    el.style.transform = current ? `${current} scale(${value})` : `scale(${value})`;
+  },
+
+  scaleX: (el, value) => {
+    const current = el.style.transform || "";
+    el.style.transform = current ? `${current} scaleX(${value})` : `scaleX(${value})`;
+  },
+
+  scaleY: (el, value) => {
+    const current = el.style.transform || "";
+    el.style.transform = current ? `${current} scaleY(${value})` : `scaleY(${value})`;
+  },
+
+  skew: (el, value) => {
+    const current = el.style.transform || "";
+    el.style.transform = current ? `${current} skew(${value})` : `skew(${value})`;
+  },
+
+  skewX: (el, value) => {
+    const current = el.style.transform || "";
+    el.style.transform = current ? `${current} skewX(${value})` : `skewX(${value})`;
+  },
+
+  skewY: (el, value) => {
+    const current = el.style.transform || "";
+    el.style.transform = current ? `${current} skewY(${value})` : `skewY(${value})`;
+  },
+
+  perspective: (el, value) => {
+    el.style.perspective = typeof value === "number" ? `${value}px` : String(value);
+  },
+};
+
+

package/src/dom/applicators/transition.ts

@@ -0,0 +1,65 @@
+/**
+ * Transition and Animation Applicators
+ */
+
+import type { ApplicatorHandler } from "./index.js";
+
+export const transitionHandlers: Record<string, ApplicatorHandler> = {
+  transition: (el, value) => {
+    el.style.transition = String(value);
+  },
+
+  transitionProperty: (el, value) => {
+    el.style.transitionProperty = String(value);
+  },
+
+  transitionDuration: (el, value) => {
+    el.style.transitionDuration = String(value);
+  },
+
+  transitionTimingFunction: (el, value) => {
+    el.style.transitionTimingFunction = String(value);
+  },
+
+  transitionDelay: (el, value) => {
+    el.style.transitionDelay = String(value);
+  },
+
+  animation: (el, value) => {
+    el.style.animation = String(value);
+  },
+
+  animationName: (el, value) => {
+    el.style.animationName = String(value);
+  },
+
+  animationDuration: (el, value) => {
+    el.style.animationDuration = String(value);
+  },
+
+  animationTimingFunction: (el, value) => {
+    el.style.animationTimingFunction = String(value);
+  },
+
+  animationDelay: (el, value) => {
+    el.style.animationDelay = String(value);
+  },
+
+  animationIterationCount: (el, value) => {
+    el.style.animationIterationCount = String(value);
+  },
+
+  animationDirection: (el, value) => {
+    el.style.animationDirection = String(value);
+  },
+
+  animationFillMode: (el, value) => {
+    el.style.animationFillMode = String(value);
+  },
+
+  animationPlayState: (el, value) => {
+    el.style.animationPlayState = String(value);
+  },
+};
+
+