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

package/src/index.ts

@@ -0,0 +1,92 @@
+// oxlint-disable-next-line typescript/triple-slash-reference -- Include the build define in consuming TypeScript programs.
+/// <reference path="./env.d.ts" />
+
+export {
+  binding,
+  choose,
+  compiledEvent,
+  compiledEffect,
+  compiledImperativeHandle,
+  compiledInsertionEffect,
+  compiledLayoutEffect,
+  compiledRoot,
+  createCompiledContext,
+  createCompiledEffectEvent,
+  createCompiledExternalStore,
+  createCompiledId,
+  createCompiledMemo,
+  createCompiledProp,
+  createCompiledReducer,
+  createCompiledRestProp,
+  createCompiledScope,
+  createCompiledState,
+  createContext,
+  createNarrowCompiledScope,
+  createPortal,
+  deferred,
+  dispatch,
+  errorBoundary,
+  indexed,
+  keyed,
+  mountCompiled,
+  mountCompiledRef,
+  objectRest,
+  runWithCompiledContext,
+  use,
+  useCallback,
+  useContext,
+  useEffect,
+  useEffectEvent,
+  useId,
+  useImperativeHandle,
+  useInsertionEffect,
+  useLayoutEffect,
+  useMemo,
+  useSyncExternalStore,
+  when,
+  type ChoiceMode,
+  type MountCompiledOptions,
+} from './compiled/core.ts'
+export type {
+  CompiledBinding,
+  CompiledComponentResult,
+  CompiledContext,
+  CompiledErrorHandler,
+  CompiledRenderValue,
+  CompiledScope,
+  OwnedBlock,
+  StructuralBinding,
+} from './compiled/types.ts'
+export { compiledComponentSpread } from './component-spread.ts'
+export {
+  Fragment,
+  h,
+  type DirectChild,
+  type DirectComponent,
+  type DirectProps,
+} from './direct-dom.ts'
+export { nestedProp } from './nested-prop.ts'
+export { assertRuntimeProtocol, VIDACT_RUNTIME_PROTOCOL } from './protocol.ts'
+export { createRef, useRef, type MutableRef } from './ref.ts'
+export {
+  cloneRenderable,
+  cloneRenderableComponent,
+  createReactElement,
+  createReactElement as createElement,
+  createRenderable,
+  dynamicIntrinsicComponent,
+  forwardedRef,
+  isRenderable,
+  keyedFragmentComponent,
+  renderableChildren,
+  renderableMarker,
+  renderableProps,
+  renderableRef,
+  renderableToArray,
+  type CompiledRenderable,
+  type RenderablePropsInput,
+} from './renderable.ts'
+export { createRoot, mountHotRoot, type CompiledRoot, type HotContext } from './root.ts'
+export { combineSources, intersectsSources, source, type SourceMask } from './source-mask.ts'
+export { compiledSpread } from './spread.ts'
+export type { StateUpdate } from './state-slot.ts'

package/src/indexed-list.ts

@@ -0,0 +1,20 @@
+import { createKeyedList, type KeyedList, type KeyedRenderResult } from './keyed-list.ts'
+
+export interface IndexedListOptions<T> {
+  readonly render: (value: T, index: number) => KeyedRenderResult<T>
+}
+
+export type IndexedList<T> = KeyedList<T>
+
+/**
+ * Reconciles records by their current position. Existing owners are retained at
+ * an index and receive the new value at that index, matching React's unkeyed
+ * collection identity semantics.
+ */
+export function createIndexedList<T>(
+  parent: Node,
+  options: IndexedListOptions<T>,
+  before: Node | null = null,
+): IndexedList<T> {
+  return createKeyedList(parent, { key: (_value, index) => index, render: options.render }, before)
+}

package/src/jsx-runtime.ts

