davaux 0.8.0

package/src/oml/jsx-runtime.ts

@@ -0,0 +1,121 @@
+// OML JSX runtime — produces an OmlNode tree instead of an HTML string.
+// Use via `jsxImportSource` in tsconfig, or import jsx directly for programmatic use.
+// Mirrors the API of src/jsx-runtime.ts; async components are fully supported.
+
+import type {
+  OmlComponent,
+  OmlElement,
+  OmlFragment,
+  OmlNode,
+  OmlProps,
+  OmlRaw,
+  OmlText,
+} from './types.js'
+
+type Primitive = string | number | boolean | null | undefined
+// Promise<string> is included so standard-runtime components (e.g. @davaux/ui) can be used
+// as children in OML pages without TypeScript errors. The runtime handles both at render time.
+type Child = Primitive | Promise<OmlNode | string> | Child[]
+
+export type Props = {
+  children?: Child | Child[]
+  key?: string | number
+  ref?: unknown
+  dangerouslySetInnerHTML?: { __html: string }
+  style?: string | Record<string, string | number>
+  className?: string
+  htmlFor?: string
+  tabIndex?: number
+  [prop: string]: unknown
+}
+
+export type ComponentType<P extends Props = Props> = (props: P) => Promise<OmlNode> | OmlNode
+
+async function resolveChildren(children: Child | Child[] | undefined): Promise<OmlNode[]> {
+  if (children == null || children === false) return []
+  if (Array.isArray(children)) {
+    const parts = await Promise.all(children.map((c) => resolveChildren(c)))
+    return parts.flat()
+  }
+  if (children instanceof Promise) {
+    const resolved = await children
+    if (resolved === null) return []
+    // A Promise<string> carries raw HTML (e.g. layout children passed from renderPage).
+    // Wrap as #raw so it passes through unescaped.
+    if (typeof resolved === 'string') return [{ type: '#raw', value: resolved } satisfies OmlRaw]
+    return [resolved as OmlNode]
+  }
+  if (typeof children === 'boolean') return []
+  const text: OmlText = { type: '#text', value: String(children) }
+  return [text]
+}
+
+// ─── JSX factory ───────────────────────────────────────────────────────────────
+
+export async function jsx(
+  type: string | ComponentType,
+  props: Props,
+  key?: string | number,
+): Promise<OmlNode> {
+  const { children, key: _key, ref: _ref, ...restProps } = props
+  const id = key != null ? String(key) : undefined
+
+  if (typeof type === 'function') {
+    const result = type(props)
+    const rawResult = result instanceof Promise ? await result : result
+    // Components may return raw HTML strings (e.g. island server stubs). Wrap in #raw so
+    // renderToHtml passes the content through without escaping.
+    const resolved: OmlNode =
+      typeof rawResult === 'string'
+        ? ({ type: '#raw', value: rawResult } satisfies OmlRaw)
+        : (rawResult as OmlNode)
+    const resolvedChildren = await resolveChildren(children)
+    const node: OmlComponent = {
+      type: '#component',
+      name: type.name || 'Anonymous',
+      id,
+      props: restProps as OmlProps,
+      ...(resolvedChildren.length > 0 ? { children: resolvedChildren } : {}),
+      output: resolved,
+    }
+    return node
+  }
+
+  if (type === Fragment) {
+    const nodes = await resolveChildren(children)
+    const node: OmlFragment = { type: '#fragment', children: nodes }
+    return node
+  }
+
+  const nodes = await resolveChildren(children)
+  const node: OmlElement = {
+    type: 'element',
+    tag: type as string,
+    id,
+    props: restProps as OmlProps,
+    children: nodes,
+  }
+  return node
+}
+
+export const jsxs = jsx
+export const jsxDEV = jsx
+
+export const Fragment = '__OmlFragment__'
+
+// ─── JSX namespace — required for `jsxImportSource: "davaux/oml"` in tsconfig ──
+// Re-uses IntrinsicElements from the main runtime; only JSX.Element differs.
+import type { JSX as BaseJSX } from '../jsx-runtime.js'
+
+export namespace JSX {
+  // Promise<string> is included so standard-runtime components are valid JSX elements
+  // in OML pages (e.g. when jsxImportSource: "davaux/oml" is set globally in tsconfig).
+  export type Element = Promise<OmlNode | string>
+  export interface ElementChildrenAttribute {
+    children: object
+  }
+  export interface IntrinsicAttributes {
+    key?: string | number
+  }
+  export type IntrinsicElements = BaseJSX.IntrinsicElements
+}

