@weft-js/start 0.1.0 → 0.1.2

package/src/run/retain-view.ts

@@ -0,0 +1,18 @@
+import { createRoot, getOwner, onCleanup, state } from '@weft-js/core'
+import { hole, rt } from '@weft-js/core/internal'
+
+/** Keep one route view alive while its pending shape occupies the same outlet. */
+export function retainRouteView(view: () => unknown, pending: () => unknown) {
+  if (rt.server) return () => pending() ?? view()
+  const parent = getOwner()
+  const content = state<unknown>(undefined)
+  let dispose = () => {}
+  createRoot((end) => {
+    dispose = end
+    hole(view, (value) => {
+      content.value = value
+    })
+  }, parent)
+  onCleanup(() => dispose())
+  return () => pending() ?? content.value
+}

package/src/run/shape-preparation.ts

@@ -0,0 +1,97 @@
+import { flush } from '@weft-js/core'
+import { level, type Component } from '../router'
+import type { ClientRoutes, RouteShape } from '../run'
+import { acquireShapeStyles } from './shape-styles'
+import { PageSkeleton, PassThroughSkeleton } from './page-skeleton'
+import type { Navigation } from './navigation'
+
+export interface PreparedRouteShape {
+  kind: 'generated' | 'override'
+  component: Component
+  /** Provided CSS is installed; its dependency closure remains unproven. */
+  ready: true
+  completeness: 'partial'
+  release(): void
+}
+
+type Renderable = Extract<RouteShape, { kind: 'generated' | 'override' }>
+
+/** Prepare the selected generated or custom shape without rendering it. */
+export function prepareRouteShape(
+  routes: ClientRoutes,
+  id: string,
+  doc: Document,
+): PreparedRouteShape | null {
+  const shape = routes.shapes?.[id]
+  if (!shape || (shape.kind !== 'generated' && shape.kind !== 'override')) return null
+  // A shape with no structure of its own would leave the outlet blank: a page's outline stands in, and a layout's
+  // place goes to its page's.
+  if (shape.thin)
+    return prepare(
+      {
+        ...shape,
+        component: id.startsWith('layout:') ? PassThroughSkeleton : PageSkeleton,
+      },
+      routes.build,
+      doc,
+    )
+  return prepare(shape, routes.build, doc)
+}
+
+function prepare(
+  shape: Renderable,
+  build: string | null | undefined,
+  doc: Document,
+): PreparedRouteShape | null {
+  const lease = acquireShapeStyles(doc, build, shape.cssText)
+  if (!lease) return null
+  return {
+    kind: shape.kind,
+    component: shape.component,
+    ready: true,
+    completeness: shape.cssStatus,
+    // oxlint-disable-next-line typescript/unbound-method -- the native method is kept to be called with .call()
+    release: lease.release,
+  }
+}
+
+/** Prepare all changed levels before replacing the current outlet. */
+export function presentShape(nav: Navigation, ids: string[], url: URL, force: boolean) {
+  let first = ids.findIndex((id, depth) => nav.route.levels[depth]?.id.value !== id)
+  if (first < 0) first = force ? ids.length - 1 : nav.changedParams(ids, url)
+  if (first < 0) {
+    const committed = new URL(nav.committedURL)
+    if (url.pathname === committed.pathname && url.search === committed.search) nav.clearShape()
+    return false
+  }
+  if (!nav.route.prepareShape) return false
+  const leases: PreparedRouteShape[] = []
+  try {
+    for (const id of ids.slice(first)) {
+      const lease = nav.route.prepareShape(id)
+      if (!lease) {
+        leases.forEach((item) => item.release())
+        return false
+      }
+      leases.push(lease)
+    }
+  } catch {
+    leases.forEach((item) => item.release())
+    return false
+  }
+  // A same-id layout stays mounted; its existing child outlet owns the presentation.
+  let depth = first
+  while (depth < ids.length - 1 && nav.route.levels[depth]?.id.value === ids[depth]) depth++
+  const retained = leases.splice(0, depth - first)
+  retained.forEach((lease) => lease.release())
+  const outlet = level(nav.route, depth)
+  const old = nav.detachShape()
+  outlet.shape.value = leases
+  nav.shape = { outlet, leases }
+  try {
+    flush()
+  } finally {
+    old?.forEach((lease) => lease.release())
+  }
+  return true
+}

package/src/run/shape-styles.ts