@@ -0,0 +1,55 @@
+// oxlint-disable-next-line typescript/triple-slash-reference -- Include the build define in consuming TypeScript programs.
+/// <reference path="./env.d.ts" />
+
+import { h, type DirectChild, type DirectComponent } from './direct-dom.ts'
+import {
+  isRenderableProtocol,
+  renderableCloneHandler,
+  type RenderableProtocol,
+} from './renderable-protocol.ts'
+import type { CompiledRenderable } from './renderable.ts'
+
+export const Fragment: symbol = Symbol.for('vidact.v1.Fragment')
+
+type ElementType = string | typeof Fragment | DirectComponent | CompiledRenderable
+
+interface JsxProps extends Record<string, unknown> {
+  readonly children?: DirectChild | readonly DirectChild[]
+}
+
+export function jsx(type: ElementType, props: JsxProps | null, _key?: unknown): DirectChild {
+  if (isRenderableProtocol(type)) return cloneElementType(type, props)
+  const children = props?.children
+  const hasChildren = props !== null && Object.hasOwn(props, 'children')
+  if (!hasChildren) return h(type, props)
+  return h(type, props, children)
+}
+
+export function jsxs(type: ElementType, props: JsxProps | null, _key?: unknown): DirectChild {
+  if (isRenderableProtocol(type)) return cloneElementType(type, props)
+  const children = props?.children
+  const hasChildren = props !== null && Object.hasOwn(props, 'children')
+  if (!hasChildren) return h(type, props)
+  return Array.isArray(children) ? h(type, props, ...children) : h(type, props, children)
+}
+
+export function jsxDEV(
+  type: ElementType,
+  props: JsxProps | null,
+  key?: unknown,
+  isStaticChildren = false,
+): DirectChild {
+  return isStaticChildren ? jsxs(type, props, key) : jsx(type, props, key)
+}
+
+/**
+ * A renderable can only reach `jsx` as an element type if something already
+ * built one, which is what registers the clone.
+ */
+function cloneElementType(type: RenderableProtocol, props: JsxProps | null): DirectChild {
+  const clone = renderableCloneHandler()
+  if (clone === undefined) {
+    throw new TypeError('V107')
+  }
+  return clone(type, props ?? {}) as DirectChild
+}

package/src/keyed-list.ts

