@vidact/runtime 0.2.0-beta.0 → 0.2.0-beta.5

package/src/raw-html.ts

@@ -0,0 +1,206 @@
+import {
+  isCompiledBinding,
+  mountCompiledPropTransition,
+  type CompiledPropTransition,
+} from './compiled/core.ts'
+import { HYDRATION_PREFIX, HydrationMismatch, isHydrating } from './hydration-bridge.ts'
+
+const RAW_HTML_PUBLICATION_PRIORITY = 100
+const rawHtmlHosts = new WeakSet<HTMLElement>()
+const DEV = typeof __VIDACT_DEV__ === 'undefined' || __VIDACT_DEV__
+
+export function mountRawHtmlProp(
+  element: HTMLElement,
+  value: unknown,
+  children: readonly unknown[],
+): void {
+  if (value === null || value === undefined) return
+  if (isCompiledBinding(value)) {
+    mountCompiledPropTransition(
+      value,
+      (initial) => mountRawHtml(element, initial, children),
+      (next, previous) => prepareRawHtml(element, next, previous, children),
+    )
+    return
+  }
+  mountRawHtml(element, value, children)
+}
+
+function mountRawHtml(element: HTMLElement, value: unknown, children: readonly unknown[]): void {
+  const html = readRawHtml(element, value, children)
+  if (html === null || html === undefined) return
+  const container = rawHtmlContainer(element)
+  const staged = parseRawHtml(element, html)
+  if (isHydrating()) {
+    if (!hasEqualHydrationRawChildren(container, staged)) {
+      throw new HydrationMismatch('server raw HTML does not match the client value')
+    }
+  } else {
+    container.replaceChildren(adoptRawHtml(element, staged))
+  }
+  rawHtmlHosts.add(element)
+}
+
+function hasEqualHydrationRawChildren(container: Node, expected: DocumentFragment): boolean {
+  const start = container.firstChild
+  const end = container.lastChild
+  if (
+    !(start instanceof Comment) ||
+    start.data !== `${HYDRATION_PREFIX}:h` ||
+    !(end instanceof Comment) ||
+    end.data !== `/${HYDRATION_PREFIX}:h`
+  ) {
+    return false
+  }
+  const actual: Node[] = []
+  for (let node = start.nextSibling; node !== null && node !== end; node = node.nextSibling) {
+    actual.push(node)
+  }
+  if (actual.length !== expected.childNodes.length) return false
+  for (let index = 0; index < actual.length; index += 1) {
+    if (!actual[index]?.isEqualNode(expected.childNodes[index] ?? null)) return false
+  }
+  return true
+}
+
+function prepareRawHtml(
+  element: HTMLElement,
+  nextValue: unknown,
+  previousValue: unknown,
+  children: readonly unknown[],
+): CompiledPropTransition | undefined {
+  const nextHtml = readRawHtml(element, nextValue, children)
+  const previousHtml = readRawHtml(element, previousValue, children)
+  if (nextHtml === null || nextHtml === undefined || nextHtml === previousHtml) return undefined
+
+  const staged = parseRawHtml(element, nextHtml)
+  const container = rawHtmlContainer(element)
+  const wasRawHtmlHost = rawHtmlHosts.has(element)
+  let previousNodes: Node[] | undefined
+  return [
+    () => {
+      // A reactive script `type` prop commits before the raw subtree.
+      assertExecutableRawHtmlTarget(element)
+      const adopted = adoptRawHtml(element, staged)
+      previousNodes = [...container.childNodes]
+      container.replaceChildren(adopted)
+      rawHtmlHosts.add(element)
+    },
+    () => {
+      if (previousNodes === undefined) return
+      container.replaceChildren(...previousNodes)
+      if (!wasRawHtmlHost) rawHtmlHosts.delete(element)
+      previousNodes = undefined
+    },
+    undefined,
+    undefined,
+    RAW_HTML_PUBLICATION_PRIORITY,
+  ]
+}
+
+export function validateRawHtmlRelatedProp(element: HTMLElement, name: string): void {
+  if (name === 'type' && rawHtmlHosts.has(element)) assertExecutableRawHtmlTarget(element)
+}
+
+function readRawHtml(element: HTMLElement, value: unknown, children: readonly unknown[]): unknown {
+  if (value === null || value === undefined) return undefined
+  assertRawHtmlPropTarget(element)
+  if (typeof value !== 'object' || !('__html' in value)) {
+    throw new Error(
+      DEV
+        ? '`props.dangerouslySetInnerHTML` must be in the form `{__html: ...}`. Please visit https://react.dev/link/dangerously-set-inner-html for more information.'
+        : 'V601',
+    )
+  }
+  const html = value['__html']
+  if (html === null || html === undefined) return html
+  if (children.some((child) => child !== null && child !== undefined)) {
+    throw new Error(
+      DEV ? 'Can only set one of `children` or `props.dangerouslySetInnerHTML`.' : 'V602',
+    )
+  }
+  assertExecutableRawHtmlTarget(element)
+  return html
+}
+
+function assertRawHtmlPropTarget(element: HTMLElement): void {
+  const tag = element.localName
+  if (isVoidHtmlElement(tag)) {
+    throw new Error(
+      DEV
+        ? `${tag} is a void element tag and must neither have \`children\` nor use \`dangerouslySetInnerHTML\`.`
+        : 'V603',
+    )
+  }
+  if (tag === 'textarea') {
+    throw new Error(DEV ? '`dangerouslySetInnerHTML` does not make sense on <textarea>.' : 'V604')
+  }
+}
+
+function assertExecutableRawHtmlTarget(element: HTMLElement): void {
+  const tag = element.localName
+  if (tag === 'script' && isExecutableScript(element as HTMLScriptElement)) {
+    throw new Error(
+      DEV
+        ? 'dangerouslySetInnerHTML on an executable <script> is unsupported because direct-created scripts execute when connected; use a non-executable data MIME type'
+        : 'V605',
+    )
+  }
+}
+
+function isVoidHtmlElement(tag: string): boolean {
+  return (
+    tag === 'area' ||
+    tag === 'base' ||
+    tag === 'br' ||
+    tag === 'col' ||
+    tag === 'embed' ||
+    tag === 'hr' ||
+    tag === 'img' ||
+    tag === 'input' ||
+    tag === 'keygen' ||
+    tag === 'link' ||
+    tag === 'menuitem' ||
+    tag === 'meta' ||
+    tag === 'param' ||
+    tag === 'source' ||
+    tag === 'track' ||
+    tag === 'wbr'
+  )
+}
+
+function isExecutableScript(element: HTMLScriptElement): boolean {
+  const type = element.type.trim().toLowerCase().split(';', 1)[0] ?? ''
+  if (type === '' || type === 'module' || type === 'importmap' || type === 'speculationrules') {
+    return true
+  }
+  return (
+    /^(?:application|text)\/(?:x-)?(?:java|ecma)script(?:1\.[0-5])?$/.test(type) ||
+    type === 'text/jscript' ||
+    type === 'text/livescript'
+  )
+}
+
+function parseRawHtml(element: HTMLElement, html: unknown): DocumentFragment {
+  const stagingDocument = element.ownerDocument.implementation.createHTMLDocument()
+  const staging =
+    element.localName === 'noscript'
+      ? (element.cloneNode(false) as HTMLElement)
+      : stagingDocument.createElement(element.localName.includes('-') ? 'div' : element.localName)
+  Reflect.set(staging, 'innerHTML', html)
+  const fragment = staging.ownerDocument.createDocumentFragment()
+  fragment.append(...rawHtmlContainer(staging).childNodes)
+  return fragment
+}
+
+function rawHtmlContainer(element: HTMLElement): HTMLElement | DocumentFragment {
+  return element instanceof HTMLTemplateElement ? element.content : element
+}
+
+function adoptRawHtml(element: HTMLElement, staged: DocumentFragment): DocumentFragment {
+  if (staged.ownerDocument === element.ownerDocument) return staged
+  const adopted = element.ownerDocument.createDocumentFragment()
+  adopted.append(...staged.childNodes)
+  element.ownerDocument.defaultView?.customElements.upgrade(adopted)
+  return adopted
+}