package/src/oml/jsx.ts

@@ -0,0 +1,151 @@
+// OML → JSX serializer.
+// Converts an OmlNode tree back to JSX source text, and an OmlBlueprint to a
+// complete .tsx component file. Enables round-trip export from Blueprint JSON.
+
+import type { OmlBlueprint, OmlNode, OmlPropType } from './types.js'
+
+const VOID_TAGS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+])
+
+const PROP_TS_TYPE: Record<OmlPropType, string> = {
+  string: 'string',
+  number: 'number',
+  boolean: 'boolean',
+  function: '() => void',
+  node: 'string',
+  array: 'unknown[]',
+}
+
+// ─── Prop serialization ────────────────────────────────────────────────────────
+
+function escapeAttr(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;')
+}
+
+function propToJsx(key: string, value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (value === true) return ` ${key}`
+  if (value === false) return ` ${key}={false}`
+  if (typeof value === 'string') return ` ${key}="${escapeAttr(value)}"`
+  if (typeof value === 'number') return ` ${key}={${value}}`
+  return ` ${key}={${JSON.stringify(value)}}`
+}
+
+function propsToJsx(props: Record<string, unknown>): string {
+  return Object.entries(props)
+    .filter(([k]) => k !== 'dangerouslySetInnerHTML' && k !== 'key' && k !== 'ref')
+    .map(([k, v]) => propToJsx(k, v))
+    .join('')
+}
+
+// ─── Node serialization ────────────────────────────────────────────────────────
+
+function nodeToJsx(node: OmlNode, depth: number): string {
+  if (node === null) return ''
+
+  const pad = '  '.repeat(depth)
+  const childPad = '  '.repeat(depth + 1)
+
+  if (node.type === '#text') return node.value
+
+  if (node.type === '#fragment') {
+    if (node.children.length === 0) return '<></>'
+    const children = node.children
+      .map((c) => nodeToJsx(c, depth + 1))
+      .filter(Boolean)
+      .map((c) => `${childPad}${c}`)
+      .join('\n')
+    return `<>\n${children}\n${pad}</>`
+  }
+
+  if (node.type === '#component') {
+    const props = propsToJsx(node.props)
+    return `<${node.name}${props} />`
+  }
+
+  if (node.type === '#raw') return `{/* raw html */}`
+
+  // element
+  const { tag, props, children } = node
+  const attrs = propsToJsx(props)
+
+  if (VOID_TAGS.has(tag)) return `<${tag}${attrs} />`
+  if (children.length === 0) return `<${tag}${attrs}></${tag}>`
+
+  // Single text child: keep inline
+  if (children.length === 1 && children[0]?.type === '#text') {
+    const { dangerouslySetInnerHTML } = props as { dangerouslySetInnerHTML?: { __html: string } }
+    if (dangerouslySetInnerHTML) {
+      return `<${tag}${attrs} dangerouslySetInnerHTML={{ __html: ${JSON.stringify(dangerouslySetInnerHTML.__html)} }} />`
+    }
+    return `<${tag}${attrs}>${children[0].value}</${tag}>`
+  }
+
+  const inner = children
+    .map((c) => nodeToJsx(c, depth + 1))
+    .filter(Boolean)
+    .map((c) => `${childPad}${c}`)
+    .join('\n')
+  return `<${tag}${attrs}>\n${inner}\n${pad}</${tag}>`
+}
+
+/**
+ * Render an OmlNode tree to a JSX expression string.
+ * `#component` nodes render as component invocations (`<Name prop="val" />`),
+ * not as their resolved output — preserving the component boundary.
+ */
+export function renderToJsx(node: OmlNode): string {
+  return nodeToJsx(node, 0)
+}
+
+// ─── Blueprint → .tsx file ─────────────────────────────────────────────────────
+
+/**
+ * Convert an OmlBlueprint to a complete `.tsx` component file.
+ * Import paths are sourced from `blueprint.imports`; missing entries are
+ * left as bare identifiers for the developer to resolve.
+ */
+export function blueprintToFile(blueprint: OmlBlueprint): string {
+  const lines: string[] = []
+
+  // Import statements
+  for (const [name, path] of Object.entries(blueprint.imports ?? {})) {
+    lines.push(`import ${name} from '${path}'`)
+  }
+  if (lines.length > 0) lines.push('')
+
+  // Props type
+  const propEntries = Object.entries(blueprint.props)
+  const propsType =
+    propEntries.length > 0
+      ? `{ ${propEntries.map(([n, s]) => `${n}${s.required ? '' : '?'}: ${PROP_TS_TYPE[s.type]}`).join(', ')} }`
+      : ''
+
+  const paramList =
+    propEntries.length > 0 ? `{ ${propEntries.map(([n]) => n).join(', ')} }: ${propsType}` : ''
+
+  lines.push(`export default function ${blueprint.name}(${paramList}) {`)
+  lines.push('  return (')
+
+  const body = nodeToJsx(blueprint.output, 2)
+  lines.push(`    ${body}`)
+
+  lines.push('  )')
+  lines.push('}')
+
+  return lines.join('\n')
+}