@@ -0,0 +1,233 @@
+export type KeyedItem<T> = readonly [
+  nodes: readonly Node[],
+  update?: ((value: T, index: number) => void) | undefined,
+  dispose?: (() => void) | undefined,
+]
+
+export type KeyedRenderResult<T> = Node | readonly Node[] | KeyedItem<T>
+
+export interface KeyedListOptions<T, K> {
+  readonly key: (value: T, index: number) => K
+  readonly render: (value: T, index: number) => KeyedRenderResult<T>
+}
+
+export interface KeyedList<T> {
+  readonly dispose: () => void
+  readonly parent: () => Node | null
+  readonly update: (values: readonly T[]) => readonly Node[]
+}
+
+type RecordState<T, K> = readonly [
+  key: K,
+  nodes: readonly Node[],
+  update: ((value: T, index: number) => void) | undefined,
+  dispose: (() => void) | undefined,
+]
+
+const DEV = typeof __VIDACT_DEV__ === 'undefined' || __VIDACT_DEV__
+
+export function createKeyedList<T, K>(
+  parent: Node,
+  options: KeyedListOptions<T, K>,
+  before: Node | null = null,
+): KeyedList<T> {
+  const hydratedRange = claimHydrationArrayRange(parent)
+  const start = hydratedRange?.[0] ?? document.createComment(DEV ? 'vidact:list' : '')
+  const end = hydratedRange?.[1] ?? document.createComment(DEV ? '/vidact:list' : '')
+  if (hydratedRange === undefined) {
+    parent.insertBefore(start, before)
+    parent.insertBefore(end, before)
+  }
+
+  let disposed = false
+  let hydrationPending = hydratedRange !== undefined
+  let records: readonly RecordState<T, K>[] = []
+
+  const update = (values: readonly T[]): readonly Node[] => {
+    if (disposed) throw new Error(DEV ? 'cannot update a disposed keyed list' : 'V801')
+    const currentParent = end.parentNode
+    if (currentParent === null || start.parentNode !== currentParent) {
+      throw new Error(DEV ? 'cannot update a detached keyed list' : 'V802')
+    }
+
+    const keys = values.map(options.key)
+    assertValidKeys(keys)
+    assertUniqueKeys(keys)
+
+    const previousByKey = new Map<K, RecordState<T, K>>()
+    for (const record of records) previousByKey.set(record[0], record)
+    const created: RecordState<T, K>[] = []
+    const retained: Array<readonly [RecordState<T, K>, T, number]> = []
+    let nextRecords: RecordState<T, K>[]
+    try {
+      nextRecords = values.map((value, index): RecordState<T, K> => {
+        const key = keys[index] as K
+        const previous = previousByKey.get(key)
+        if (previous !== undefined) {
+          previousByKey.delete(key)
+          retained.push([previous, value, index])
+          return previous
+        }
+
+        const item = normalizeRenderResult(
+          withHydrationInsertion(parent, end, () => options.render(value, index)),
+        )
+        const record: RecordState<T, K> = [key, item[0], item[1], item[2]]
+        created.push(record)
+        return record
+      })
+      for (const [record, value, index] of retained) record[2]?.(value, index)
+    } catch (error) {
+      disposeRecords(currentParent, created)
+      throw error
+    }
+
+    const cleanup = disposeRecords(currentParent, previousByKey.values())
+
+    const activeElement =
+      document.activeElement instanceof HTMLElement &&
+      currentParent.contains(document.activeElement)
+        ? document.activeElement
+        : null
+    const selectionControl =
+      activeElement instanceof HTMLInputElement || activeElement instanceof HTMLTextAreaElement
+        ? activeElement
+        : null
+    const selection =
+      selectionControl === null
+        ? null
+        : ([selectionControl.selectionStart, selectionControl.selectionEnd] as const)
+    let cursor: Node = end
+    for (let recordIndex = nextRecords.length - 1; recordIndex >= 0; recordIndex -= 1) {
+      const record = nextRecords[recordIndex] as RecordState<T, K>
+      for (let nodeIndex = record[1].length - 1; nodeIndex >= 0; nodeIndex -= 1) {
+        const node = record[1][nodeIndex] as Node
+        if (node.nextSibling !== cursor) moveBefore(currentParent, node, cursor)
+        cursor = node
+      }
+    }
+    if (
+      activeElement !== null &&
+      document.activeElement !== activeElement &&
+      currentParent.contains(activeElement)
+    ) {
+      activeElement.focus({ preventScroll: true })
+      if (
+        selectionControl !== null &&
+        selection !== null &&
+        selection[0] !== null &&
+        selection[1] !== null
+      ) {
+        selectionControl.setSelectionRange(selection[0], selection[1])
+      }
+    }
+
+    records = nextRecords
+    if (hydrationPending) {
+      hydrationPending = false
+      finishHydrationArrayRange(currentParent, end)
+    }
+    if (cleanup[1]) throw cleanup[0]
+    return created.flatMap((record) => record[1])
+  }
+
+  const dispose = (): void => {
+    if (disposed) return
+    disposed = true
+    const currentParent = end.parentNode
+    const cleanup =
+      currentParent === null
+        ? ([undefined, false] as const)
+        : disposeRecords(currentParent, records)
+    records = []
+    start.remove()
+    end.remove()
+    if (cleanup[1]) throw cleanup[0]
+  }
+
+  return { dispose, parent: () => end.parentNode, update }
+}
+
+function moveBefore(parent: Node, node: Node, before: Node): void {
+  const statePreservingParent = parent as Node & {
+    moveBefore?: (node: Node, before: Node | null) => void
+  }
+  if (statePreservingParent.moveBefore !== undefined && node.parentNode === parent) {
+    statePreservingParent.moveBefore(node, before)
+  } else {
+    parent.insertBefore(node, before)
+  }
+}
+
+function assertValidKeys<K>(keys: readonly K[]): void {
+  for (const key of keys) {
+    if (typeof key !== 'string' && typeof key !== 'number' && typeof key !== 'bigint') {
+      throw new Error(DEV ? `invalid key in keyed list: ${String(key)}` : 'V803')
+    }
+  }
+}
+
+function assertUniqueKeys<K>(keys: readonly K[]): void {
+  const seen = new Set<K>()
+  for (const key of keys) {
+    if (seen.has(key)) {
+      throw new Error(DEV ? `duplicate key in keyed list: ${String(key)}` : 'V804')
+    }
+    seen.add(key)
+  }
+}
+
+function normalizeRenderResult<T>(result: KeyedRenderResult<T>): KeyedItem<T> {
+  if (isNode(result)) return [normalizeNodes([result])]
+  if (isNodeArray(result)) return [normalizeNodes(result)]
+  return [normalizeNodes(result[0]), result[1], result[2]]
+}
+
+function normalizeNodes(nodes: readonly Node[]): readonly Node[] {
+  const normalized: Node[] = []
+  for (const node of nodes) {
+    if (node.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+      normalized.push(...node.childNodes)
+    } else {
+      normalized.push(node)
+    }
+  }
+  return normalized.length === 0 ? [document.createComment(DEV ? 'vidact:empty' : '')] : normalized
+}
+
+function isNode(value: unknown): value is Node {
+  return typeof value === 'object' && value !== null && 'nodeType' in value
+}
+
+function isNodeArray<T>(value: KeyedRenderResult<T>): value is readonly Node[] {
+  return Array.isArray(value) && (value.length === 0 || isNode(value[0]))
+}
+
+function removeNodes(parent: Node, nodes: readonly Node[]): void {
+  for (const node of nodes) {
+    if (node.parentNode === parent) parent.removeChild(node)
+  }
+}
+
+function disposeRecords<T, K>(
+  parent: Node,
+  records: Iterable<RecordState<T, K>>,
+): readonly [error: unknown, failed: boolean] {
+  let firstError: unknown
+  let failed = false
+  for (const record of records) {
+    removeNodes(parent, record[1])
+    try {
+      record[3]?.()
+    } catch (error) {
+      if (!failed) firstError = error
+      failed = true
+    }
+  }
+  return [firstError, failed]
+}
+import {
+  claimHydrationArrayRange,
+  finishHydrationArrayRange,
+  withHydrationInsertion,
+} from './hydration-bridge.ts'