@@ -0,0 +1,72 @@
+interface SheetLease {
+  release(): void
+}
+
+interface SheetEntry {
+  element: HTMLStyleElement
+  count: number
+}
+
+const sheets = new WeakMap<Document, Map<string, SheetEntry>>()
+
+function hasImports(rules: CSSRuleList): boolean {
+  for (const rule of Array.from(rules)) {
+    if (rule.type === 3) return true
+    if ('cssRules' in rule && hasImports((rule as CSSGroupingRule).cssRules)) return true
+  }
+  return false
+}
+
+/** Apply provided shape CSS before app styles. A lease owns only the styles it creates. */
+export function acquireShapeStyles(
+  doc: Document,
+  build: string | null | undefined,
+  text: string[],
+): SheetLease | null {
+  if (!doc.head || text.some((css) => /@import\b/i.test(css))) return null
+  const key = JSON.stringify([build ?? null, text])
+  const entries = sheets.get(doc) ?? new Map<string, SheetEntry>()
+  if (!sheets.has(doc)) sheets.set(doc, entries)
+  let entry = entries.get(key)
+  if (entry && entry.element.parentNode !== doc.head) {
+    entries.delete(key)
+    entry = undefined
+  }
+  if (!entry) {
+    const element = doc.createElement('style')
+    element.setAttribute('data-weft-shape-style', '')
+    const nonce = doc.querySelector<HTMLMetaElement>('meta[property="csp-nonce"]')?.nonce
+    if (nonce) element.nonce = nonce
+    element.textContent = text.join('\n')
+    const owned = new Set<Element>([...entries.values()].map((item) => item.element))
+    const appStyle =
+      [...doc.head.querySelectorAll('style,link[rel~="stylesheet"]')].find(
+        (item) => !owned.has(item),
+      ) ?? null
+    try {
+      doc.head.insertBefore(element, appStyle)
+      if (!element.sheet || hasImports(element.sheet.cssRules)) {
+        element.remove()
+        return null
+      }
+    } catch {
+      element.remove()
+      return null
+    }
+    entry = { element, count: 0 }
+    entries.set(key, entry)
+  }
+  entry.count++
+  const owned = entry
+  let released = false
+  return {
+    release() {
+      if (released) return
+      released = true
+      if (--owned.count === 0) {
+        owned.element.remove()
+        if (entries.get(key) === owned) entries.delete(key)
+      }
+    },
+  }
+}

package/src/run/source-context/pin.ts