package/src/oml/page.ts

@@ -0,0 +1,13 @@
+import type { PageHandler, RequestContext } from '../types.js'
+import { definePage } from '../types.js'
+import type { OmlNode } from './types.js'
+
+/** Narrower alias for handlers that explicitly return OmlNode. Equivalent to PageHandler at runtime. */
+export type OmlPageHandler<P extends Record<string, string> = Record<string, string>> = (
+  ctx: RequestContext<P>,
+) => OmlNode | Promise<OmlNode>
+
+/** Alias for definePage — kept for clarity when a handler is intentionally OML-only. */
+export const defineOmlPage: <P extends Record<string, string> = Record<string, string>>(
+  fn: OmlPageHandler<P>,
+) => PageHandler<P> = definePage

package/src/oml/render.ts

@@ -0,0 +1,181 @@
+// OML renderer — converts an OmlNode tree to an HTML string.
+// Separating rendering from tree construction enables caching, diffing, and
+// multi-target output (HTML, email, etc.) from the same tree.
+
+import type { OmlNode, OmlProps } from './types.js'
+
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+])
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+function styleToString(style: Record<string, string | number>): string {
+  return Object.entries(style)
+    .map(([k, v]) => {
+      const prop = k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+      return `${prop}:${v}`
+    })
+    .join(';')
+}
+
+function renderProps(props: OmlProps | null | undefined): string {
+  if (!props) return ''
+  const parts: string[] = []
+
+  for (const [key, val] of Object.entries(props)) {
+    if (key === 'key' || key === 'ref' || key === 'dangerouslySetInnerHTML') continue
+    if (val === false || val == null) continue
+
+    const attr =
+      key === 'className'
+        ? 'class'
+        : key === 'htmlFor'
+          ? 'for'
+          : key === 'tabIndex'
+            ? 'tabindex'
+            : key
+
+    if (attr.startsWith('on') && attr[2] === attr[2]?.toUpperCase()) continue
+
+    if (val === true) {
+      parts.push(attr)
+      continue
+    }
+
+    if (attr === 'style') {
+      const css =
+        typeof val === 'string' ? val : styleToString(val as Record<string, string | number>)
+      parts.push(`style="${escapeHtml(css)}"`)
+      continue
+    }
+
+    parts.push(`${attr}="${escapeHtml(String(val))}"`)
+  }
+
+  return parts.length ? ` ${parts.join(' ')}` : ''
+}
+
+/** Render an OmlNode tree to an HTML string. */
+export function renderToHtml(node: OmlNode): string {
+  if (node === null) return ''
+  if (typeof (node as unknown) === 'string') return node as unknown as string
+
+  if (node.type === '#text') return escapeHtml(node.value)
+
+  if (node.type === '#fragment') return node.children.map(renderToHtml).join('')
+
+  if (node.type === '#component') return renderToHtml(node.output)
+
+  if (node.type === '#raw') return node.value
+
+  // OmlElement
+  const { tag, props, children } = node
+  const attrs = renderProps(props)
+
+  if (VOID_ELEMENTS.has(tag)) return `<${tag}${attrs}>`
+
+  const dsi = (props as { dangerouslySetInnerHTML?: { __html: string } } | null | undefined)
+    ?.dangerouslySetInnerHTML
+  if (dsi) {
+    return `<${tag}${attrs}>${dsi.__html}</${tag}>`
+  }
+
+  return `<${tag}${attrs}>${children.map(renderToHtml).join('')}</${tag}>`
+}
+
+function injectOmlAttrs(html: string, name: string, inst: number): string {
+  return html.replace(/(<[a-zA-Z][a-zA-Z0-9-]*)(\s|>|\/)/, (_, tag, after) => {
+    return `${tag} data-oml-comp="${name}" data-oml-inst="${inst}"${after}`
+  })
+}
+
+type DevCounters = Map<string, number>
+
+/**
+ * For #raw-returning components whose JSX children are stored on the node, inject
+ * child markers into the parent's raw HTML via string replacement. Each child's
+ * original raw HTML is found in the parent string and replaced with the marked version.
+ * This works because library components include their children's HTML verbatim.
+ */
+function injectChildMarkers(parentHtml: string, children: OmlNode[], counters: DevCounters): string {
+  let html = parentHtml
+  for (const child of children) {
+    if (!child) continue
+    if (child.type === '#component' && child.output?.type === '#raw') {
+      const childInst = counters.get(child.name) ?? 0
+      counters.set(child.name, childInst + 1)
+      let childHtml = child.output.value
+      if (child.children && child.children.length > 0) {
+        childHtml = injectChildMarkers(childHtml, child.children, counters)
+      }
+      const markedChildHtml = injectOmlAttrs(childHtml, child.name, childInst)
+      html = html.replace(child.output.value, markedChildHtml)
+    } else if (child.type === '#fragment') {
+      html = injectChildMarkers(html, child.children, counters)
+    }
+  }
+  return html
+}
+
+/**
+ * Dev-mode renderer — identical to renderToHtml but injects `data-oml-comp` and
+ * `data-oml-inst` attributes into the first HTML tag of #raw-returning components
+ * and recursively into their JSX children. This lets the visual editor map clicked
+ * DOM elements back to their OML #component nodes.
+ */
+export function renderToHtmlDev(node: OmlNode, counters: DevCounters = new Map()): string {
+  if (node === null) return ''
+  if (typeof (node as unknown) === 'string') return node as unknown as string
+
+  if (node.type === '#text') return escapeHtml(node.value)
+
+  if (node.type === '#fragment')
+    return node.children.map((c) => renderToHtmlDev(c, counters)).join('')
+
+  if (node.type === '#raw') return node.value
+
+  if (node.type === '#component') {
+    const inst = counters.get(node.name) ?? 0
+    counters.set(node.name, inst + 1)
+    if (node.output?.type === '#raw') {
+      let html = node.output.value
+      if (node.children && node.children.length > 0) {
+        html = injectChildMarkers(html, node.children, counters)
+      }
+      return injectOmlAttrs(html, node.name, inst)
+    }
+    return renderToHtmlDev(node.output, counters)
+  }
+
+  const { tag, props, children } = node
+  const attrs = renderProps(props)
+
+  if (VOID_ELEMENTS.has(tag)) return `<${tag}${attrs}>`
+
+  const dsi = (props as { dangerouslySetInnerHTML?: { __html: string } } | null | undefined)
+    ?.dangerouslySetInnerHTML
+  if (dsi) return `<${tag}${attrs}>${dsi.__html}</${tag}>`
+
+  return `<${tag}${attrs}>${children.map((c) => renderToHtmlDev(c, counters)).join('')}</${tag}>`
+}