package/src/metadata.ts

@@ -0,0 +1,212 @@
+import { registerCompiledCleanup } from './compiled/core.ts'
+import {
+  LINK_IDENTITY_PROPS,
+  META_IDENTITY_ATTRIBUTES,
+  META_IDENTITY_PROPS,
+} from './dom/attributes.ts'
+import { applyBaseDomProp, installDomPropHandler } from './dom/properties.ts'
+
+type MetadataEntry = {
+  readonly elements: Element[]
+  readonly baseline: number
+}
+
+type MetadataState = {
+  readonly entries: Map<string, MetadataEntry>
+  readonly stylePrecedence: string[]
+}
+
+type MetadataOwner = {
+  readonly element: Element
+  readonly state: MetadataState
+  entry: MetadataEntry
+  key: string
+}
+
+const metadataByDocument = new WeakMap<Document, MetadataState>()
+const metadataOwners = new WeakMap<Element, MetadataOwner>()
+let propRekeyingInstalled = false
+
+export function installFrameworkMetadataPropRekeying(): void {
+  if (propRekeyingInstalled) return
+  propRekeyingInstalled = true
+  installDomPropHandler((element, name, value) => {
+    const owner = metadataOwners.get(element)
+    if (owner === undefined || !isMetadataIdentityProp(element.localName, name)) return false
+    detachMetadataOwner(owner)
+    applyBaseDomProp(element, name, value)
+    if (name === 'precedence') {
+      element.setAttribute('data-precedence', String(value ?? 'default'))
+      element.removeAttribute('precedence')
+    }
+    attachMetadataOwner(owner)
+    return true
+  })
+}
+
+export function isFrameworkMetadataElement(
+  element: Element,
+  props: Readonly<Record<string, unknown>> | null = null,
+): boolean {
+  const name = element.localName
+  if (
+    (name === 'title' || name === 'meta' || name === 'link') &&
+    element.hasAttribute('itemprop')
+  ) {
+    return false
+  }
+  if (name === 'title' || name === 'meta') return true
+  if (name === 'link') {
+    if (
+      props !== null &&
+      ['onLoad', 'onError', 'disabled'].some((key) => Object.hasOwn(props, key))
+    ) {
+      return false
+    }
+    return element.getAttribute('rel') !== 'stylesheet' || element.hasAttribute('precedence')
+  }
+  if (name === 'style') return element.hasAttribute('href') && element.hasAttribute('precedence')
+  return name === 'script' && element.hasAttribute('async') && element.hasAttribute('src')
+}
+
+export function hoistFrameworkMetadata(element: Element): DocumentFragment {
+  const document = element.ownerDocument
+  const state = metadataState(document)
+  const key = metadataKey(element)
+  const owner: MetadataOwner = {
+    element,
+    state,
+    key,
+    entry: metadataEntry(document, state, key),
+  }
+  attachMetadataOwner(owner)
+  metadataOwners.set(element, owner)
+  element.removeAttribute('precedence')
+  registerCompiledCleanup(() => {
+    detachMetadataOwner(owner)
+    metadataOwners.delete(element)
+  })
+  return document.createDocumentFragment()
+}
+
+function metadataState(document: Document): MetadataState {
+  let state = metadataByDocument.get(document)
+  if (state !== undefined) return state
+  state = {
+    entries: new Map(),
+    stylePrecedence: [...document.head.children]
+      .filter((candidate) => metadataTier(candidate) === 2)
+      .map(stylePrecedence)
+      .filter((value, index, values) => values.indexOf(value) === index),
+  }
+  metadataByDocument.set(document, state)
+  return state
+}
+
+function metadataEntry(document: Document, state: MetadataState, key: string): MetadataEntry {
+  let entry = state.entries.get(key)
+  if (entry !== undefined) return entry
+  const existing = [...document.head.children].find(
+    (candidate) => isFrameworkMetadataElement(candidate) && metadataKey(candidate) === key,
+  )
+  entry = {
+    elements: existing === undefined ? [] : [existing],
+    baseline: existing === undefined ? 0 : 1,
+  }
+  state.entries.set(key, entry)
+  return entry
+}
+
+function attachMetadataOwner(owner: MetadataOwner): void {
+  const document = owner.element.ownerDocument
+  owner.key = metadataKey(owner.element)
+  owner.entry = metadataEntry(document, owner.state, owner.key)
+  owner.entry.elements.at(-1)?.remove()
+  owner.entry.elements.push(owner.element)
+  insertByPrecedence(document.head, owner.element, owner.state)
+}
+
+function detachMetadataOwner(owner: MetadataOwner): void {
+  const { element, entry, key, state } = owner
+  const index = entry.elements.indexOf(element)
+  if (index === -1) return
+  const visible = index === entry.elements.length - 1
+  entry.elements.splice(index, 1)
+  element.remove()
+  if (entry.elements.length === entry.baseline) {
+    if (visible && entry.elements.length !== 0) {
+      element.ownerDocument.head.append(entry.elements.at(-1)!)
+    }
+    if (state.entries.get(key) === entry) state.entries.delete(key)
+  } else if (visible) {
+    insertByPrecedence(element.ownerDocument.head, entry.elements.at(-1)!, state)
+  }
+}
+
+function isMetadataIdentityProp(elementName: string, propName: string): boolean {
+  if (propName === 'precedence') return elementName === 'link' || elementName === 'style'
+  if (elementName === 'meta') {
+    return (META_IDENTITY_PROPS as readonly string[]).includes(propName)
+  }
+  if (elementName === 'link') return (LINK_IDENTITY_PROPS as readonly string[]).includes(propName)
+  if (elementName === 'script') return propName === 'src'
+  return false
+}
+
+function metadataKey(element: Element): string {
+  const name = element.localName
+  if (name === 'title') return 'title'
+  if (name === 'meta') {
+    for (const attribute of META_IDENTITY_ATTRIBUTES) {
+      if (element.hasAttribute(attribute))
+        return `meta:${attribute}:${element.getAttribute(attribute)}`
+    }
+  }
+  if (name === 'link') {
+    return `link:${element.getAttribute('rel') ?? ''}:${element.getAttribute('href') ?? ''}:${element.getAttribute('as') ?? ''}`
+  }
+  if (name === 'style') return `style:${element.getAttribute('href') ?? ''}`
+  return `script:${element.getAttribute('src') ?? ''}`
+}
+
+function insertByPrecedence(head: HTMLHeadElement, element: Element, state: MetadataState): void {
+  const tier = metadataTier(element) ?? 1
+  const precedence = stylePrecedence(element)
+  if (tier === 2) {
+    if (!state.stylePrecedence.includes(precedence)) state.stylePrecedence.push(precedence)
+    element.setAttribute('data-precedence', precedence)
+  }
+  const before = [...head.children].find((candidate) => {
+    const candidateTier = metadataTier(candidate)
+    if (candidateTier === undefined) return false
+    if (candidateTier !== tier) return candidateTier > tier
+    return (
+      tier === 2 &&
+      state.stylePrecedence.indexOf(stylePrecedence(candidate)) >
+        state.stylePrecedence.indexOf(precedence)
+    )
+  })
+  head.insertBefore(element, before ?? null)
+}
+
+function metadataTier(element: Element): number | undefined {
+  const name = element.localName
+  if (name === 'style') return element.hasAttribute('data-precedence') ? 2 : undefined
+  if (name === 'script') return element.hasAttribute('src') ? 3 : undefined
+  if (name === 'link') {
+    const relation = element.getAttribute('rel')
+    if (relation === 'stylesheet') {
+      return element.hasAttribute('precedence') || element.hasAttribute('data-precedence')
+        ? 2
+        : undefined
+    }
+    if (['preconnect', 'dns-prefetch', 'preload', 'modulepreload'].includes(relation ?? ''))
+      return 0
+    return 1
+  }
+  return name === 'title' || name === 'meta' ? 1 : undefined
+}
+
+function stylePrecedence(element: Element): string {
+  return element.getAttribute('precedence') ?? element.getAttribute('data-precedence') ?? 'default'
+}