package/src/ref.ts

@@ -0,0 +1,13 @@
+export interface MutableRef<T> {
+  current: T
+}
+
+/** Creates the plain ref object used by dependency initialization outside component hooks. */
+export function createRef<T>(): MutableRef<T | null> {
+  return { current: null }
+}
+
+/** Creates the stable ref cell captured by a component's one-time execution. */
+export function useRef<T>(initialValue: T): MutableRef<T> {
+  return { current: initialValue }
+}

package/src/renderable-protocol.ts

@@ -0,0 +1,63 @@
+export const RENDERABLE = Symbol.for('vidact.v1.Renderable')
+
+export interface RenderableProtocol {
+  readonly [RENDERABLE]: {
+    readonly identity: unknown
+    readonly input: unknown
+    readonly reconcile: boolean
+    readonly construct: (input: never) => unknown
+  }
+}
+
+/**
+ * Cloning a renderable pulls in the element-construction module, which most
+ * compiled apps never touch. The renderable module registers its clone the
+ * first time an element capability is created, so `jsx` can reach it without
+ * importing it, and bundles that never build elements leave it out.
+ */
+export type RenderableClone = (
+  value: RenderableProtocol,
+  overrides: Record<string, unknown>,
+) => unknown
+
+let renderableClone: RenderableClone | undefined
+
+export function installRenderableClone(clone: RenderableClone): void {
+  renderableClone = clone
+}
+
+export function renderableCloneHandler(): RenderableClone | undefined {
+  return renderableClone
+}
+
+export function isRenderableProtocol(value: unknown): value is RenderableProtocol {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.hasOwn(value, RENDERABLE) &&
+    typeof (value as RenderableProtocol)[RENDERABLE]?.construct === 'function'
+  )
+}
+
+export function materializeRenderable(value: RenderableProtocol): unknown {
+  const internals = value[RENDERABLE]
+  return internals.construct(internals.input as never)
+}
+
+export function materializeRenderableWithInput(value: RenderableProtocol, input: unknown): unknown {
+  return value[RENDERABLE].construct(input as never)
+}
+
+export function renderableIdentity(value: RenderableProtocol): unknown {
+  return value[RENDERABLE].identity
+}
+
+export function canReconcileRenderable(value: RenderableProtocol): boolean {
+  return value[RENDERABLE].reconcile
+}
+
+export function renderablePropsSnapshot(value: RenderableProtocol): Record<PropertyKey, unknown> {
+  const props = (value as RenderableProtocol & { readonly props: Record<PropertyKey, unknown> })
+    .props
+  return Object.fromEntries(Reflect.ownKeys(props).map((name) => [name, Reflect.get(props, name)]))
+}

