@vidact/start 0.2.0-beta.0 → 0.2.0-beta.4

package/src/client.ts

@@ -0,0 +1,262 @@
+import {
+  cloneRenderable,
+  compiledRoot,
+  createCompiledScope,
+  type CompiledComponentResult,
+  type CompiledRoot,
+} from '@vidact/runtime'
+import { createElement, hydrateRoot } from '@vidact/runtime/hydrate'
+
+import {
+  composeRouteMatches,
+  loadRouteMatches,
+  matchRoutes,
+  type LoadedRouteMatch,
+  type RouteManifest,
+  type StartComponent,
+} from './router.ts'
+import {
+  decodeStartSnapshot,
+  VIDACT_START_NAVIGATION_HEADER,
+  VIDACT_START_SNAPSHOT_MEDIA_TYPE,
+} from './snapshot.ts'
+
+const DEFAULT_ROOT_ID = 'vidact-start-root'
+const DEFAULT_SNAPSHOT_ID = 'vidact-start-snapshot'
+
+export interface HydrateStartOptions {
+  readonly fetch?: typeof globalThis.fetch
+  readonly manifest: RouteManifest
+  readonly root?: ParentNode
+  readonly rootId?: string
+  readonly snapshot?: string
+  readonly snapshotId?: string
+}
+
+export interface StartNavigateOptions {
+  readonly replace?: boolean
+  readonly scroll?: boolean
+}
+
+export interface StartClient extends CompiledRoot {
+  readonly navigate: (to: string | URL, options?: StartNavigateOptions) => Promise<boolean>
+}
+
+type HistoryMode = 'none' | 'push' | 'replace'
+
+export async function hydrateStart(options: HydrateStartOptions): Promise<StartClient> {
+  const snapshot = decodeStartSnapshot(
+    options.snapshot ?? readSnapshot(options.snapshotId ?? DEFAULT_SNAPSHOT_ID),
+  )
+  const initialUrl = new URL(snapshot.pathname, window.location.href)
+  const matches = matchRoutes(options.manifest, initialUrl.pathname)
+  if (matches.length === 0) throw new Error(`cannot hydrate unmatched route ${snapshot.pathname}`)
+  const request = new Request(initialUrl)
+  const loaded = await loadRouteMatches(matches, request, snapshot.loaderData)
+  const host =
+    options.root ?? document.querySelector(`#${CSS.escape(options.rootId ?? DEFAULT_ROOT_ID)}`)
+  if (host === null) throw new Error('Vidact Start hydration root is missing')
+
+  const root = hydrateRoot(host, createClientApplication(loaded, request.url))
+  const fetchNavigation = options.fetch ?? window.fetch.bind(window)
+  let navigation = 0
+  let navigationController: AbortController | undefined
+  let disposed = false
+
+  async function navigate(
+    to: string | URL,
+    navigationOptions: StartNavigateOptions = {},
+  ): Promise<boolean> {
+    return performNavigation(
+      new URL(to, window.location.href),
+      navigationOptions.replace === true ? 'replace' : 'push',
+      navigationOptions.scroll !== false,
+    )
+  }
+
+  async function performNavigation(
+    target: URL,
+    historyMode: HistoryMode,
+    scroll: boolean,
+  ): Promise<boolean> {
+    if (disposed) throw new Error('cannot navigate an unmounted Vidact Start client')
+    if (!isClientNavigationUrl(target)) {
+      navigateDocument(target, historyMode === 'replace')
+      return false
+    }
+    const nextMatches = matchRoutes(options.manifest, target.pathname)
+    if (nextMatches.length === 0) {
+      navigateDocument(target, historyMode === 'replace')
+      return false
+    }
+
+    navigation += 1
+    const attempt = navigation
+    navigationController?.abort()
+    const controller = new AbortController()
+    navigationController = controller
+
+    try {
+      const response = await fetchNavigation(target, {
+        credentials: 'same-origin',
+        headers: { [VIDACT_START_NAVIGATION_HEADER]: '1' },
+        signal: controller.signal,
+      })
+      if (attempt !== navigation) return false
+      if (
+        !response.ok ||
+        response.headers.get('content-type')?.split(';', 1)[0] !== VIDACT_START_SNAPSHOT_MEDIA_TYPE
+      ) {
+        navigateDocument(target, historyMode === 'replace')
+        return false
+      }
+
+      const nextSnapshot = decodeStartSnapshot(await response.text())
+      const nextUrl = new URL(nextSnapshot.pathname, target.origin)
+      const snapshotMatches = matchRoutes(options.manifest, nextUrl.pathname)
+      if (snapshotMatches.length === 0) {
+        navigateDocument(target, historyMode === 'replace')
+        return false
+      }
+      const nextRequest = new Request(nextUrl)
+      const nextLoaded = await loadRouteMatches(
+        snapshotMatches,
+        nextRequest,
+        nextSnapshot.loaderData,
+      )
+      if (attempt !== navigation) return false
+
+      root.replace(createClientApplication(nextLoaded, nextRequest.url))
+      updateHistory(nextUrl, historyMode)
+      if (scroll) scrollToLocation(nextUrl)
+      return true
+    } catch {
+      if (controller.signal.aborted || attempt !== navigation) return false
+      navigateDocument(target, historyMode === 'replace')
+      return false
+    }
+  }
+
+  function handleClick(event: MouseEvent): void {
+    const anchor = linkForEvent(event)
+    if (anchor === undefined) return
+    const target = new URL(anchor.href, window.location.href)
+    if (
+      target.pathname === window.location.pathname &&
+      target.search === window.location.search &&
+      target.hash !== window.location.hash
+    ) {
+      return
+    }
+    event.preventDefault()
+    void performNavigation(
+      target,
+      anchor.hasAttribute('data-vidact-start-replace') ? 'replace' : 'push',
+      true,
+    )
+  }
+
+  function handlePopState(): void {
+    void performNavigation(new URL(window.location.href), 'none', false)
+  }
+
+  document.addEventListener('click', handleClick)
+  window.addEventListener('popstate', handlePopState)
+
+  return {
+    mount: root.mount,
+    replace: root.replace,
+    navigate,
+    unmount() {
+      if (disposed) return
+      disposed = true
+      navigation += 1
+      navigationController?.abort()
+      document.removeEventListener('click', handleClick)
+      window.removeEventListener('popstate', handlePopState)
+      root.unmount()
+    },
+  }
+}
+
+function createClientApplication(
+  matches: readonly LoadedRouteMatch[],
+  requestUrl: string,
+): () => CompiledComponentResult {
+  return () => {
+    const scope = createCompiledScope()
+    const application = composeRouteMatches(
+      matches,
+      (component, props) => createElement(component as never, props),
+      requestUrl,
+    )
+    return compiledRoot(scope, () => cloneRenderable(application))
+  }
+}
+
+function linkForEvent(event: MouseEvent): HTMLAnchorElement | undefined {
+  if (
+    event.defaultPrevented ||
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey
+  ) {
+    return undefined
+  }
+  const target = event.target
+  if (!(target instanceof Element)) return undefined
+  const anchor = target.closest<HTMLAnchorElement>('a[data-vidact-start-link]')
+  if (
+    anchor === null ||
+    anchor.hasAttribute('download') ||
+    (anchor.target !== '' && anchor.target !== '_self') ||
+    anchor.rel.split(/\s+/u).includes('external')
+  ) {
+    return undefined
+  }
+  const url = new URL(anchor.href, window.location.href)
+  return isClientNavigationUrl(url) ? anchor : undefined
+}
+
+function isClientNavigationUrl(url: URL): boolean {
+  return (
+    url.origin === window.location.origin && (url.protocol === 'http:' || url.protocol === 'https:')
+  )
+}
+
+function updateHistory(url: URL, mode: HistoryMode): void {
+  if (mode === 'push') window.history.pushState({}, '', url)
+  else if (mode === 'replace') window.history.replaceState(window.history.state, '', url)
+}
+
+function scrollToLocation(url: URL): void {
+  if (url.hash.length > 1) {
+    let id: string
+    try {
+      id = decodeURIComponent(url.hash.slice(1))
+    } catch {
+      id = url.hash.slice(1)
+    }
+    const target = document.getElementById(id)
+    if (target !== null) {
+      target.scrollIntoView()
+      return
+    }
+  }
+  window.scrollTo({ top: 0, left: 0, behavior: 'instant' })
+}
+
+function navigateDocument(url: URL, replace: boolean): void {
+  if (replace) window.location.replace(url)
+  else window.location.assign(url)
+}
+
+function readSnapshot(id: string): string {
+  const element = document.querySelector(`#${CSS.escape(id)}`)
+  if (element === null) throw new Error(`Vidact Start snapshot ${id} is missing`)
+  return element.textContent ?? ''
+}
+
+export type { StartComponent }