package/src/oml/types.ts

@@ -0,0 +1,159 @@
+// OML — Object Markup Language
+// A stable, serializable intermediate representation of a rendered component tree.
+// Produced by the OML JSX runtime; consumed by the OML renderer and visual editor.
+
+export type OmlProps = Record<string, unknown>
+
+/** A plain text node. */
+export type OmlText = {
+  type: '#text'
+  value: string
+}
+
+/** A raw HTML passthrough node — not escaped; used for island server stubs and similar. */
+export type OmlRaw = {
+  type: '#raw'
+  value: string
+}
+
+/** A rendered HTML element. */
+export type OmlElement = {
+  type: 'element'
+  /** The HTML tag name (div, span, button, etc.). */
+  tag: string
+  /** Stable identity from the JSX `key` prop — used for diffing and caching. */
+  id?: string
+  props: OmlProps
+  children: OmlNode[]
+}
+
+/**
+ * A rendered component call — preserves component boundaries for the visual
+ * editor and inspector. The `return` field is what the component rendered.
+ */
+export type OmlComponent = {
+  type: '#component'
+  /** Component function name — shown in the inspector. */
+  name: string
+  id?: string
+  /** Props passed to the component (children excluded). */
+  props: OmlProps
+  /**
+   * Resolved JSX children passed to the component — stored separately from `output`
+   * so the visual editor can show the JSX hierarchy even when `output` is #raw
+   * (i.e. when a library component renders to an HTML string).
+   */
+  children?: OmlNode[]
+  /** The component's rendered output. */
+  output: OmlNode
+}
+
+/** A JSX Fragment — a grouping with no wrapper element. */
+export type OmlFragment = {
+  type: '#fragment'
+  children: OmlNode[]
+}
+
+export type OmlNode = OmlElement | OmlComponent | OmlFragment | OmlText | OmlRaw | null
+
+// ─── Blueprint — JSON component definition ─────────────────────────────────────
+// Stored in .oml.json files; naturally maps to SurrealDB records.
+
+export type OmlPropType = 'string' | 'number' | 'boolean' | 'function' | 'node' | 'array'
+
+export type OmlPropSchema = {
+  type: OmlPropType
+  default?: unknown
+  required?: boolean
+  description?: string
+}
+
+/**
+ * A component definition stored in a Blueprint JSON file.
+ * The `return` field is the root OmlNode of the component's render tree.
+ * Wires (signal connections) between nodes are stored as id references.
+ * `imports` maps component names used in the tree to their module paths,
+ * enabling round-trip export back to .tsx without losing import information.
+ */
+export type OmlBlueprint = {
+  id: string
+  name: string
+  props: Record<string, OmlPropSchema>
+  output: OmlNode
+  imports?: Record<string, string>
+}
+
+// ─── JSON parse / validate ─────────────────────────────────────────────────────
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+function parseNode(v: unknown): OmlNode {
+  if (v === null) return null
+  if (!isObject(v)) throw new Error(`OML: expected node object, got ${typeof v}`)
+
+  const { type } = v
+  if (type === '#text') {
+    if (typeof v.value !== 'string') throw new Error('OML: #text node missing string value')
+    return { type: '#text', value: v.value }
+  }
+  if (type === '#fragment') {
+    return { type: '#fragment', children: parseChildren(v.children) }
+  }
+  if (type === '#component') {
+    if (typeof v.name !== 'string') throw new Error('OML: #component node missing name')
+    const parsed: OmlComponent = {
+      type: '#component',
+      name: v.name,
+      id: typeof v.id === 'string' ? v.id : undefined,
+      props: isObject(v.props) ? (v.props as OmlProps) : {},
+      output: parseNode(v.output),
+    }
+    if (Array.isArray(v.children) && v.children.length > 0) {
+      parsed.children = parseChildren(v.children)
+    }
+    return parsed
+  }
+  if (type === 'element') {
+    if (typeof v.tag !== 'string') throw new Error('OML: element node missing tag')
+    return {
+      type: 'element',
+      tag: v.tag,
+      id: typeof v.id === 'string' ? v.id : undefined,
+      props: isObject(v.props) ? (v.props as OmlProps) : {},
+      children: parseChildren(v.children),
+    }
+  }
+  throw new Error(`OML: unknown node type "${type}"`)
+}
+
+function parseChildren(v: unknown): OmlNode[] {
+  if (!Array.isArray(v)) return []
+  return v.map(parseNode)
+}
+
+/**
+ * Parse and validate an `OmlNode` from untrusted JSON (e.g. a Blueprint file).
+ * Throws a descriptive error if the shape is invalid.
+ */
+export function parseOml(json: unknown): OmlNode {
+  return parseNode(json)
+}
+
+/**
+ * Parse and validate an `OmlBlueprint` from untrusted JSON.
+ * Throws a descriptive error if the shape is invalid.
+ */
+export function parseOmlBlueprint(json: unknown): OmlBlueprint {
+  if (!isObject(json)) throw new Error('OML: blueprint must be an object')
+  if (typeof json.id !== 'string') throw new Error('OML: blueprint missing id')
+  if (typeof json.name !== 'string') throw new Error('OML: blueprint missing name')
+  return {
+    id: json.id,
+    name: json.name,
+    props: isObject(json.props) ? (json.props as Record<string, OmlPropSchema>) : {},
+    output: parseNode(json.output),
+    imports: isObject(json.imports) ? (json.imports as Record<string, string>) : undefined,
+  }
+}