@velumo/renderer-dom 0.1.0-beta.0

package/src/layout-renderer.ts

@@ -0,0 +1,721 @@
+export interface LayoutRendererElement {
+  setAttribute(name: string, value: string): void;
+  appendChild(child: LayoutRendererElement): void;
+  readonly style?: { setProperty(name: string, value: string): void };
+  textContent: string;
+  parentNode?: unknown;
+}
+
+export interface LayoutRendererFactories {
+  createElement(tagName: string): LayoutRendererElement;
+  createElementNS?(namespace: string, tagName: string): LayoutRendererElement;
+  setStyleProperty(
+    element: LayoutRendererElement,
+    property: string,
+    value: string,
+  ): void;
+}
+
+export function renderLayoutNode(
+  node: unknown,
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  if (!isRecord(node) || typeof node.kind !== "string") {
+    return unknownLayoutElement(factories);
+  }
+
+  switch (node.kind) {
+    case "stack":
+      return renderLayoutContainer(node, "stack", factories);
+    case "grid":
+      return renderGridLayout(node, factories);
+    case "split":
+      return renderSplitLayout(node, factories);
+    case "hero":
+      return renderLayoutContainer(node, "hero", factories);
+    case "frame":
+      return renderFrameLayout(node, factories);
+    case "heading":
+      return renderHeadingElement(node, factories);
+    case "text":
+      return renderTextElement(node, factories);
+    case "media":
+      return renderMediaElement(node, factories);
+    case "callout":
+      return renderCalloutElement(node, factories);
+    case "canvas":
+      return renderCanvasLayout(node, factories);
+    case "animate":
+      return renderAnimateLayout(node, factories);
+    case "code":
+      return renderCodeElement(node, factories);
+    case "icon":
+      return renderIconElement(node, factories);
+    case "badge":
+      return renderBadgeElement(node, factories);
+    case "rule":
+      return renderRuleElement(node, factories);
+    case "table":
+      return renderTableLayout(node, factories);
+    case "connector":
+      return renderConnectorElement(node, factories);
+    default:
+      return unknownLayoutElement(factories);
+  }
+}
+
+function renderLayoutContainer(
+  node: {
+    readonly children?: unknown;
+    readonly justify?: unknown;
+    readonly align?: unknown;
+    readonly direction?: unknown;
+  },
+  kind: string,
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("div");
+  element.setAttribute("data-velumo-layout", kind);
+  if (
+    typeof (node as { readonly direction?: unknown }).direction === "string"
+  ) {
+    element.setAttribute(
+      "data-velumo-stack-direction",
+      (node as { readonly direction: string }).direction,
+    );
+  }
+  if (typeof (node as { readonly justify?: unknown }).justify === "string") {
+    element.setAttribute(
+      "data-velumo-stack-justify",
+      (node as { readonly justify: string }).justify,
+    );
+  }
+  if (typeof (node as { readonly align?: unknown }).align === "string") {
+    element.setAttribute(
+      "data-velumo-stack-align",
+      (node as { readonly align: string }).align,
+    );
+  }
+  appendLayoutChildren(element, node.children, factories);
+  return element;
+}
+
+function renderGridLayout(
+  node: {
+    readonly children?: unknown;
+    readonly columns?: unknown;
+    readonly rows?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = renderLayoutContainer(node, "grid", factories);
+
+  if (typeof node.columns === "number") {
+    factories.setStyleProperty(
+      element,
+      "--velumo-layout-columns",
+      String(node.columns),
+    );
+  }
+
+  if (typeof node.rows === "number") {
+    factories.setStyleProperty(
+      element,
+      "--velumo-layout-rows",
+      String(node.rows),
+    );
+  }
+
+  return element;
+}
+
+function renderSplitLayout(
+  node: {
+    readonly children?: unknown;
+    readonly weights?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = renderLayoutContainer(node, "split", factories);
+
+  if (Array.isArray(node.weights)) {
+    factories.setStyleProperty(
+      element,
+      "--velumo-layout-weights",
+      node.weights.join(" "),
+    );
+  }
+
+  return element;
+}
+
+function renderFrameLayout(
+  node: {
+    readonly children?: unknown;
+    readonly meta?: unknown;
+    readonly tone?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = renderLayoutContainer(node, "frame", factories);
+
+  if (typeof node.tone === "string") {
+    element.setAttribute("data-velumo-frame-tone", node.tone);
+  }
+
+  if (isRecord(node.meta)) {
+    if (typeof node.meta.safeArea === "string") {
+      element.setAttribute("data-velumo-safe-area", node.meta.safeArea);
+    }
+
+    if (typeof node.meta.cameraHint === "string") {
+      element.setAttribute("data-velumo-camera-hint", node.meta.cameraHint);
+    }
+
+    if (typeof node.meta.depth === "number") {
+      factories.setStyleProperty(
+        element,
+        "--velumo-layout-depth",
+        String(node.meta.depth),
+      );
+    }
+  }
+
+  return element;
+}
+
+function applyTextStyleAttributes(
+  element: LayoutRendererElement,
+  node: {
+    readonly transform?: unknown;
+    readonly decoration?: unknown;
+    readonly glow?: unknown;
+    readonly tone?: unknown;
+  },
+): void {
+  if (typeof node.transform === "string") {
+    element.setAttribute("data-velumo-text-transform", node.transform);
+  }
+  if (typeof node.decoration === "string") {
+    element.setAttribute("data-velumo-text-decoration", node.decoration);
+  }
+  if (node.glow === true) {
+    element.setAttribute("data-velumo-text-glow", "");
+  }
+  if (typeof node.tone === "string") {
+    element.setAttribute("data-velumo-text-tone", node.tone);
+  }
+}
+
+function renderHeadingElement(
+  node: {
+    readonly text?: unknown;
+    readonly size?: unknown;
+    readonly level?: unknown;
+    readonly transform?: unknown;
+    readonly decoration?: unknown;
+    readonly glow?: unknown;
+    readonly tone?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const level =
+    typeof node.level === "number" &&
+    Number.isInteger(node.level) &&
+    node.level >= 1 &&
+    node.level <= 6
+      ? node.level
+      : 1;
+  const element = factories.createElement(`h${level}`);
+  element.textContent = String(node.text ?? "");
+  element.setAttribute("data-velumo-element", "heading");
+  if (typeof node.size === "string") {
+    element.setAttribute("data-velumo-heading-size", node.size);
+  }
+  applyTextStyleAttributes(element, node);
+  return element;
+}
+
+function renderTextElement(
+  node: {
+    readonly text?: unknown;
+    readonly variant?: unknown;
+    readonly transform?: unknown;
+    readonly decoration?: unknown;
+    readonly glow?: unknown;
+    readonly tone?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("p");
+  element.textContent = String(node.text ?? "");
+  element.setAttribute("data-velumo-element", "text");
+
+  if (typeof node.variant === "string") {
+    element.setAttribute("data-velumo-text-variant", node.variant);
+  }
+
+  applyTextStyleAttributes(element, node);
+  return element;
+}
+
+function renderMediaElement(
+  node: {
+    readonly src?: unknown;
+    readonly alt?: unknown;
+    readonly fit?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("img");
+  element.setAttribute("data-velumo-element", "media");
+  element.setAttribute("src", String(node.src ?? ""));
+  element.setAttribute("alt", String(node.alt ?? ""));
+
+  if (typeof node.fit === "string") {
+    element.setAttribute("data-velumo-media-fit", node.fit);
+  }
+
+  return element;
+}
+
+function renderCalloutElement(
+  node: { readonly children?: unknown; readonly tone?: unknown },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("aside");
+  element.setAttribute("data-velumo-element", "callout");
+
+  if (typeof node.tone === "string") {
+    element.setAttribute("data-velumo-callout-tone", node.tone);
+  }
+
+  appendLayoutChildren(element, node.children, factories);
+  return element;
+}
+
+function appendLayoutChildren(
+  parent: LayoutRendererElement,
+  children: unknown,
+  factories: LayoutRendererFactories,
+): void {
+  if (!Array.isArray(children)) {
+    return;
+  }
+
+  for (const child of children) {
+    parent.appendChild(renderLayoutNode(child, factories));
+  }
+}
+
+function renderCanvasLayout(
+  node: { readonly items?: unknown },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("div");
+  element.setAttribute("data-velumo-layout", "canvas");
+  factories.setStyleProperty(element, "position", "relative");
+  factories.setStyleProperty(element, "flex", "1");
+  factories.setStyleProperty(element, "min-height", "0");
+  factories.setStyleProperty(element, "width", "100%");
+  // height:100% fills any definite-height parent (grid item, spatial world);
+  // in a flex column flex-basis:0% from flex:1 overrides height so the canvas
+  // still fills remaining space — no overlap regression since it is in-flow.
+  factories.setStyleProperty(element, "height", "100%");
+
+  if (Array.isArray(node.items)) {
+    for (const item of node.items) {
+      if (!isRecord(item)) {
+        continue;
+      }
+      const slot = factories.createElement("div");
+      slot.setAttribute("data-velumo-canvas-item", "");
+      factories.setStyleProperty(slot, "position", "absolute");
+      if (typeof item.x === "number") {
+        factories.setStyleProperty(slot, "left", `${item.x}%`);
+      }
+      if (typeof item.y === "number") {
+        factories.setStyleProperty(slot, "top", `${item.y}%`);
+      }
+      if (typeof item.width === "number") {
+        factories.setStyleProperty(slot, "width", `${item.width}%`);
+      }
+      if (typeof item.height === "number") {
+        factories.setStyleProperty(slot, "height", `${item.height}%`);
+      }
+      slot.appendChild(renderLayoutNode(item.child, factories));
+      element.appendChild(slot);
+    }
+  }
+
+  return element;
+}
+
+function renderAnimateLayout(
+  node: {
+    readonly name?: unknown;
+    readonly delay?: unknown;
+    readonly duration?: unknown;
+    readonly easing?: unknown;
+    readonly child?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("div");
+  element.setAttribute("data-velumo-layout", "animate");
+  if (typeof node.name === "string") {
+    element.setAttribute("data-velumo-animation", node.name);
+  }
+  if (typeof node.delay === "number") {
+    factories.setStyleProperty(
+      element,
+      "--velumo-animation-delay",
+      `${node.delay}s`,
+    );
+  }
+  if (typeof node.duration === "number") {
+    factories.setStyleProperty(
+      element,
+      "--velumo-animation-duration",
+      `${node.duration}s`,
+    );
+  }
+  if (typeof node.easing === "string") {
+    factories.setStyleProperty(
+      element,
+      "--velumo-animation-easing",
+      node.easing,
+    );
+  }
+  element.appendChild(renderLayoutNode(node.child, factories));
+  return element;
+}
+
+function renderCodeElement(
+  node: { readonly lines?: unknown },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("pre");
+  element.setAttribute("data-velumo-element", "code");
+  const lines = Array.isArray(node.lines) ? node.lines : [];
+  lines.forEach((line, lineIndex) => {
+    if (Array.isArray(line)) {
+      for (const tok of line) {
+        if (!isRecord(tok)) {
+          continue;
+        }
+        const span = factories.createElement("span");
+        span.setAttribute(
+          "data-velumo-token",
+          typeof tok.kind === "string" ? tok.kind : "plain",
+        );
+        span.textContent = String(tok.text ?? "");
+        element.appendChild(span);
+      }
+    }
+    if (lineIndex < lines.length - 1) {
+      const newline = factories.createElement("span");
+      newline.textContent = "\n";
+      element.appendChild(newline);
+    }
+  });
+  return element;
+}
+
+function renderIconElement(
+  node: {
+    readonly name?: unknown;
+    readonly tone?: unknown;
+    readonly label?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("span");
+  element.setAttribute("data-velumo-element", "icon");
+  element.setAttribute(
+    "data-velumo-icon",
+    typeof node.name === "string" ? node.name : "dot",
+  );
+  if (typeof node.tone === "string") {
+    element.setAttribute("data-velumo-text-tone", node.tone);
+  }
+  if (typeof node.label === "string" && node.label.length > 0) {
+    element.setAttribute("role", "img");
+    element.setAttribute("aria-label", node.label);
+  } else {
+    element.setAttribute("aria-hidden", "true");
+  }
+  return element;
+}
+
+function renderBadgeElement(
+  node: {
+    readonly text?: unknown;
+    readonly tone?: unknown;
+    readonly variant?: unknown;
+    readonly dot?: unknown;
+    readonly mono?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("span");
+  element.setAttribute("data-velumo-element", "badge");
+  if (typeof node.tone === "string") {
+    element.setAttribute("data-velumo-badge-tone", node.tone);
+  }
+  if (typeof node.variant === "string") {
+    element.setAttribute("data-velumo-badge-variant", node.variant);
+  }
+  if (node.mono === true) {
+    element.setAttribute("data-velumo-badge-mono", "");
+  }
+  if (typeof node.dot === "string") {
+    const dot = factories.createElement("span");
+    dot.setAttribute("data-velumo-badge-dot", node.dot);
+    element.appendChild(dot);
+  }
+  const label = factories.createElement("span");
+  label.textContent = String(node.text ?? "");
+  element.appendChild(label);
+  return element;
+}
+
+function renderRuleElement(
+  node: {
+    readonly length?: unknown;
+    readonly thickness?: unknown;
+    readonly tone?: unknown;
+    readonly gradient?: unknown;
+    readonly radius?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("span");
+  element.setAttribute("data-velumo-element", "rule");
+  const width =
+    typeof node.length === "number"
+      ? `${node.length}px`
+      : typeof node.length === "string"
+        ? node.length
+        : "100%";
+  const height =
+    typeof node.thickness === "number" ? `${node.thickness}px` : "2px";
+  const radius = typeof node.radius === "number" ? `${node.radius}px` : "999px";
+  factories.setStyleProperty(element, "width", width);
+  factories.setStyleProperty(element, "height", height);
+  factories.setStyleProperty(element, "border-radius", radius);
+  if (Array.isArray(node.gradient) && node.gradient.length === 2) {
+    const [from, to] = node.gradient;
+    element.setAttribute(
+      "data-velumo-rule-gradient",
+      `${String(from)} ${String(to)}`,
+    );
+    factories.setStyleProperty(
+      element,
+      "--velumo-rule-from",
+      `var(--velumo-tone-${String(from)})`,
+    );
+    factories.setStyleProperty(
+      element,
+      "--velumo-rule-to",
+      `var(--velumo-tone-${String(to)})`,
+    );
+  } else if (typeof node.tone === "string") {
+    element.setAttribute("data-velumo-rule-tone", node.tone);
+  }
+  return element;
+}
+
+function renderTableLayout(
+  node: { readonly columns?: unknown; readonly rows?: unknown },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const columns = Array.isArray(node.columns) ? node.columns : [];
+  const element = factories.createElement("div");
+  element.setAttribute("data-velumo-layout", "table");
+  element.setAttribute("role", "table");
+  const weights = columns
+    .map((c) => (isRecord(c) && typeof c.weight === "number" ? c.weight : 1))
+    .join("fr ");
+  factories.setStyleProperty(
+    element,
+    "--velumo-table-columns",
+    columns.length > 0 ? `${weights}fr` : "1fr",
+  );
+
+  const applyColAttrs = (
+    cell: LayoutRendererElement,
+    column: unknown,
+  ): void => {
+    if (!isRecord(column)) {
+      return;
+    }
+    if (column.emphasis === true) {
+      cell.setAttribute("data-velumo-col-emphasis", "");
+    }
+    if (typeof column.align === "string") {
+      cell.setAttribute("data-velumo-col-align", column.align);
+    }
+  };
+
+  const hasHeader = columns.some((c) => isRecord(c) && c.header !== undefined);
+  if (hasHeader) {
+    const headRow = factories.createElement("div");
+    headRow.setAttribute("role", "row");
+    headRow.setAttribute("data-velumo-table-head", "");
+    columns.forEach((column) => {
+      const cell = factories.createElement("div");
+      cell.setAttribute("role", "columnheader");
+      applyColAttrs(cell, column);
+      if (isRecord(column) && column.header !== undefined) {
+        cell.appendChild(renderLayoutNode(column.header, factories));
+      }
+      headRow.appendChild(cell);
+    });
+    element.appendChild(headRow);
+  }
+
+  const body = factories.createElement("div");
+  body.setAttribute("role", "rowgroup");
+  const rows = Array.isArray(node.rows) ? node.rows : [];
+  for (const row of rows) {
+    const rowEl = factories.createElement("div");
+    rowEl.setAttribute("role", "row");
+    const cells = Array.isArray(row) ? row.slice(0, columns.length) : [];
+    cells.forEach((cellNode, cellIndex) => {
+      const cell = factories.createElement("div");
+      cell.setAttribute("role", "cell");
+      applyColAttrs(cell, columns[cellIndex]);
+      cell.appendChild(renderLayoutNode(cellNode, factories));
+      rowEl.appendChild(cell);
+    });
+    body.appendChild(rowEl);
+  }
+  element.appendChild(body);
+  return element;
+}
+
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+
+function connectorMarkerId(node: {
+  readonly from?: unknown;
+  readonly to?: unknown;
+  readonly control?: unknown;
+  readonly arrow?: unknown;
+  readonly dashed?: unknown;
+  readonly tone?: unknown;
+}): string {
+  // Deterministic, collision-resistant id from all style-bearing fields so that
+  // two connectors sharing endpoints but differing in tone/arrow/dashed/control
+  // receive distinct marker ids (inline-SVG ids are document-global).
+  const pt = (p: unknown): string =>
+    isRecord(p) ? `${String(p.x)}_${String(p.y)}` : "x";
+  const parts = [
+    pt(node.from),
+    pt(node.to),
+    isRecord(node.control) ? pt(node.control) : "noctl",
+    typeof node.arrow === "string" ? node.arrow : "none",
+    node.dashed === true ? "d" : "s",
+    typeof node.tone === "string" ? node.tone : "default",
+  ].join("-");
+  return `velumo-arrow-${parts}`.replace(/[^a-zA-Z0-9_-]/g, "");
+}
+
+function renderConnectorElement(
+  node: {
+    readonly from?: unknown;
+    readonly to?: unknown;
+    readonly control?: unknown;
+    readonly arrow?: unknown;
+    readonly dashed?: unknown;
+    readonly tone?: unknown;
+  },
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const create = (tag: string): LayoutRendererElement =>
+    factories.createElementNS
+      ? factories.createElementNS(SVG_NAMESPACE, tag)
+      : factories.createElement(tag);
+
+  const svg = create("svg");
+  svg.setAttribute("data-velumo-element", "connector");
+  svg.setAttribute("viewBox", "0 0 100 100");
+  svg.setAttribute("preserveAspectRatio", "none");
+  svg.setAttribute("width", "100%");
+  svg.setAttribute("height", "100%");
+  svg.setAttribute("aria-hidden", "true");
+  if (typeof node.tone === "string") {
+    svg.setAttribute("data-velumo-text-tone", node.tone);
+  }
+
+  // Guard against non-finite coordinates (e.g. NaN from non-numeric input) so
+  // the path data attribute is always well-formed.
+  const num = (v: unknown): number => {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+  };
+  const from = isRecord(node.from) ? node.from : { x: 0, y: 0 };
+  const to = isRecord(node.to) ? node.to : { x: 0, y: 0 };
+  const fx = num(from.x ?? 0);
+  const fy = num(from.y ?? 0);
+  const tx = num(to.x ?? 0);
+  const ty = num(to.y ?? 0);
+  const d = isRecord(node.control)
+    ? `M ${fx} ${fy} Q ${num(node.control.x ?? 0)} ${num(node.control.y ?? 0)} ${tx} ${ty}`
+    : `M ${fx} ${fy} L ${tx} ${ty}`;
+
+  const arrow = typeof node.arrow === "string" ? node.arrow : "none";
+  const markerId = connectorMarkerId(node);
+
+  // Append the connection path first so depth-first tree walkers encounter it
+  // before the arrowhead path nested inside <defs>/<marker>.
+  const path = create("path");
+  path.setAttribute("d", d);
+  path.setAttribute("fill", "none");
+  path.setAttribute("stroke", "currentColor");
+  path.setAttribute("stroke-width", "2.5");
+  path.setAttribute("vector-effect", "non-scaling-stroke");
+  path.setAttribute("stroke-linecap", "round");
+  if (node.dashed === true) {
+    path.setAttribute("stroke-dasharray", "4 4");
+  }
+  if (arrow === "end" || arrow === "both") {
+    path.setAttribute("marker-end", `url(#${markerId})`);
+  }
+  if (arrow === "start" || arrow === "both") {
+    path.setAttribute("marker-start", `url(#${markerId})`);
+  }
+  svg.appendChild(path);
+
+  if (arrow === "end" || arrow === "start" || arrow === "both") {
+    const defs = create("defs");
+    const marker = create("marker");
+    marker.setAttribute("id", markerId);
+    marker.setAttribute("markerWidth", "2.6");
+    marker.setAttribute("markerHeight", "2.6");
+    marker.setAttribute("refX", "2.2");
+    marker.setAttribute("refY", "1.3");
+    marker.setAttribute("orient", "auto");
+    marker.setAttribute("markerUnits", "userSpaceOnUse");
+    const head = create("path");
+    head.setAttribute("d", "M 0 0 L 2.6 1.3 L 0 2.6 z");
+    head.setAttribute("fill", "currentColor");
+    marker.appendChild(head);
+    defs.appendChild(marker);
+    svg.appendChild(defs);
+  }
+
+  return svg;
+}
+
+function unknownLayoutElement(
+  factories: LayoutRendererFactories,
+): LayoutRendererElement {
+  const element = factories.createElement("div");
+  element.setAttribute("data-velumo-layout", "unknown");
+  return element;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}