package/src/renderable.ts

@@ -0,0 +1,283 @@
+import { binding, isCompiledBinding } from './compiled/core.ts'
+import type { CompiledBinding, CompiledRenderValue, CompiledScope } from './compiled/types.ts'
+import { Fragment, h, type DirectComponent } from './direct-dom.ts'
+import {
+  installRenderableClone,
+  isRenderableProtocol,
+  RENDERABLE,
+  type RenderableClone,
+} from './renderable-protocol.ts'
+import type { SourceMask } from './source-mask.ts'
+import { unionSources } from './source-mask.ts'
+import { compiledSpread } from './spread.ts'
+
+const DEV = typeof __VIDACT_DEV__ === 'undefined' || __VIDACT_DEV__
+const SPECIAL_PROPS = new Set(['children', 'key', 'ref'])
+
+type Props = Record<string, unknown>
+export type RenderablePropsInput = Props | CompiledBinding<Props>
+
+type RenderableInternals = {
+  readonly identity: unknown
+  readonly input: RenderablePropsInput
+  readonly reconcile: boolean
+  readonly construct: (input: RenderablePropsInput) => CompiledRenderValue
+}
+
+export interface CompiledRenderable {
+  readonly props: Props
+  readonly [RENDERABLE]: RenderableInternals
+}
+
+export function createRenderable(
+  input: RenderablePropsInput,
+  construct: (input: RenderablePropsInput) => CompiledRenderValue,
+  identity: unknown = construct,
+  reconcile = false,
+): CompiledRenderable {
+  installRenderableClone(cloneRenderable as RenderableClone)
+  readPropsInput(input)
+  const capability = {
+    props: propsView(input),
+  } as CompiledRenderable
+  Object.defineProperty(capability, RENDERABLE, {
+    configurable: false,
+    enumerable: false,
+    value: { identity, input, reconcile, construct } satisfies RenderableInternals,
+  })
+  return capability
+}
+
+export function isRenderable(value: unknown): value is CompiledRenderable {
+  return isRenderableProtocol(value)
+}
+
+export function createReactElement(
+  type: string | typeof Fragment | DirectComponent | CompiledRenderable,
+  props: Props | null,
+  ...children: CompiledRenderValue[]
+): CompiledRenderable {
+  const input: Props = { ...props }
+  if (children.length === 1) input.children = children[0]
+  else if (children.length > 1) input.children = children
+
+  if (typeof type === 'string') return createIntrinsicRenderable(type, input)
+
+  return createRenderable(
+    input,
+    (currentInput) => {
+      if (isRenderable(type)) return cloneRenderable(type, currentInput)
+      const resolved = readPropsInput(currentInput)
+      const { children: currentChildren, key: _key, ...currentProps } = resolved
+      return Object.hasOwn(resolved, 'children')
+        ? h(type, currentProps, currentChildren as CompiledRenderValue)
+        : h(type, currentProps)
+    },
+    type,
+    false,
+  )
+}
+
+export function renderableToArray(value: unknown): [CompiledRenderable] {
+  if (!isRenderable(value)) {
+    throw new TypeError(
+      DEV ? 'Children.toArray requires one compiled renderable capability' : 'V107',
+    )
+  }
+  return [value]
+}
+
+export function renderableMarker(value: unknown): undefined {
+  if (!isRenderable(value)) {
+    throw new TypeError(
+      DEV ? 'React element metadata requires a compiled renderable capability' : 'V107',
+    )
+  }
+  return undefined
+}
+
+export function cloneRenderable(
+  value: unknown,
+  overrides?: RenderablePropsInput | null,
+  childrenOverride?: CompiledRenderValue | CompiledBinding<CompiledRenderValue>,
+): CompiledRenderValue {
+  if (!isRenderable(value)) {
+    throw new TypeError(DEV ? 'cloneRenderable requires a compiled renderable capability' : 'V107')
+  }
+  const internals = value[RENDERABLE]
+  let input = mergeInputs(internals.input, overrides)
+  if (arguments.length >= 3) input = mergeInputs(input, childrenInput(childrenOverride))
+  return createRenderable(
+    input,
+    internals.construct,
+    internals.identity,
+    internals.reconcile,
+  ) as unknown as CompiledRenderValue
+}
+
+export function cloneRenderableComponent(props: Record<string, unknown>): CompiledRenderValue {
+  const value = isCompiledBinding(props.value) ? props.value[1]() : props.value
+  if (Object.hasOwn(props, 'childrenOverride')) {
+    return cloneRenderable(
+      value,
+      props.overrides as RenderablePropsInput | null | undefined,
+      props.childrenOverride as CompiledRenderValue | CompiledBinding<CompiledRenderValue>,
+    )
+  }
+  return cloneRenderable(value, props.overrides as RenderablePropsInput | null | undefined)
+}
+
+export function keyedFragmentComponent(props: Record<string, unknown>): CompiledRenderValue {
+  return props.children as CompiledRenderValue
+}
+
+export function renderableProps(input: RenderablePropsInput): Record<string, unknown> {
+  const ordinary = projectInput(input, (props) =>
+    Object.fromEntries(
+      Reflect.ownKeys(props)
+        .filter((name) => typeof name !== 'string' || !SPECIAL_PROPS.has(name))
+        .map((name) => [name, Reflect.get(props, name)]),
+    ),
+  )
+  return isCompiledBinding(ordinary) ? compiledSpread(ordinary, []) : ordinary
+}
+
+export function renderableChildren(input: RenderablePropsInput): CompiledRenderValue {
+  return projectInput(input, (props) => props.children) as CompiledRenderValue
+}
+
+export function renderableRef(input: RenderablePropsInput): unknown {
+  return projectInput(input, (props) => props.ref)
+}
+
+export function forwardedRef(props: Record<string, unknown>): unknown {
+  return props.ref
+}
+
+export function dynamicIntrinsicComponent(props: Record<string, unknown>): CompiledRenderValue {
+  const tag = isCompiledBinding(props.tag) ? props.tag[1]() : props.tag
+  if (typeof tag !== 'string') {
+    throw new TypeError(DEV ? 'dynamic intrinsic construction requires a string tag' : 'V107')
+  }
+  let input = props.props as RenderablePropsInput
+  if (Object.hasOwn(props, 'childrenOverride')) {
+    input = mergeInputs(
+      input,
+      childrenInput(
+        props.childrenOverride as CompiledRenderValue | CompiledBinding<CompiledRenderValue>,
+      ),
+    )
+  }
+  return createIntrinsicRenderable(tag, input) as unknown as CompiledRenderValue
+}
+
+function createIntrinsicRenderable(tag: string, input: RenderablePropsInput): CompiledRenderable {
+  return createRenderable(
+    input,
+    (currentInput) =>
+      h(
+        tag,
+        { ...renderableProps(currentInput), ref: renderableRef(currentInput) },
+        renderableChildren(currentInput),
+      ),
+    tag,
+    true,
+  )
+}
+
+function propsView(input: RenderablePropsInput): Props {
+  return new Proxy(
+    {},
+    {
+      get(_target, property) {
+        const value = Reflect.get(readPropsInput(input), property)
+        return isCompiledBinding(value) ? value[1]() : value
+      },
+      getOwnPropertyDescriptor(_target, property) {
+        return Object.hasOwn(readPropsInput(input), property)
+          ? { configurable: true, enumerable: true }
+          : undefined
+      },
+      has(_target, property) {
+        return Reflect.has(readPropsInput(input), property)
+      },
+      ownKeys() {
+        return Reflect.ownKeys(readPropsInput(input))
+      },
+    },
+  )
+}
+
+function childrenInput(
+  value: CompiledRenderValue | CompiledBinding<CompiledRenderValue> | undefined,
+): RenderablePropsInput {
+  if (!isCompiledBinding(value)) return { children: value }
+  return binding(value[2], value[3], () => ({ children: value[1]() }), value[4], value[5])
+}
+
+function mergeInputs(
+  authored: RenderablePropsInput,
+  overrides: RenderablePropsInput | null | undefined,
+): RenderablePropsInput {
+  if (overrides == null) return authored
+  if (!isCompiledBinding(authored) && !isCompiledBinding(overrides)) {
+    return { ...readPropsInput(authored), ...readPropsInput(overrides) }
+  }
+  const inputs = [authored, overrides]
+  const subscriptions = collectSubscriptions(inputs)
+  const evaluate = (): Props => ({
+    ...readPropsInput(authored),
+    ...readPropsInput(overrides),
+  })
+  return binding(
+    subscriptions[0]![0],
+    subscriptions[0]![1],
+    evaluate,
+    subscriptions[1]?.[0],
+    subscriptions[1]?.[1],
+  )
+}
+
+function projectInput<Value>(
+  input: RenderablePropsInput,
+  project: (props: Props) => Value,
+): Value | CompiledBinding<Value> {
+  if (!isCompiledBinding(input)) return project(readPropsInput(input))
+  return binding(input[2], input[3], () => project(readPropsInput(input)), input[4], input[5])
+}
+
+function collectSubscriptions(
+  inputs: readonly RenderablePropsInput[],
+): Array<[CompiledScope, SourceMask]> {
+  const subscriptions = new Map<CompiledScope, SourceMask>()
+  for (const input of inputs) {
+    if (!isCompiledBinding(input)) continue
+    addSubscription(subscriptions, input[2], input[3])
+    if (input[4] !== undefined && input[5] !== undefined) {
+      addSubscription(subscriptions, input[4], input[5])
+    }
+  }
+  if (subscriptions.size > 2) {
+    throw new TypeError(
+      DEV ? 'a compiled renderable can combine reactive props from at most two scopes' : 'V107',
+    )
+  }
+  return [...subscriptions]
+}
+
+function addSubscription(
+  subscriptions: Map<CompiledScope, SourceMask>,
+  scope: CompiledScope,
+  reads: SourceMask,
+): void {
+  const current = subscriptions.get(scope)
+  subscriptions.set(scope, current === undefined ? reads : unionSources(current, reads))
+}
+
+function readPropsInput(input: RenderablePropsInput): Props {
+  const value = isCompiledBinding(input) ? input[1]() : input
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(DEV ? 'compiled renderable props must evaluate to an object' : 'V107')
+  }
+  return value
+}

package/src/retained-ui.ts

@@ -0,0 +1,19 @@
+import { enableRetainedUi, retainedActivity } from './compiled/core.ts'
+import type { CompiledBinding, CompiledRenderValue, StructuralBinding } from './compiled/types.ts'
+import { enableRetainedUiStyles } from './dom/styles.ts'
+
+export interface ActivityProps {
+  readonly children?: (() => CompiledRenderValue) | readonly [() => CompiledRenderValue]
+  readonly mode: 'visible' | 'hidden' | CompiledBinding<'visible' | 'hidden'>
+  readonly name?: string
+}
+
+export function Activity(props: ActivityProps): StructuralBinding {
+  const render = Array.isArray(props.children) ? props.children[0] : props.children
+  if (typeof render !== 'function') {
+    throw new TypeError('Activity children must be a compiler-generated render function')
+  }
+  enableRetainedUi()
+  enableRetainedUiStyles()
+  return retainedActivity(props.mode, render)
+}