@crombolo/render 0.0.0-stage → 0.10.0

package/src/jsx-runtime.ts

@@ -0,0 +1,334 @@
+/**
+ * A JSX runtime that renders straight to an HTML string.
+ *
+ * Templates are ordinary .tsx files executed by Bun, so there is no virtual DOM
+ * and no hydration: a template is a function from a model to markup. Configured
+ * through `jsxImportSource` in tsconfig.
+ *
+ * A component may be async. Rendering stays synchronous until it meets a
+ * promise, and from there hands back a promise of the markup instead, so a tree
+ * without one renders exactly as it always has.
+ */
+import { escapeHtml, RawHtml, serializeAttributes, VOID_ELEMENTS } from './html.ts'
+import type { CustomElementAttributes, KnownElements } from './jsx-attributes.ts'
+
+export type Child =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | RawHtml
+  | Promise<Child>
+  | Child[]
+
+/** What `jsx()` returns: markup, or a promise of it once an async component is involved. */
+export type Html = RawHtml | Promise<RawHtml>
+
+/**
+ * The value of the `setInnerHTML` attribute: markup, and whether to emit it
+ * verbatim.
+ *
+ * React's `dangerouslySetInnerHTML` is always verbatim, and its name is the only
+ * thing standing between a value and an injection. Making it a flag moves that
+ * decision into the value, so a template that forgets it escapes rather than
+ * trusting whatever arrived.
+ */
+export interface InnerHTML {
+  __html: string | Promise<string>
+  /** Emit the markup as-is. Escaped when absent. */
+  dangerously?: boolean
+}
+
+export interface ElementProps extends Record<string, unknown> {
+  children?: Child
+  setInnerHTML?: InnerHTML
+  /** React's spelling, always verbatim. `setInnerHTML` escapes unless told not to. */
+  dangerouslySetInnerHTML?: { __html: string | Promise<string> }
+}
+
+export type Component = (props: ElementProps) => Child
+
+export const Fragment = Symbol.for('crombolo.fragment')
+
+export function isPromise(value: unknown): value is Promise<unknown> {
+  return typeof (value as { then?: unknown } | null | undefined)?.then === 'function'
+}
+
+const REACT_ELEMENTS = new Set([
+  Symbol.for('react.element'),
+  Symbol.for('react.transitional.element'),
+])
+
+/** Refuses what has no markup of its own, saying what to do instead. */
+function refuseChild(child: unknown): never {
+  if (typeof child === 'function')
+    throw new Error(
+      'A function is not valid as a child. Call it, or render it as a component: <Name />.',
+    )
+  if (typeof child === 'symbol') throw new Error('A symbol is not valid as a child.')
+  if (REACT_ELEMENTS.has((child as { $$typeof?: symbol }).$$typeof as symbol))
+    throw new Error(
+      "A React element was rendered in a page template. Templates render with Crombolo's own " +
+        'JSX, to static HTML, so a React component cannot run here. Render an element to mount ' +
+        'it on, and load your client code from /scripts/.',
+    )
+  const found =
+    Object.getPrototypeOf(child) === Object.prototype
+      ? `object with keys {${Object.keys(child as object).join(', ')}}`
+      : Object.prototype.toString.call(child)
+  throw new Error(
+    `Objects are not valid as a child (found: ${found}). Render a list as an array, and a value as text.`,
+  )
+}
+
+function renderChild(child: Child): string | Promise<string> {
+  if (child === null || child === undefined || child === false || child === true) return ''
+  if (child instanceof RawHtml) return child.value
+  if (isPromise(child))
+    return (child as Promise<unknown>).then((value) => renderChild(value as Child))
+  if (Array.isArray(child)) {
+    const parts = child.map(renderChild)
+    return parts.some(isPromise)
+      ? Promise.all(parts).then((done) => done.join(''))
+      : (parts as string[]).join('')
+  }
+  if (typeof child === 'string' || typeof child === 'number' || typeof child === 'bigint')
+    return escapeHtml(String(child))
+  return refuseChild(child)
+}
+
+function toHtml(content: string | Promise<string>, wrap = (inner: string) => inner): Html {
+  if (!isPromise(content)) return new RawHtml(wrap(content))
+  const html = content.then((inner) => new RawHtml(wrap(inner)))
+  // Marked handled so an element built but never rendered does not surface as an
+  // unhandled rejection; whoever renders it still receives the error.
+  html.catch(() => {})
+  return html
+}
+
+function innerHtml(type: string, props: ElementProps): string | Promise<string> {
+  const verbatim = props.dangerouslySetInnerHTML
+  if (verbatim) {
+    if (props.setInnerHTML)
+      throw new Error(`<${type}> was given both setInnerHTML and dangerouslySetInnerHTML.`)
+    if (props.children !== undefined && props.children !== null)
+      throw new Error(`<${type}> was given both children and dangerouslySetInnerHTML.`)
+    return verbatim.__html
+  }
+  const inner = props.setInnerHTML
+  if (!inner) return renderChild(props.children)
+  const output = (html: string) => (inner.dangerously ? html : escapeHtml(html))
+  return isPromise(inner.__html) ? inner.__html.then(output) : output(inner.__html)
+}
+
+/**
+ * An `<option>` that keeps its value until it is written, so the `<select>`
+ * holding it can mark it selected. JSX builds the options before the select,
+ * so by then a finished string could only be edited, not asked.
+ */
+class OptionHtml extends RawHtml {
+  readonly optionValue: string | undefined
+  readonly #props: ElementProps
+  readonly #inner: string
+
+  constructor(props: ElementProps, inner: string) {
+    super(`<option${serializeAttributes(props, 'option')}>${inner}</option>`)
+    this.#props = props
+    this.#inner = inner
+    // Without a value attribute an option submits its text, so that is what matches.
+    this.optionValue =
+      props.value !== undefined && props.value !== null
+        ? String(props.value)
+        : textOf(props.children)
+  }
+
+  /** This option as the select's value says it should be. */
+  chosen(selected: boolean): OptionHtml {
+    return new OptionHtml({ ...this.#props, selected }, this.#inner)
+  }
+}
+
+/** An `<optgroup>` that keeps its options, so the select can reach through it. */
+class OptgroupHtml extends RawHtml {
+  readonly #props: ElementProps
+
+  constructor(props: ElementProps, inner: string) {
+    super(`<optgroup${serializeAttributes(props, 'optgroup')}>${inner}</optgroup>`)
+    this.#props = props
+  }
+
+  get options(): Child {
+    return this.#props.children
+  }
+
+  /** This group, written again with its options as the select chose them. */
+  withOptions(children: Child): Html {
+    return optgroup({ ...this.#props, children })
+  }
+}
+
+function optgroup(props: ElementProps): Html {
+  const inner = renderChild(props.children)
+  if (!isPromise(inner)) return new OptgroupHtml(props, inner)
+  const group = inner.then((done) => new OptgroupHtml(props, done))
+  group.catch(() => {})
+  return group
+}
+
+/** The plain text of children that are only text, as an option's implicit value. */
+function textOf(children: Child): string | undefined {
+  if (typeof children === 'string' || typeof children === 'number') return String(children)
+  if (Array.isArray(children)) {
+    const parts = children.map(textOf)
+    return parts.every((part) => part !== undefined) ? parts.join('') : undefined
+  }
+  return undefined
+}
+
+/** Marks the options among `children` whose value was chosen, noting which values it found. */
+function chooseOptions(children: Child, chosen: Set<string>, found: Set<string>): Child {
+  if (children instanceof OptionHtml) {
+    const selected = children.optionValue !== undefined && chosen.has(children.optionValue)
+    if (selected) found.add(children.optionValue as string)
+    return children.chosen(selected)
+  }
+  if (children instanceof OptgroupHtml)
+    return children.withOptions(chooseOptions(children.options, chosen, found))
+  if (Array.isArray(children)) return children.map((child) => chooseOptions(child, chosen, found))
+  if (isPromise(children))
+    return (children as Promise<unknown>).then((resolved) =>
+      chooseOptions(resolved as Child, chosen, found),
+    )
+  return children
+}
+
+/** React's controlled form values, as the attributes and content the HTML spells them with. */
+function formControl(type: string, props: ElementProps): ElementProps {
+  if (type === 'input') {
+    const { defaultValue, defaultChecked, ...rest } = props
+    return {
+      ...rest,
+      ...(rest.value === undefined && defaultValue !== undefined ? { value: defaultValue } : {}),
+      ...(rest.checked === undefined && defaultChecked !== undefined
+        ? { checked: defaultChecked }
+        : {}),
+    }
+  }
+  if (type === 'textarea') {
+    const { value, defaultValue, ...rest } = props
+    const text = value ?? defaultValue
+    if (text === undefined || text === null) return rest
+    if (rest.children !== undefined && rest.children !== null)
+      throw new Error('<textarea> was given both a value and children; use the value alone.')
+    return { ...rest, children: String(text) }
+  }
+  return props
+}
+
+function select(props: ElementProps): Html {
+  const { value, defaultValue, ...rest } = props
+  const wanted = value ?? defaultValue
+  if (wanted === undefined || wanted === null) return jsx('select', rest)
+  const chosen = new Set((Array.isArray(wanted) ? wanted : [wanted]).map(String))
+  const found = new Set<string>()
+  const children = chooseOptions(rest.children, chosen, found)
+  const check = (html: RawHtml) => {
+    const missing = [...chosen].filter((v) => !found.has(v))
+    if (missing.length > 0)
+      throw new Error(
+        `<select> was given the value ${JSON.stringify(missing[0])}, but no <option> it can see ` +
+          'has it. An option inside a fragment or returned from a component is written before ' +
+          'the select can ask it, so put `selected` on that option instead.',
+      )
+    return html
+  }
+  const html = jsx('select', { ...rest, children })
+  return isPromise(html) ? html.then(check) : check(html)
+}
+
+export function jsx(type: string | Component | typeof Fragment, props: ElementProps | null): Html {
+  const actual = props ?? {}
+
+  if (type === Fragment) return toHtml(renderChild(actual.children))
+
+  if (typeof type === 'function') return toHtml(renderChild(type(actual)))
+
+  if (type === 'select' && (actual.value != null || actual.defaultValue != null))
+    return select(actual)
+
+  for (const [name, value] of Object.entries(actual)) {
+    if (name !== 'children' && name !== 'setInnerHTML' && isPromise(value))
+      throw new Error(
+        `The "${name}" attribute of <${type}> is a promise. Await it before rendering the element.`,
+      )
+  }
+  const attributes = formControl(type, actual)
+  if (type === 'optgroup') return optgroup(attributes)
+  const open = `<${type}${serializeAttributes(attributes, type)}`
+  if (VOID_ELEMENTS.has(type)) return new RawHtml(`${open} />`)
+  const inner = innerHtml(type, attributes)
+  if (type === 'option') {
+    if (!isPromise(inner)) return new OptionHtml(attributes, inner)
+    const option = inner.then((done) => new OptionHtml(attributes, done))
+    option.catch(() => {})
+    return option
+  }
+  return toHtml(inner, (done) => `${open}>${done}</${type}>`)
+}
+
+export const jsxs = jsx
+export const jsxDEV = jsx
+
+/**
+ * What a view's `.tsx` compiles against: each tag with its own attributes (see
+ * `jsx-attributes.ts`), and markup out. `@crombolo/crombolo/loose` is the same runtime
+ * with any attribute on any tag, for a site not ready to be checked.
+ */
+export declare namespace JSX {
+  /** What a JSX expression is: markup, or a promise of it once anything in it is async. */
+  type Element = Html
+  /**
+   * What may stand in a JSX tag position. Without this, TypeScript requires a
+   * component's declared return type to be assignable to `Element`, so a
+   * component returning plain text or a list would be rejected.
+   *
+   * The props are `never` rather than `ElementProps` so that a component
+   * declaring its own prop type still fits: parameters are contravariant, so
+   * pinning them here would reject every component that takes anything more
+   * specific than `ElementProps` — which is all of them. Props are checked
+   * against the component's own signature regardless; this constrains only what
+   * may stand in the tag position.
+   */
+  type ElementType = string | ((props: never) => Child)
+  interface IntrinsicElements extends KnownElements {
+    [custom: `${string}-${string}`]: CustomElementAttributes
+  }
+  interface IntrinsicAttributes {
+    key?: string | number | bigint | null
+  }
+  interface ElementChildrenAttribute {
+    children: unknown
+  }
+}
+
+/** Renders a template's return value to HTML: a string, or a promise of one when anything in it is async. */
+export function renderToString(child: Child): string | Promise<string> {
+  return renderChild(child)
+}
+
+/**
+ * `jsx()` for markup that must be ready now: the built-in components, whose
+ * return types promise `RawHtml`. Refuses a promise rather than handing one on.
+ */
+export function element(
+  type: string | Component | typeof Fragment,
+  props: ElementProps | null,
+): RawHtml {
+  const html = jsx(type, props)
+  if (isPromise(html))
+    throw new Error(
+      `<${typeof type === 'string' ? type : 'component'}> was given an async child, which this element cannot wait for.`,
+    )
+  return html
+}

package/src/loose/jsx-runtime.ts

@@ -0,0 +1,21 @@
+/**
+ * The same JSX runtime with unchecked attributes: any attribute on any tag, and
+ * a JSX expression typed as text. For a site that is upgrading and has views
+ * the checked types would flag; set `"jsxImportSource": "@crombolo/crombolo/loose"`.
+ * What renders is identical either way.
+ */
+import type { Child, ElementProps } from '../jsx-runtime.ts'
+
+export type { Child, ElementProps } from '../jsx-runtime.ts'
+export { Fragment, jsx, jsxDEV, jsxs } from '../jsx-runtime.ts'
+
+export declare namespace JSX {
+  type Element = string
+  type ElementType = string | ((props: never) => Child)
+  interface IntrinsicElements {
+    [tag: string]: ElementProps
+  }
+  interface ElementChildrenAttribute {
+    children: unknown
+  }
+}

package/src/media.ts

@@ -0,0 +1,205 @@
+/**
+ * Media as templates see it: a published media item with its file URL, and
+ * what the Media Picker and Image Cropper yield — the item with its crops,
+ * each crop reachable as a URL the media route resizes and cuts.
+ */
+import type { PublishedProperty } from './model.ts'
+
+export interface Crop {
+  alias: string
+  width: number
+  height: number
+  /** Fractions trimmed from each edge, as the cropper stores them; null means "around the focal point". */
+  coordinates: { x1: number; y1: number; x2: number; y2: number } | null
+}
+
+export interface FocalPoint {
+  left: number
+  top: number
+}
+
+/** A crop URL: a named crop, or any size around the focal point. */
+export type CropRequest =
+  | string
+  | { width?: number; height?: number; mode?: string; format?: string }
+
+/** `url` with the query that yields `request`, given the crops and focal point in force. */
+export function cropUrl(
+  url: string,
+  crops: readonly Crop[],
+  focalPoint: FocalPoint | null,
+  request: CropRequest,
+): string | null {
+  const params = new URLSearchParams()
+  if (typeof request === 'string') {
+    const crop = crops.find((c) => c.alias === request)
+    if (!crop) return null
+    if (crop.coordinates)
+      params.set(
+        'cc',
+        [crop.coordinates.x1, crop.coordinates.y1, crop.coordinates.x2, crop.coordinates.y2].join(
+          ',',
+        ),
+      )
+    else if (focalPoint) params.set('rxy', `${focalPoint.left},${focalPoint.top}`)
+    params.set('width', String(crop.width))
+    params.set('height', String(crop.height))
+  } else {
+    if (focalPoint && request.width && request.height)
+      params.set('rxy', `${focalPoint.left},${focalPoint.top}`)
+    if (request.width) params.set('width', String(request.width))
+    if (request.height) params.set('height', String(request.height))
+    if (request.mode) params.set('rmode', request.mode.toLowerCase())
+    if (request.format) params.set('format', request.format)
+  }
+  const query = params.toString()
+  return query ? `${url}?${query}` : url
+}
+
+const numberOr = (value: unknown, fallback: number) => {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : fallback
+}
+
+/** Crops as the cropper stores them, tolerating partial data. */
+export function readCrops(value: unknown): Crop[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((raw): Crop[] => {
+    const crop = raw as Record<string, unknown>
+    if (typeof crop.alias !== 'string') return []
+    const c = crop.coordinates as Record<string, unknown> | null | undefined
+    return [
+      {
+        alias: crop.alias,
+        width: numberOr(crop.width, 0),
+        height: numberOr(crop.height, 0),
+        coordinates: c
+          ? {
+              x1: numberOr(c.x1, 0),
+              y1: numberOr(c.y1, 0),
+              x2: numberOr(c.x2, 0),
+              y2: numberOr(c.y2, 0),
+            }
+          : null,
+      },
+    ]
+  })
+}
+
+export function readFocalPoint(value: unknown): FocalPoint | null {
+  const f = value as Record<string, unknown> | null | undefined
+  if (!f) return null
+  return { left: numberOr(f.left, 0.5), top: numberOr(f.top, 0.5) }
+}
+
+/** An Image Cropper value: the file, its crops and focal point. `toString()` is its URL. */
+export class ImageCropperValue {
+  readonly src: string
+  readonly crops: Crop[]
+  readonly focalPoint: FocalPoint | null
+
+  constructor(value: { src?: unknown; crops?: unknown; focalPoint?: unknown }) {
+    this.src = typeof value.src === 'string' ? value.src : ''
+    this.crops = readCrops(value.crops)
+    this.focalPoint = readFocalPoint(value.focalPoint)
+  }
+
+  get url(): string {
+    return this.src
+  }
+
+  cropUrl(request: CropRequest): string | null {
+    return this.src ? cropUrl(this.src, this.crops, this.focalPoint, request) : null
+  }
+
+  toString(): string {
+    return this.src
+  }
+}
+
+/** One published media item. */
+export class PublishedMedia {
+  readonly key: string
+  readonly id: number
+  readonly name: string
+  readonly mediaType: { alias: string }
+  readonly properties: PublishedProperty[]
+
+  constructor(init: {
+    key: string
+    id: number
+    name: string
+    mediaTypeAlias: string
+    properties: PublishedProperty[]
+  }) {
+    this.key = init.key
+    this.id = init.id
+    this.name = init.name
+    this.mediaType = { alias: init.mediaTypeAlias }
+    this.properties = init.properties
+  }
+
+  /** The file's URL: what `umbracoFile` holds. */
+  get url(): string {
+    const file = this.properties.find((p) => p.alias === 'umbracoFile')?.value
+    if (typeof file === 'string') return file
+    const src = (file as { src?: unknown } | null | undefined)?.src
+    return typeof src === 'string' ? src : ''
+  }
+
+  /** The file as an Image Cropper value, for its crops and focal point. */
+  get image(): ImageCropperValue {
+    const file = this.properties.find((p) => p.alias === 'umbracoFile')?.value
+    return new ImageCropperValue(
+      typeof file === 'string' ? { src: file } : ((file as object | null | undefined) ?? {}),
+    )
+  }
+
+  value(alias: string): unknown {
+    return this.properties.find((p) => p.alias === alias)?.value ?? null
+  }
+
+  text(alias: string): string {
+    const value = this.value(alias)
+    return value === null || value === undefined ? '' : String(value)
+  }
+}
+
+/**
+ * A Media Picker entry: the media item, with the crops and focal point this
+ * pick overrides (Umbraco's `MediaWithCrops`).
+ */
+export class MediaWithCrops {
+  readonly key: string
+  readonly media: PublishedMedia
+  readonly crops: Crop[]
+  readonly focalPoint: FocalPoint | null
+
+  constructor(
+    media: PublishedMedia,
+    local: { key?: unknown; crops?: unknown; focalPoint?: unknown },
+  ) {
+    this.media = media
+    this.key = typeof local.key === 'string' ? local.key : media.key
+    const own = media.image
+    const localCrops = readCrops(local.crops)
+    // The pick's own crop wins; the media's crops fill in the rest.
+    this.crops = [
+      ...localCrops,
+      ...own.crops.filter((c) => !localCrops.some((l) => l.alias === c.alias)),
+    ]
+    this.focalPoint = readFocalPoint(local.focalPoint) ?? own.focalPoint
+  }
+
+  get name(): string {
+    return this.media.name
+  }
+
+  get url(): string {
+    return this.media.url
+  }
+
+  cropUrl(request: CropRequest): string | null {
+    return this.url ? cropUrl(this.url, this.crops, this.focalPoint, request) : null
+  }
+}