package/src/index-client.ts

@@ -0,0 +1,3 @@
+export * from './link-client.ts'
+export * from './router.ts'
+export * from './snapshot.ts'

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './link.ts'
+export * from './router.ts'
+export * from './snapshot.ts'

package/src/link-client.ts

@@ -0,0 +1,10 @@
+import type { CompiledRenderValue } from '@vidact/runtime'
+import { createElement } from '@vidact/runtime/hydrate'
+
+import { anchorProps, type LinkProps } from './link-contract.ts'
+
+export function Link(props: LinkProps): CompiledRenderValue {
+  return createElement('a', anchorProps(props)) as unknown as CompiledRenderValue
+}
+
+export type { LinkProps }

package/src/link-contract.ts

@@ -0,0 +1,17 @@
+import type { CompiledRenderValue } from '@vidact/runtime'
+
+export interface LinkProps extends Readonly<Record<string, unknown>> {
+  readonly children?: CompiledRenderValue
+  readonly href: string
+  readonly reloadDocument?: boolean
+  readonly replace?: boolean
+}
+
+export function anchorProps(props: LinkProps): Record<string, unknown> {
+  const { reloadDocument = false, replace = false, ...attributes } = props
+  return {
+    ...attributes,
+    ...(reloadDocument ? {} : { 'data-vidact-start-link': '' }),
+    ...(replace ? { 'data-vidact-start-replace': '' } : {}),
+  }
+}