package/src/nested-prop.ts

@@ -0,0 +1,27 @@
+import { binding, isCompiledBinding } from './compiled/core.ts'
+
+const DEV = typeof __VIDACT_DEV__ === 'undefined' || __VIDACT_DEV__
+
+type ContainerFallback = (() => unknown) | null
+
+export function nestedProp(
+  input: unknown,
+  path: readonly string[],
+  containerFallbacks: readonly ContainerFallback[],
+): unknown {
+  const read = (): unknown => {
+    let value = isCompiledBinding(input) ? input[1]() : input
+    for (const [index, name] of path.entries()) {
+      if (value === undefined) value = containerFallbacks[index]?.()
+      if (value === null || value === undefined) {
+        throw new TypeError(
+          DEV ? `cannot destructure nested prop ${name} from a nullish value` : 'V015',
+        )
+      }
+      value = (value as Record<string, unknown>)[name]
+    }
+    return value
+  }
+
+  return isCompiledBinding(input) ? binding(input[2], input[3], read, input[4], input[5]) : read()
+}

package/src/profiling.ts

@@ -0,0 +1,43 @@
+import {
+  captureCompiledOwnerStack,
+  enableProfiling,
+  profiled,
+  recordCompiledDebugValue,
+} from './compiled/core.ts'
+import type {
+  CompiledBinding,
+  CompiledRenderValue,
+  ProfilerOnRender,
+  StructuralBinding,
+} from './compiled/types.ts'
+
+export interface ProfilerProps {
+  readonly children?: (() => CompiledRenderValue) | readonly [() => CompiledRenderValue]
+  readonly id: string | CompiledBinding<string>
+  readonly onRender: ProfilerOnRender | CompiledBinding<ProfilerOnRender>
+}
+
+export function Profiler(props: ProfilerProps): StructuralBinding {
+  const render = Array.isArray(props.children) ? props.children[0] : props.children
+  if (typeof render !== 'function') {
+    throw new TypeError('Profiler children must be a compiler-generated render function')
+  }
+  enableProfiling()
+  return profiled(props.id, props.onRender, render)
+}
+
+export function useDebugValue<Value>(
+  value: Value | CompiledBinding<Value>,
+  format?: (value: Value) => unknown,
+): void {
+  if (format !== undefined && typeof format !== 'function') {
+    throw new TypeError('useDebugValue formatter must be a function')
+  }
+  enableProfiling()
+  recordCompiledDebugValue(value, format)
+}
+
+export function captureOwnerStack(): string | null {
+  enableProfiling()
+  return captureCompiledOwnerStack()
+}

package/src/protocol.ts

@@ -0,0 +1,8 @@
+export const VIDACT_RUNTIME_PROTOCOL = 'vidact-runtime-v2'
+
+export function assertRuntimeProtocol(expected: string): void {
+  if (expected === VIDACT_RUNTIME_PROTOCOL) return
+  throw new Error(
+    `Vidact compiler/runtime protocol mismatch: compiled for ${expected}, runtime provides ${VIDACT_RUNTIME_PROTOCOL}`,
+  )
+}