@@ -0,0 +1,124 @@
+export type Name = 'href' | 'action' | 'formaction'
+export interface Saved {
+  original: string | null
+  installed: string
+}
+
+export interface Wrapper {
+  target: object
+  name: string
+  descriptor: PropertyDescriptor
+  replacement: PropertyDescriptor
+}
+
+export interface Retained {
+  root: HTMLElement
+  win: Window & typeof globalThis
+  source: string
+  base: string
+  saved: Map<Element, Map<Name, Saved>>
+  owners: WeakMap<NamedNodeMap, Element>
+  nativeSet: Element['setAttribute']
+  nativeRemove: Element['removeAttribute']
+  attrValue: PropertyDescriptor['set']
+  stopped: boolean
+  wrappers: Wrapper[]
+}
+
+export const SELECTOR = 'a[href],form,button[formaction],input[formaction]'
+
+export const relevant = (item: Element, name: string): name is Name =>
+  (item.localName === 'a' && name === 'href') ||
+  (item.localName === 'form' && name === 'action') ||
+  ((item.localName === 'button' || item.localName === 'input') && name === 'formaction')
+
+export function pin(
+  c: Retained,
+  item: Element,
+  name: Name,
+  raw: string | null,
+  force = false,
+): string | null {
+  const records = c.saved.get(item)
+  if (!force && records?.get(name)?.installed === raw) return raw
+  if (raw === null && name !== 'action') {
+    records?.delete(name)
+    return null
+  }
+  // Absolute and root-relative URLs resolve the same from any path: leave them alone.
+  if (raw && raw !== records?.get(name)?.installed && /^(?:[a-z][a-z\d+.-]*:|\/)/i.test(raw)) {
+    records?.delete(name)
+    return raw
+  }
+  let resolved: string
+  try {
+    resolved = name !== 'href' && !raw ? c.source : new URL(raw ?? '', c.base).href
+  } catch {
+    records?.delete(name)
+    return raw
+  }
+  if (raw === resolved) {
+    records?.delete(name)
+    return raw
+  }
+  const own = records ?? new Map<Name, Saved>()
+  c.saved.set(item, own)
+  own.set(name, { original: raw, installed: resolved })
+  return resolved
+}
+
+export function patch(c: Retained, item: Element, name: Name) {
+  const raw = item.getAttribute(name)
+  const resolved = pin(c, item, name, raw)
+  if (resolved !== raw) {
+    if (resolved === null) Reflect.apply(c.nativeRemove, item, [name])
+    else Reflect.apply(c.nativeSet, item, [name, resolved])
+  }
+}
+
+export function patchItem(c: Retained, item: Element) {
+  void item.attributes // Register maps captured before this context began.
+  if (item.localName === 'a') patch(c, item, 'href')
+  if (item.localName === 'form') patch(c, item, 'action')
+  if (item.localName === 'button' || item.localName === 'input') patch(c, item, 'formaction')
+}
+
+export function scan(c: Retained, parent: ParentNode) {
+  for (const item of parent.querySelectorAll(SELECTOR)) patchItem(c, item)
+}
+
+export function ownerOf(c: Retained, map: NamedNodeMap) {
+  const known = c.owners.get(map)
+  if (known) return known
+  if (c.root.matches('a,form,button,input') && c.root.attributes === map) return c.root
+  for (const item of c.root.querySelectorAll('a,form,button,input'))
+    if (item.attributes === map) return item
+  return undefined
+}
+
+export function changedNode(
+  c: Retained,
+  item: Element | null | undefined,
+  attr: unknown,
+  added: boolean,
+  previous: Attr | null,
+) {
+  if (
+    c.stopped ||
+    !item ||
+    !c.root.contains(item) ||
+    !(attr instanceof c.win.Attr) ||
+    attr.namespaceURI !== null ||
+    !relevant(item, attr.localName.toLowerCase())
+  )
+    return
+  const name = attr.localName.toLowerCase() as Name
+  if (added) {
+    const raw = attr.value,
+      value = pin(c, item, name, raw, previous !== attr)
+    if (value !== raw) Reflect.apply(c.attrValue!, attr, [value])
+  } else {
+    const value = pin(c, item, name, null, true)
+    if (value !== null) Reflect.apply(c.nativeSet, item, [name, value])
+  }
+}

package/src/run/source-context.ts

