davaux 0.8.0

package/src/jsx-runtime.ts

@@ -0,0 +1,536 @@
+// Server JSX runtime — renders component trees to HTML strings.
+// TypeScript resolves this via jsxImportSource: "davaux" in tsconfig.json.
+// Async components are fully supported: any component may return Promise<string>.
+
+type Primitive = string | number | boolean | null | undefined
+// Promise<object|null> lets OML JSX elements (Promise<OmlNode|string>) pass as children without errors.
+type Child = Primitive | Promise<string | object | null> | Child[]
+type StyleObject = Record<string, string | number>
+
+export type Props = {
+  children?: Child | Child[]
+  key?: string | number
+  ref?: unknown
+  dangerouslySetInnerHTML?: { __html: string }
+  style?: string | StyleObject
+  className?: string
+  htmlFor?: string
+  tabIndex?: number
+  [prop: string]: unknown
+}
+
+export type ComponentType<P extends Props = Props> = (props: P) => JSX.Element
+
+// ─── HTML helpers ─────────────────────────────────────────────────────────────
+
+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, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+function styleToString(style: StyleObject): string {
+  return Object.entries(style)
+    .map(([k, v]) => {
+      // camelCase → kebab-case
+      const prop = k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+      return `${prop}:${v}`
+    })
+    .join(';')
+}
+
+async function renderChildren(children: Child | Child[] | undefined): Promise<string> {
+  if (children == null || children === false) return ''
+  if (Array.isArray(children)) {
+    const parts = await Promise.all(children.map((c) => renderChildren(c)))
+    return parts.join('')
+  }
+  if (children instanceof Promise) {
+    const resolved = await children
+    // The OML jsx runtime produces OmlNode objects instead of strings. Render them to
+    // HTML on the fly — the import is cached by Node after the first call.
+    if (resolved !== null && typeof resolved === 'object') {
+      const { renderToHtml } = await import('./oml/render.js')
+      return renderToHtml(resolved as never)
+    }
+    return (resolved ?? '') as string
+  }
+  if (typeof children === 'boolean') return ''
+  return escapeHtml(String(children))
+}
+
+function renderAttrs(props: Props): string {
+  const parts: string[] = []
+
+  for (const [key, val] of Object.entries(props)) {
+    if (key === 'children' || key === 'key' || key === 'ref' || key === 'dangerouslySetInnerHTML')
+      continue
+
+    if (val === false || val == null) continue
+
+    // Map React-isms to HTML attributes
+    const attr =
+      key === 'className'
+        ? 'class'
+        : key === 'htmlFor'
+          ? 'for'
+          : key === 'tabIndex'
+            ? 'tabindex'
+            : key
+
+    // Skip event handlers — they have no meaning in SSR
+    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 StyleObject)
+      parts.push(`style="${escapeHtml(css)}"`)
+      continue
+    }
+
+    parts.push(`${attr}="${escapeHtml(String(val))}"`)
+  }
+
+  return parts.length ? ` ${parts.join(' ')}` : ''
+}
+
+// ─── JSX factory ──────────────────────────────────────────────────────────────
+
+export async function jsx(
+  type: string | ComponentType,
+  props: Props,
+  _key?: string | number,
+): Promise<string> {
+  if (typeof type === 'function') {
+    const result = type(props)
+    return (result instanceof Promise ? await result : result) as unknown as string
+  }
+
+  if (type === Fragment) {
+    return renderChildren(props.children)
+  }
+
+  if (props.dangerouslySetInnerHTML) {
+    const attrs = renderAttrs(props)
+    return `<${type}${attrs}>${props.dangerouslySetInnerHTML.__html}</${type}>`
+  }
+
+  const attrs = renderAttrs(props)
+  if (VOID_ELEMENTS.has(type)) return `<${type}${attrs}>`
+
+  const children = await renderChildren(props.children)
+  return `<${type}${attrs}>${children}</${type}>`
+}
+
+export const jsxs = jsx
+export const jsxDEV = jsx
+
+export const Fragment = '__Fragment__'
+
+// ─── JSX namespace (used by TypeScript for element type checking) ──────────────
+
+export namespace JSX {
+  // Always Promise<string> — async functions returning JSX auto-unwrap to Promise<string>.
+  // Sync functions returning JSX also satisfy this because JSX.Element = Promise<string>
+  // and a sync function returning a promise is valid where Promise<string> is expected.
+  export type Element = Promise<string>
+
+  export interface ElementChildrenAttribute {
+    children: object
+  }
+
+  export interface IntrinsicAttributes {
+    key?: string | number
+  }
+
+  // Shared HTML attribute base
+  interface HTMLAttributes {
+    id?: string
+    class?: string
+    className?: string
+    style?: string | StyleObject
+    title?: string
+    lang?: string
+    dir?: 'ltr' | 'rtl' | 'auto'
+    hidden?: boolean
+    tabIndex?: number
+    tabindex?: number
+    role?: string
+    slot?: string
+    draggable?: boolean
+    spellcheck?: boolean
+    contenteditable?: boolean | 'true' | 'false'
+    dangerouslySetInnerHTML?: { __html: string }
+    // data-* and aria-*
+    [attr: string]: unknown
+  }
+
+  interface AnchorAttributes extends HTMLAttributes {
+    href?: string
+    target?: '_blank' | '_self' | '_parent' | '_top' | string
+    rel?: string
+    download?: string | boolean
+    hreflang?: string
+    type?: string
+  }
+
+  interface InputAttributes extends HTMLAttributes {
+    type?: string
+    name?: string
+    value?: string | number
+    defaultValue?: string | number
+    checked?: boolean
+    defaultChecked?: boolean
+    placeholder?: string
+    disabled?: boolean
+    readonly?: boolean
+    required?: boolean
+    min?: string | number
+    max?: string | number
+    step?: string | number
+    multiple?: boolean
+    accept?: string
+    autocomplete?: string
+    autofocus?: boolean
+    form?: string
+    pattern?: string
+    list?: string
+  }
+
+  interface FormAttributes extends HTMLAttributes {
+    action?: string
+    method?: 'get' | 'post'
+    enctype?: string
+    target?: string
+    novalidate?: boolean
+    autocomplete?: string
+  }
+
+  interface ButtonAttributes extends HTMLAttributes {
+    type?: 'button' | 'submit' | 'reset'
+    disabled?: boolean
+    form?: string
+    name?: string
+    value?: string
+    autofocus?: boolean
+  }
+
+  interface ImgAttributes extends HTMLAttributes {
+    src?: string
+    alt?: string
+    width?: number | string
+    height?: number | string
+    loading?: 'lazy' | 'eager'
+    decoding?: 'async' | 'auto' | 'sync'
+    srcset?: string
+    sizes?: string
+  }
+
+  interface LinkAttributes extends HTMLAttributes {
+    href?: string
+    rel?: string
+    type?: string
+    media?: string
+    as?: string
+    crossorigin?: string
+    integrity?: string
+  }
+
+  interface ScriptAttributes extends HTMLAttributes {
+    src?: string
+    type?: string
+    async?: boolean
+    defer?: boolean
+    module?: boolean
+    crossorigin?: string
+    integrity?: string
+    nonce?: string
+  }
+
+  interface MetaAttributes extends HTMLAttributes {
+    name?: string
+    content?: string
+    charset?: string
+    httpEquiv?: string
+    property?: string
+  }
+
+  interface LabelAttributes extends HTMLAttributes {
+    htmlFor?: string
+    for?: string
+    form?: string
+  }
+
+  interface SelectAttributes extends HTMLAttributes {
+    name?: string
+    value?: string
+    defaultValue?: string
+    multiple?: boolean
+    disabled?: boolean
+    required?: boolean
+    size?: number
+    form?: string
+    autocomplete?: string
+  }
+
+  interface TextareaAttributes extends HTMLAttributes {
+    name?: string
+    value?: string
+    defaultValue?: string
+    placeholder?: string
+    disabled?: boolean
+    readonly?: boolean
+    required?: boolean
+    rows?: number
+    cols?: number
+    maxlength?: number
+    form?: string
+    autocomplete?: string
+    autofocus?: boolean
+    wrap?: 'hard' | 'soft'
+  }
+
+  interface VideoAttributes extends HTMLAttributes {
+    src?: string
+    controls?: boolean
+    autoplay?: boolean
+    loop?: boolean
+    muted?: boolean
+    poster?: string
+    width?: number | string
+    height?: number | string
+    preload?: 'auto' | 'metadata' | 'none'
+  }
+
+  interface AudioAttributes extends HTMLAttributes {
+    src?: string
+    controls?: boolean
+    autoplay?: boolean
+    loop?: boolean
+    muted?: boolean
+    preload?: 'auto' | 'metadata' | 'none'
+  }
+
+  interface ColAttributes extends HTMLAttributes {
+    span?: number
+  }
+
+  interface TdAttributes extends HTMLAttributes {
+    colspan?: number
+    rowspan?: number
+    headers?: string
+  }
+
+  interface ThAttributes extends TdAttributes {
+    scope?: 'col' | 'row' | 'colgroup' | 'rowgroup'
+    abbr?: string
+  }
+
+  interface IframeAttributes extends HTMLAttributes {
+    src?: string
+    srcdoc?: string
+    name?: string
+    sandbox?: string
+    allow?: string
+    allowfullscreen?: boolean
+    width?: number | string
+    height?: number | string
+    loading?: 'lazy' | 'eager'
+    referrerpolicy?: string
+  }
+
+  export interface IntrinsicElements {
+    // Document structure
+    html: HTMLAttributes
+    head: HTMLAttributes
+    body: HTMLAttributes
+    title: HTMLAttributes
+    base: HTMLAttributes & { href?: string; target?: string }
+    link: LinkAttributes
+    meta: MetaAttributes
+    style: HTMLAttributes & { media?: string }
+    script: ScriptAttributes
+    noscript: HTMLAttributes
+
+    // Sectioning
+    main: HTMLAttributes
+    header: HTMLAttributes
+    footer: HTMLAttributes
+    nav: HTMLAttributes
+    section: HTMLAttributes
+    article: HTMLAttributes
+    aside: HTMLAttributes
+    h1: HTMLAttributes
+    h2: HTMLAttributes
+    h3: HTMLAttributes
+    h4: HTMLAttributes
+    h5: HTMLAttributes
+    h6: HTMLAttributes
+    hgroup: HTMLAttributes
+    address: HTMLAttributes
+
+    // Content
+    div: HTMLAttributes
+    span: HTMLAttributes
+    p: HTMLAttributes
+    pre: HTMLAttributes
+    blockquote: HTMLAttributes & { cite?: string }
+    hr: HTMLAttributes
+    br: HTMLAttributes
+    wbr: HTMLAttributes
+    figure: HTMLAttributes
+    figcaption: HTMLAttributes
+    details: HTMLAttributes & { open?: boolean }
+    summary: HTMLAttributes
+    dialog: HTMLAttributes & { open?: boolean }
+
+    // Lists
+    ul: HTMLAttributes
+    ol: HTMLAttributes & { start?: number; reversed?: boolean; type?: string }
+    li: HTMLAttributes & { value?: number }
+    dl: HTMLAttributes
+    dt: HTMLAttributes
+    dd: HTMLAttributes
+
+    // Inline text
+    a: AnchorAttributes
+    em: HTMLAttributes
+    strong: HTMLAttributes
+    small: HTMLAttributes
+    s: HTMLAttributes
+    cite: HTMLAttributes
+    q: HTMLAttributes & { cite?: string }
+    dfn: HTMLAttributes
+    abbr: HTMLAttributes
+    code: HTMLAttributes
+    var: HTMLAttributes
+    samp: HTMLAttributes
+    kbd: HTMLAttributes
+    sub: HTMLAttributes
+    sup: HTMLAttributes
+    b: HTMLAttributes
+    u: HTMLAttributes
+    i: HTMLAttributes
+    mark: HTMLAttributes
+    ruby: HTMLAttributes
+    rp: HTMLAttributes
+    rt: HTMLAttributes
+    bdi: HTMLAttributes
+    bdo: HTMLAttributes
+    time: HTMLAttributes & { datetime?: string }
+    data: HTMLAttributes & { value?: string }
+
+    // Forms
+    form: FormAttributes
+    label: LabelAttributes
+    input: InputAttributes
+    button: ButtonAttributes
+    select: SelectAttributes
+    datalist: HTMLAttributes
+    optgroup: HTMLAttributes & { label?: string; disabled?: boolean }
+    option: HTMLAttributes & {
+      value?: string
+      disabled?: boolean
+      selected?: boolean
+      label?: string
+    }
+    textarea: TextareaAttributes
+    output: HTMLAttributes & { for?: string; form?: string; name?: string }
+    progress: HTMLAttributes & { value?: number; max?: number }
+    meter: HTMLAttributes & {
+      value?: number
+      min?: number
+      max?: number
+      low?: number
+      high?: number
+      optimum?: number
+    }
+    fieldset: HTMLAttributes & { disabled?: boolean; form?: string; name?: string }
+    legend: HTMLAttributes
+
+    // Media
+    img: ImgAttributes
+    video: VideoAttributes
+    audio: AudioAttributes
+    source: HTMLAttributes & {
+      src?: string
+      type?: string
+      srcset?: string
+      sizes?: string
+      media?: string
+    }
+    track: HTMLAttributes & {
+      src?: string
+      kind?: string
+      label?: string
+      srclang?: string
+      default?: boolean
+    }
+    embed: HTMLAttributes & {
+      src?: string
+      type?: string
+      width?: number | string
+      height?: number | string
+    }
+    object: HTMLAttributes & {
+      data?: string
+      type?: string
+      width?: number | string
+      height?: number | string
+    }
+    picture: HTMLAttributes
+    canvas: HTMLAttributes & { width?: number | string; height?: number | string }
+    map: HTMLAttributes & { name?: string }
+    area: HTMLAttributes & {
+      alt?: string
+      coords?: string
+      shape?: string
+      href?: string
+      target?: string
+    }
+
+    // Tables
+    table: HTMLAttributes
+    caption: HTMLAttributes
+    colgroup: HTMLAttributes & { span?: number }
+    col: ColAttributes
+    thead: HTMLAttributes
+    tbody: HTMLAttributes
+    tfoot: HTMLAttributes
+    tr: HTMLAttributes
+    td: TdAttributes
+    th: ThAttributes
+
+    // Interactive
+    iframe: IframeAttributes
+    portal: HTMLAttributes
+    menu: HTMLAttributes
+
+    // Obsolete / catch-all
+    [tag: string]: HTMLAttributes
+  }
+}