package/src/link.ts

@@ -0,0 +1,10 @@
+import type { CompiledRenderValue } from '@vidact/runtime'
+import { createElement, type ServerChild } from '@vidact/runtime/server'
+
+import { anchorProps, type LinkProps } from './link-contract.ts'
+
+export function Link(props: LinkProps): CompiledRenderValue {
+  return createElement('a', anchorProps(props)) as ServerChild as unknown as CompiledRenderValue
+}
+
+export type { LinkProps }

package/src/router.ts

@@ -0,0 +1,282 @@
+import type { CompiledRenderValue } from '@vidact/runtime'
+import type { FrameworkValue } from '@vidact/runtime/framework/protocol'
+
+const FILE_ROUTE = Symbol('Vidact.Start.FileRoute')
+
+export type RouteParameters = Readonly<Record<string, string>>
+export type StartComponent<LoaderData extends FrameworkValue = FrameworkValue> = {
+  bivarianceHack(props: RouteComponentProps<LoaderData>): unknown
+}['bivarianceHack']
+
+export interface RouteComponentProps<
+  LoaderData extends FrameworkValue = FrameworkValue,
+> extends Readonly<Record<string, unknown>> {
+  readonly children?: CompiledRenderValue
+  readonly loaderData: LoaderData
+  readonly params: RouteParameters
+  readonly requestUrl: string
+}
+
+export interface RouteLoaderContext {
+  readonly parentData: Readonly<Record<string, FrameworkValue>>
+  readonly params: RouteParameters
+  readonly request: Request
+}
+
+export interface RouteServerContext {
+  readonly params: RouteParameters
+  readonly request: Request
+}
+
+export type RouteServerHandler = (context: RouteServerContext) => Response | Promise<Response>
+
+export interface FileRouteOptions<LoaderData extends FrameworkValue = FrameworkValue> {
+  readonly component?: StartComponent<LoaderData>
+  readonly loader?: (context: RouteLoaderContext) => LoaderData | Promise<LoaderData>
+  readonly server?: {
+    readonly handlers: Readonly<Partial<Record<string, RouteServerHandler>>>
+  }
+}
+
+export interface FileRouteDefinition<LoaderData extends FrameworkValue = FrameworkValue> {
+  readonly [FILE_ROUTE]: true
+  readonly options: FileRouteOptions<LoaderData>
+}
+
+export interface RouteModule {
+  readonly Route?: FileRouteDefinition
+  readonly default?: FileRouteDefinition
+}
+
+export interface RouteManifestEntry {
+  readonly id: string
+  readonly parentId: string | null
+  readonly path: string
+  readonly load: () => PromiseLike<RouteModule>
+}
+
+export interface RouteManifest {
+  readonly entries: readonly RouteManifestEntry[]
+  readonly byId: ReadonlyMap<string, RouteManifestEntry>
+}
+
+export interface RouteMatch {
+  readonly entry: RouteManifestEntry
+  readonly params: RouteParameters
+}
+
+export interface ResolvedRouteMatch extends RouteMatch {
+  readonly definition: FileRouteDefinition
+}
+
+export interface LoadedRouteMatch extends ResolvedRouteMatch {
+  readonly loaderData: FrameworkValue
+}
+
+export function defineFileRoute<const LoaderData extends FrameworkValue = undefined>(
+  options: FileRouteOptions<LoaderData>,
+): FileRouteDefinition<LoaderData> {
+  return Object.freeze({ [FILE_ROUTE]: true as const, options: Object.freeze({ ...options }) })
+}
+
+export function isFileRouteDefinition(value: unknown): value is FileRouteDefinition {
+  return typeof value === 'object' && value !== null && FILE_ROUTE in value
+}
+
+export function createRouteManifest(entries: readonly RouteManifestEntry[]): RouteManifest {
+  const byId = new Map<string, RouteManifestEntry>()
+  for (const entry of entries) {
+    if (entry.id.length === 0) throw new TypeError('route id must be non-empty')
+    if (!entry.path.startsWith('/')) throw new TypeError(`route ${entry.id} path must start with /`)
+    if (byId.has(entry.id)) throw new TypeError(`duplicate route id ${entry.id}`)
+    byId.set(entry.id, Object.freeze({ ...entry }))
+  }
+  for (const entry of byId.values()) {
+    if (entry.parentId !== null && !byId.has(entry.parentId)) {
+      throw new TypeError(`route ${entry.id} has unknown parent ${entry.parentId}`)
+    }
+    assertAcyclicParentChain(entry, byId)
+  }
+  const frozenEntries = Object.freeze([...byId.values()])
+  return Object.freeze({ entries: frozenEntries, byId })
+}
+
+export function matchRoutes(manifest: RouteManifest, pathname: string): readonly RouteMatch[] {
+  const normalized = normalizePathname(pathname)
+  let selected: { entry: RouteManifestEntry; params: RouteParameters; score: number } | undefined
+  for (const entry of manifest.entries) {
+    const match = matchPath(entry.path, normalized)
+    if (match === undefined) continue
+    const score = routeScore(entry, manifest)
+    if (selected === undefined || score > selected.score) selected = { entry, params: match, score }
+  }
+  if (selected === undefined) return []
+  const chain: RouteManifestEntry[] = []
+  let entry: RouteManifestEntry | undefined = selected.entry
+  while (entry !== undefined) {
+    chain.push(entry)
+    entry = entry.parentId === null ? undefined : manifest.byId.get(entry.parentId)
+  }
+  return Object.freeze(
+    chain.toReversed().map((matchedEntry) =>
+      Object.freeze({
+        entry: matchedEntry,
+        params: Object.freeze({ ...selected.params }),
+      }),
+    ),
+  )
+}
+
+export async function loadRouteMatches(
+  matches: readonly RouteMatch[],
+  request: Request,
+  suppliedData: Readonly<Record<string, FrameworkValue>> = {},
+): Promise<readonly LoadedRouteMatch[]> {
+  return runRouteLoaders(await resolveRouteMatches(matches), request, suppliedData)
+}
+
+export async function resolveRouteMatches(
+  matches: readonly RouteMatch[],
+): Promise<readonly ResolvedRouteMatch[]> {
+  return Object.freeze(
+    await Promise.all(
+      matches.map(async (match) => {
+        const module = await match.entry.load()
+        return Object.freeze({
+          ...match,
+          definition: readRouteDefinition(match.entry.id, module),
+        })
+      }),
+    ),
+  )
+}
+
+export async function runRouteLoaders(
+  matches: readonly ResolvedRouteMatch[],
+  request: Request,
+  suppliedData: Readonly<Record<string, FrameworkValue>> = {},
+): Promise<readonly LoadedRouteMatch[]> {
+  const loaded: LoadedRouteMatch[] = []
+  const parentData: Record<string, FrameworkValue> = { ...suppliedData }
+  for (const match of matches) {
+    const loaderData = Object.hasOwn(suppliedData, match.entry.id)
+      ? suppliedData[match.entry.id]
+      : match.definition.options.loader === undefined
+        ? undefined
+        : // oxlint-disable-next-line no-await-in-loop -- Descendants receive settled parent data.
+          await match.definition.options.loader({
+            parentData: Object.freeze({ ...parentData }),
+            params: match.params,
+            request,
+          })
+    parentData[match.entry.id] = loaderData
+    loaded.push(Object.freeze({ ...match, loaderData }))
+  }
+  return Object.freeze(loaded)
+}
+
+export function composeRouteMatches(
+  matches: readonly LoadedRouteMatch[],
+  createElement: (component: StartComponent, props: RouteComponentProps) => unknown,
+  requestUrl: string,
+): unknown {
+  let children: CompiledRenderValue | undefined
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    const match = matches[index]!
+    const component = match.definition.options.component
+    if (component === undefined) continue
+    children = createElement(component, {
+      children,
+      loaderData: match.loaderData,
+      params: match.params,
+      requestUrl,
+    }) as CompiledRenderValue
+  }
+  return children
+}
+
+export function routeLoaderData(
+  matches: readonly LoadedRouteMatch[],
+): Readonly<Record<string, FrameworkValue>> {
+  return Object.freeze(
+    Object.fromEntries(matches.map((match) => [match.entry.id, match.loaderData])) as Record<
+      string,
+      FrameworkValue
+    >,
+  )
+}
+
+function readRouteDefinition(id: string, module: RouteModule): FileRouteDefinition {
+  const definition = module.Route ?? module.default
+  if (!isFileRouteDefinition(definition)) {
+    throw new TypeError(`route module ${id} must export a Route created by defineFileRoute`)
+  }
+  return definition
+}
+
+function matchPath(pattern: string, pathname: string): RouteParameters | undefined {
+  if (pattern === '/') return pathname === '/' ? Object.freeze({}) : undefined
+  const patternSegments = segments(pattern)
+  const pathSegments = segments(pathname)
+  const parameters: Record<string, string> = {}
+  let pathIndex = 0
+  for (const segment of patternSegments) {
+    if (segment === '*') {
+      if (pathIndex >= pathSegments.length) return undefined
+      parameters['*'] = decodeSegment(pathSegments.slice(pathIndex).join('/'))
+      pathIndex = pathSegments.length
+      break
+    }
+    const value = pathSegments[pathIndex]
+    if (value === undefined) return undefined
+    if (segment.startsWith(':')) parameters[segment.slice(1)] = decodeSegment(value)
+    else if (segment !== value) return undefined
+    pathIndex += 1
+  }
+  return pathIndex === pathSegments.length ? Object.freeze(parameters) : undefined
+}
+
+function normalizePathname(pathname: string): string {
+  const path = pathname.split(/[?#]/u, 1)[0] ?? '/'
+  if (!path.startsWith('/')) throw new TypeError('route pathname must start with /')
+  return path.length > 1 ? path.replace(/\/+$/u, '') : '/'
+}
+
+function segments(pathname: string): string[] {
+  return pathname.split('/').filter(Boolean)
+}
+
+function decodeSegment(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    throw new TypeError(`invalid encoded route segment ${value}`)
+  }
+}
+
+function routeScore(entry: RouteManifestEntry, manifest: RouteManifest): number {
+  const specificity = segments(entry.path).reduce(
+    (score, segment) => score + (segment === '*' ? 1 : segment.startsWith(':') ? 10 : 100),
+    0,
+  )
+  let depth = 0
+  let current: RouteManifestEntry | undefined = entry
+  while (current !== undefined) {
+    depth += 1
+    current = current.parentId === null ? undefined : manifest.byId.get(current.parentId)
+  }
+  return specificity * 1_000 + depth
+}
+
+function assertAcyclicParentChain(
+  entry: RouteManifestEntry,
+  byId: ReadonlyMap<string, RouteManifestEntry>,
+): void {
+  const visited = new Set<string>([entry.id])
+  let parentId = entry.parentId
+  while (parentId !== null) {
+    if (visited.has(parentId)) throw new TypeError(`route ${entry.id} has a cyclic parent chain`)
+    visited.add(parentId)
+    parentId = byId.get(parentId)?.parentId ?? null
+  }
+}