@@ -0,0 +1,311 @@
+import {
+  changedNode,
+  ownerOf,
+  patchItem,
+  pin,
+  relevant,
+  scan,
+  SELECTOR,
+  type Retained,
+} from './source-context/pin'
+
+export interface SourceContext {
+  /** Stop observing before incoming setup; keep controls pinned until the swap. */
+  stop(): void
+  release(): void
+}
+
+type Original = (...args: unknown[]) => unknown
+
+const active = new WeakSet<Document>()
+const EVENTS = ['pointerdown', 'click', 'auxclick', 'submit']
+const AFTER = ['click', 'auxclick', 'submit']
+
+function install(
+  c: Retained,
+  target: object,
+  name: string,
+  make: (d: PropertyDescriptor) => PropertyDescriptor,
+  required = true,
+) {
+  const descriptor = Object.getOwnPropertyDescriptor(target, name)
+  if (!descriptor) {
+    if (required) throw new Error('Missing control hook')
+    return
+  }
+  if (!descriptor.configurable) throw new Error('Locked control hook')
+  const replacement = make(descriptor)
+  Object.defineProperty(target, name, replacement)
+  c.wrappers.push({ target, name, descriptor, replacement })
+}
+
+function restore(c: Retained) {
+  for (const { target, name, descriptor, replacement } of c.wrappers.reverse()) {
+    const now = Object.getOwnPropertyDescriptor(target, name)
+    if (
+      now &&
+      now.get === replacement.get &&
+      now.set === replacement.set &&
+      now.value === replacement.value &&
+      now.writable === replacement.writable &&
+      now.enumerable === replacement.enumerable &&
+      now.configurable === replacement.configurable
+    )
+      Object.defineProperty(target, name, descriptor)
+  }
+}
+
+function wrapMethods(
+  c: Retained,
+  target: object,
+  names: string[],
+  make: (name: string, original: Original) => Original,
+) {
+  for (const name of names)
+    install(c, target, name, (descriptor) => ({
+      ...descriptor,
+      value: make(name, descriptor.value as Original),
+    }))
+}
+
+function hookAttributes(c: Retained) {
+  install(c, c.win.Element.prototype, 'attributes', (descriptor) => ({
+    ...descriptor,
+    get(this: Element) {
+      // oxlint-disable-next-line typescript/unbound-method -- the native method is kept to be called with .call()
+      const map = Reflect.apply(descriptor.get!, this, []) as NamedNodeMap
+      if (!c.stopped) c.owners.set(map, this)
+      return map
+    },
+  }))
+}
+
+function hookValues(c: Retained) {
+  const { win, root } = c
+  for (const [prototype, property] of [
+    [win.Attr.prototype, 'value'],
+    [win.Node.prototype, 'nodeValue'],
+    [win.Node.prototype, 'textContent'],
+  ] as const) {
+    install(c, prototype, property, (descriptor) => ({
+      ...descriptor,
+      set(this: Node, value: string | null) {
+        if (!c.stopped && this instanceof win.Attr && this.namespaceURI === null) {
+          const item = this.ownerElement,
+            name = this.localName.toLowerCase()
+          if (item && root.contains(item) && relevant(item, name)) {
+            // oxlint-disable-next-line typescript/no-unnecessary-type-conversion -- a DOM setter can receive null at runtime
+            const raw = property === 'value' ? value : String(value ?? '')
+            value = pin(c, item, name, raw, true)
+          }
+        }
+        // oxlint-disable-next-line typescript/unbound-method -- the native method is kept to be called with .call()
+        Reflect.apply(descriptor.set!, this, [value])
+      },
+    }))
+  }
+}
+
+function hookNamedNodeMap(c: Retained) {
+  const { win } = c
+  const names = ['setNamedItem', 'setNamedItemNS', 'removeNamedItem', 'removeNamedItemNS']
+  wrapMethods(
+    c,
+    win.NamedNodeMap.prototype,
+    names,
+    (method, original) =>
+      function (this: NamedNodeMap, ...args: unknown[]) {
+        const added = method.startsWith('set')
+        const owner = !c.stopped && !added ? ownerOf(c, this) : c.owners.get(this)
+        const result = Reflect.apply(original, this, args) as Attr | null
+        const attr = added ? args[0] : result
+        const item = owner ?? (attr instanceof win.Attr ? attr.ownerElement : null)
+        changedNode(c, item, attr, added, result)
+        return result
+      },
+  )
+}
+
+function hookAttributeNodes(c: Retained) {
+  const names = ['setAttributeNode', 'setAttributeNodeNS', 'removeAttributeNode']
+  wrapMethods(
+    c,
+    c.win.Element.prototype,
+    names,
+    (method, original) =>
+      function (this: Element, ...args: unknown[]) {
+        const result = Reflect.apply(original, this, args) as Attr | null
+        const added = method !== 'removeAttributeNode'
+        changedNode(c, this, added ? args[0] : result, added, result)
+        return result
+      },
+  )
+}
+
+function hookAttributeMethods(c: Retained) {
+  const names = ['setAttribute', 'removeAttribute', 'setAttributeNS', 'removeAttributeNS']
+  wrapMethods(
+    c,
+    c.win.Element.prototype,
+    names,
+    (name, original) =>
+      function (this: Element, ...args: unknown[]) {
+        const namespaced = name.endsWith('NS')
+        const key = String(args[namespaced ? 1 : 0])
+        const attr = key.toLowerCase()
+        const local = !namespaced || args[0] === null || args[0] === ''
+        if (!c.stopped && local && c.root.contains(this) && relevant(this, attr)) {
+          const raw = name.startsWith('remove') ? null : String(args[namespaced ? 2 : 1])
+          const value = pin(c, this, attr, raw, true)
+          if (value === null) return Reflect.apply(c.nativeRemove, this, [key])
+          return Reflect.apply(c.nativeSet, this, [key, value])
+        }
+        return Reflect.apply(original, this, args)
+      },
+  )
+}
+
+function hookReflected(c: Retained) {
+  const { win } = c
+  for (const [prototype, property, attr] of [
+    [win.HTMLAnchorElement.prototype, 'href', 'href'],
+    [win.HTMLFormElement.prototype, 'action', 'action'],
+    [win.HTMLButtonElement.prototype, 'formAction', 'formaction'],
+    [win.HTMLInputElement.prototype, 'formAction', 'formaction'],
+  ] as const) {
+    install(
+      c,
+      prototype,
+      property,
+      (descriptor) => ({
+        ...descriptor,
+        set(this: Element, value: string) {
+          const next = !c.stopped && c.root.contains(this) ? pin(c, this, attr, value, true) : value
+          // oxlint-disable-next-line typescript/unbound-method -- the native method is kept to be called with .call()
+          Reflect.apply(descriptor.set!, this, [next])
+        },
+      }),
+      false,
+    )
+  }
+}
+
+function hookSubmit(c: Retained) {
+  wrapMethods(
+    c,
+    c.win.HTMLFormElement.prototype,
+    ['submit', 'requestSubmit'],
+    (_, original) =>
+      function (this: HTMLFormElement, ...args: unknown[]) {
+        if (!c.stopped && c.root.contains(this)) {
+          patchItem(c, this)
+          if (args[0] instanceof Element && c.root.contains(args[0])) patchItem(c, args[0])
+        }
+        return Reflect.apply(original, this, args)
+      },
+  )
+}
+
+function observe(c: Retained, doc: Document) {
+  const { root } = c
+  const activate = (event: Event) => {
+    for (const item of event.composedPath())
+      if (item instanceof Element && root.contains(item)) patchItem(c, item)
+    if ('submitter' in event) {
+      const submitter = (event as SubmitEvent).submitter
+      if (submitter && root.contains(submitter)) patchItem(c, submitter)
+    }
+  }
+  for (const type of EVENTS) doc.addEventListener(type, activate, true)
+  for (const type of AFTER) doc.addEventListener(type, activate)
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      if (
+        record.type === 'attributes' &&
+        record.target instanceof Element &&
+        root.contains(record.target)
+      )
+        patchItem(c, record.target)
+      for (const node of record.addedNodes) {
+        if (!(node instanceof Element) || !root.contains(node)) continue
+        if (node.matches(SELECTOR)) patchItem(c, node)
+        scan(c, node)
+      }
+    }
+  })
+  observer.observe(root, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ['href', 'action', 'formaction'],
+  })
+  return () => {
+    observer.disconnect()
+    for (const type of EVENTS) doc.removeEventListener(type, activate, true)
+    for (const type of AFTER) doc.removeEventListener(type, activate)
+  }
+}
+
+/** Keep retained controls on their committed URL without changing the document base. */
+export function retainSourceContext(
+  doc: Document,
+  source: string,
+  base: string,
+): SourceContext | null {
+  const root = doc.getElementById('app') ?? doc.body
+  const win = doc.defaultView
+  if (!root || !win || active.has(doc)) return null
+  const c: Retained = {
+    root,
+    win,
+    source,
+    base,
+    saved: new Map(),
+    owners: new WeakMap(),
+    // oxlint-disable-next-line typescript/unbound-method -- the native method is kept to be called with .call()
+    nativeSet: win.Element.prototype.setAttribute,
+    // oxlint-disable-next-line typescript/unbound-method -- the native method is kept to be called with .call()
+    nativeRemove: win.Element.prototype.removeAttribute,
+    // oxlint-disable-next-line typescript/unbound-method -- the native setter is kept to be called with .call()
+    attrValue: Object.getOwnPropertyDescriptor(win.Attr.prototype, 'value')?.set,
+    stopped: false,
+    wrappers: [],
+  }
+  try {
+    hookAttributes(c)
+    hookValues(c)
+    hookNamedNodeMap(c)
+    hookAttributeNodes(c)
+    hookAttributeMethods(c)
+    hookReflected(c)
+    hookSubmit(c)
+  } catch {
+    restore(c)
+    return null
+  }
+  active.add(doc)
+  scan(c, root)
+  const unobserve = observe(c, doc)
+  const stop = () => {
+    if (c.stopped) return
+    c.stopped = true
+    active.delete(doc)
+    unobserve()
+    restore(c)
+  }
+  let released = false
+  return {
+    stop,
+    release() {
+      if (released) return
+      released = true
+      stop()
+      for (const [item, records] of c.saved)
+        for (const [name, action] of records) {
+          if (item.getAttribute(name) !== action.installed) continue
+          if (action.original === null) item.removeAttribute(name)
+          else item.setAttribute(name, action.original)
+        }
+    },
+  }
+}