package/src/link.ts

@@ -0,0 +1,49 @@
+import type { JSX } from './jsx-runtime.js'
+import { jsx } from './jsx-runtime.js'
+import type { RequestContext } from './types.js'
+
+type AnchorProps = JSX.IntrinsicElements['a']
+type LinkProps = AnchorProps & {
+  activeClass?: string
+  external?: boolean
+}
+
+/**
+ * Create basePath-aware link utilities for use in layouts and pages.
+ *
+ * Returns `{ link, Link }`:
+ * - `link(href)` — prefixes the configured `basePath` to absolute paths.
+ * - `Link` — a JSX `<a>` component that also handles `activeClass` detection
+ *   and sets safe defaults (`rel="noopener noreferrer"`, `target="_blank"`) for
+ *   external links.
+ *
+ * @example
+ * const { link, Link } = createLink(ctx)
+ * <Link href="/about" activeClass="active">About</Link>
+ * <Link href="https://example.com" external>External</Link>
+ */
+export function createLink(ctx: RequestContext) {
+  const link = (href: string) => (href.startsWith('/') ? `${ctx.basePath}${href}` : href)
+  const Link = ({
+    href = '',
+    activeClass,
+    external,
+    class: className,
+    rel,
+    target,
+    ...rest
+  }: LinkProps) => {
+    const resolvedHref = link(href)
+    const isActive = activeClass != null && resolvedHref === ctx.url.pathname
+    const classes =
+      [className, isActive ? activeClass : undefined].filter(Boolean).join(' ') || undefined
+    const resolvedTarget = external && !target ? '_blank' : target
+    const resolvedRel = external && !rel ? 'noopener noreferrer' : rel
+    return jsx(
+      'a',
+      { href: resolvedHref, class: classes, target: resolvedTarget, rel: resolvedRel, ...rest },
+      undefined,
+    )
+  }
+  return { link, Link }
+}

package/src/oml/fragment.ts

@@ -0,0 +1,54 @@
+import type { OmlNode } from './types.js'
+
+export type OmlFragmentOptions<P> = {
+  /** Derive a stable string cache key from props. Defaults to JSON.stringify(props). */
+  key?: (props: P) => string
+  /** Time-to-live in milliseconds. Omit for indefinite caching. */
+  ttl?: number
+}
+
+type CacheEntry = { node: OmlNode; at: number }
+
+const registry = new Set<Map<string, CacheEntry>>()
+
+/** Invalidate all fragment caches — useful after CMS updates or programmatic cache busting. */
+export function clearAllFragments(): void {
+  for (const cache of registry) cache.clear()
+}
+
+/** Define a cached, no-props OML fragment. The function runs once; subsequent calls return the cached node. */
+export function defineFragment(
+  fn: () => OmlNode | Promise<OmlNode>,
+  options?: { ttl?: number },
+): () => Promise<OmlNode>
+
+/** Define a cached OML fragment that accepts props. Caches per unique prop combination. */
+export function defineFragment<P extends Record<string, unknown>>(
+  fn: (props: P) => OmlNode | Promise<OmlNode>,
+  options?: OmlFragmentOptions<P>,
+): (props: P) => Promise<OmlNode>
+
+export function defineFragment<P extends Record<string, unknown>>(
+  fn: (props?: P) => OmlNode | Promise<OmlNode>,
+  options?: OmlFragmentOptions<P>,
+): (props?: P) => Promise<OmlNode> {
+  const cache = new Map<string, CacheEntry>()
+  registry.add(cache)
+
+  return async (props?: P): Promise<OmlNode> => {
+    const key =
+      options?.key && props !== undefined ? options.key(props) : JSON.stringify(props ?? null)
+
+    const entry = cache.get(key)
+    if (entry !== undefined) {
+      if (!options?.ttl || Date.now() - entry.at < options.ttl) {
+        return entry.node
+      }
+      cache.delete(key)
+    }
+
+    const node = await fn(props)
+    cache.set(key, { node, at: Date.now() })
+    return node
+  }
+}

package/src/oml/index.ts

@@ -0,0 +1,21 @@
+export type { OmlFragmentOptions } from './fragment.js'
+export { clearAllFragments, defineFragment } from './fragment.js'
+export { blueprintToFile, renderToJsx } from './jsx.js'
+export type { ComponentType as OmlComponentType, Props as OmlJsxProps } from './jsx-runtime.js'
+export { Fragment, jsx, jsxDEV, jsxs } from './jsx-runtime.js'
+export type { OmlPageHandler } from './page.js'
+export { defineOmlPage } from './page.js'
+export { renderToHtml } from './render.js'
+export type {
+  OmlBlueprint,
+  OmlComponent,
+  OmlElement,
+  OmlFragment,
+  OmlNode,
+  OmlPropSchema,
+  OmlProps,
+  OmlPropType,
+  OmlRaw,
+  OmlText,
+} from './types.js'
+export { parseOml, parseOmlBlueprint } from './types.js'