@weft-js/start 0.0.0-stage → 0.1.0

package/src/routes.mjs

@@ -0,0 +1,142 @@
+// File routes (research 25 §2): `src/routes` → a route manifest, plain data that the server, the client table, the
+// Vite plugin and `weft routes` all read. Conventions:
+//
+//   index.tsx              /
+//   about.tsx              /about
+//   users/[id].tsx         /users/:id        (router-core path `/users/$id`)
+//   docs/[...rest].tsx     /docs/*           (router-core splat `$`, the param is `rest`)
+//   _layout.tsx            wraps every route in its directory and below (the root one wraps the whole app)
+//   404.tsx                the not-found page (root only), rendered inside the root layout with status 404
+//   _error.tsx             the error page (root only), rendered inside the root layout with status 500
+//   users/[id].og.tsx      the share card of `users/[id]` (research 20 §4); `_default.og.tsx` replaces the built-in card
+//
+// Any other file or directory starting with `_` is ignored, and so are tests. A route module may export `default`
+// (the component), `load`, `meta` and `prerender` (research 20 §3, §4.3).
+
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const EXT = /\.(tsx|jsx|ts|js)$/
+const posix = p => p.split('\\').join('/')
+
+/**
+ * @typedef {{ id: string, file: string, layouts: string[], path: string, pattern: string, params: string[], splat?: string, rank: number[], card?: string, kind: 'page' | '404' | 'error' }} RouteEntry
+ * @typedef {{ id: string, file: string, dir: string, parent?: string }} LayoutEntry
+ * @typedef {{ root: string, dir: string, routes: RouteEntry[], layouts: LayoutEntry[], defaultCard?: string, problems: { file: string, message: string }[] }} Manifest
+ */
+
+/** Scan `<root>/src/routes` (or `dir`). Paths in the manifest are relative to `root`, POSIX-style. */
+export function scanRoutes(root, dir = join(root, 'src', 'routes')) {
+  /** @type {Manifest} */
+  const out = { root, dir: posix(relative(root, dir)), routes: [], layouts: [], problems: [] }
+  if (!existsSync(dir)) return out
+  const files = []
+  const walk = d => {
+    for (const name of readdirSync(d).sort()) {
+      const abs = join(d, name)
+      if (statSync(abs).isDirectory()) {
+        if (!name.startsWith('_') && !name.startsWith('.')) walk(abs)
+      } else if (EXT.test(name) && !/\.(test|spec)\.|\.d\.ts$/.test(name)) files.push(posix(relative(dir, abs)))
+    }
+  }
+  walk(dir)
+
+  const rel = f => posix(relative(root, join(dir, f)))
+  const layoutFile = new Map() // route dir ('' = root) → its _layout file
+  for (const f of files) {
+    const m = /^(?:(.*)\/)?_layout\.[jt]sx?$/.exec(f)
+    if (m) layoutFile.set(m[1] ?? '', f)
+  }
+  const layoutOf = new Map([...layoutFile.keys()].map(d => [d, `layout:${d}`]))
+  for (const [d, f] of [...layoutFile].sort((a, b) => a[0].length - b[0].length)) {
+    out.layouts.push({ id: layoutOf.get(d), file: rel(f), dir: d, parent: chain(d, layoutOf).at(-2) })
+  }
+
+  const cards = new Map()
+  for (const f of files) {
+    const m = /^(.*)\.og\.[jt]sx?$/.exec(f)
+    if (!m) continue
+    if (m[1] === '_default') out.defaultCard = rel(f)
+    else cards.set(m[1], rel(f))
+  }
+
+  for (const f of files) {
+    const base = f.replace(EXT, '')
+    const name = base.split('/').pop()
+    if (base.endsWith('.og') || name === '_layout' || name === '_default') continue
+    const d = base.includes('/') ? base.slice(0, base.lastIndexOf('/')) : ''
+    if (name === '404' || name === '_error') {
+      if (d) { out.problems.push({ file: rel(f), message: `\`${name}\` is only read at the routes root for now; this one is ignored` }); continue }
+      out.routes.push({ id: name === '404' ? '404' : 'error', file: rel(f), layouts: chain('', layoutOf), path: '', pattern: '', params: [], rank: [], kind: name === '404' ? '404' : 'error' })
+      continue
+    }
+    if (name.startsWith('_') || d.split('/').some(s => s.startsWith('_'))) continue
+    const segs = base === 'index' ? [] : base.split('/')
+    if (segs.at(-1) === 'index') segs.pop()
+    const params = []
+    let splat
+    const parts = []
+    let bad = false
+    for (const s of segs) {
+      const p = /^\[(\.\.\.)?([A-Za-z_$][\w$]*)\]$/.exec(s)
+      if (p) {
+        if (p[1]) splat = p[2]
+        params.push(p[2])
+        parts.push(p[1] ? '$' : `$${p[2]}`)
+      } else if (/[[\]]/.test(s)) bad = true
+      else parts.push(s)
+    }
+    if (bad) { out.problems.push({ file: rel(f), message: 'a segment mixes text and a `[param]`; use a whole segment `[name]`' }); continue }
+    if (splat && parts.at(-1) !== '$') { out.problems.push({ file: rel(f), message: '`[...rest]` must be the last segment' }); continue }
+    const pattern = '/' + parts.join('/')
+    out.routes.push({
+      id: pattern, file: rel(f), layouts: chain(d, layoutOf), path: '/' + segs.join('/'), pattern, params, splat,
+      // Static segments outrank params, params outrank a splat (router-core's order; the client table uses it).
+      rank: parts.map(p => (p === '$' ? 0 : p.startsWith('$') ? 1 : 2)),
+      card: cards.get(base), kind: 'page',
+    })
+  }
+  out.routes.sort((a, b) => cmpRank(a.rank, b.rank) || a.id.localeCompare(b.id))
+  for (const [b, file] of cards) if (!out.routes.some(r => r.card === file)) out.problems.push({ file, message: `no route \`${b}\` for this card` })
+  return out
+}
+
+/** Layout ids from the root down to `d`. */
+function chain(d, layoutOf) {
+  const out = []
+  const parts = d ? d.split('/') : []
+  for (let i = 0; i <= parts.length; i++) {
+    const id = layoutOf.get(parts.slice(0, i).join('/'))
+    if (id) out.push(id)
+  }
+  return out
+}
+
+function cmpRank(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === undefined) return 1 // shorter after: `/users/new` is tried before `/users/$id/edit`… only on ties
+    if (b[i] === undefined) return -1
+    if (a[i] !== b[i]) return b[i] - a[i]
+  }
+  return 0
+}
+
+/** `/users/$id` with `{ id: '42' }` → `/users/42`; a splat fills `$`. */
+export function fillPath(pattern, params) {
+  return pattern.replace(/\$([\w$]*)/g, (_, name) => {
+    const v = params[name || '_splat'] ?? params[name]
+    return name ? encodeURIComponent(String(v)) : String(v ?? '')
+  })
+}
+
+/** A route's file path as authors write it in types: `src/routes/users/[id].tsx` → `/users/[id]`, `index.tsx` → `/`. */
+export function filePath(manifest, route) {
+  return '/' + route.file.slice(manifest.dir.length + 1).replace(EXT, '').replace(/(^|\/)index$/, '')
+}
+
+/** `.weft/routes.d.ts`: every route path, so `RouteProps<…, '/users/[id]'>` and `Meta<…, path>` only take real ones. */
+export function routeTypes(manifest) {
+  const pages = manifest.routes.filter(r => r.kind === 'page')
+  const lines = pages.map(r => `    '${filePath(manifest, r)}': true`)
+  return `// Generated by weft from ${manifest.dir}. Do not edit.\nimport '@weft-js/start'\ndeclare module '@weft-js/start' {\n  interface RouteFiles {\n${lines.join('\n')}\n  }\n}\n`
+}

package/src/run.tsx

@@ -0,0 +1,198 @@
+// The client (`client.tsx` starts it) and its router (research 25 §3): hydrate the server's page, then navigate without page loads. A navigation
+// fetches `/_weft/data/<path>` (the server matches, runs the loaders and merges the head, so loaders never ship to
+// the client), loads the route chunks it needs (started in parallel from a guess against the route table), and
+// writes the levels: a level that keeps its route keeps its component and gets new params/data in place.
+// `setHead` writes the server's merged tags for the tab title and history; crawlers only read the server's HTML.
+//
+// Server functions (research 27): the query cache seeds itself from the page's `#weft-cache` as it loads, and gets
+// each navigation's `c` through `client.seed`, so hydration fetches nothing (and an app without queries doesn't ship
+// the cache). Redirects from loaders and server functions navigate (at most 5 in a row); a
+// mutation that invalidates a tag the current route's loaders read refetches the route data in place.
+
+import { drain, enter, hydrate, level as staticLevel, wake } from '@weft-js/core/dom'
+import { flush } from '@weft-js/core'
+import { setHead } from '@weft-js/core/head'
+import type { Held } from './boot'
+import { applyMatches, client, createRouteState, type Component, type Match, type NavigateOptions, type RoutePayload } from './router'
+import { App } from './view'
+import { ErrorPage, NotFoundPage } from './builtin'
+
+type Hot = ImportMeta & { hot?: { on(event: string, on: (data: { queries: boolean }) => unknown): void } }
+
+/** The client half of `virtual:weft/routes`: the page routes in match order, and a chunk loader per route id. */
+export interface ClientRoutes {
+  table: { id: string; pattern: string; layouts: string[] }[]
+  load: Record<string, () => Promise<{ default?: Component }>>
+  /** Each island's code, by id: all a static level loads (PLAN §11). */
+  islands?: Record<string, () => Promise<{ default: Component }>>
+}
+
+/** Hydrate the page in `#app` and take over its links. Resolves once hydrated. */
+const SLOW_FADE = 100 // ms from asking for a fade to it starting
+
+export async function start(routes: ClientRoutes, options: { container?: Element } = {}) {
+  const container = options.container ?? document.getElementById('app')!
+  const page: RoutePayload = JSON.parse(document.getElementById('weft-route')!.textContent)
+  const data = JSON.parse(document.getElementById('weft-data')?.textContent ?? 'null')
+  let tags = page.m.map(m => m.t ?? [])
+  const comps: Record<string, Component> = {}
+  // The built-in 404 and error pages stand in only when the app has no route file for them.
+  const builtin: Record<string, Component> = { 404: NotFoundPage, error: ErrorPage }
+  const chunk = (id: string) =>
+    comps[id] ? Promise.resolve()
+    : routes.load[id] ? routes.load[id]().then(m => { if (m.default) comps[id] = m.default })
+    : Promise.resolve(builtin[id] && (comps[id] = builtin[id]))
+  const islands: Record<string, Component> = {}
+  const island = (id: string) => islands[id] ? undefined : routes.islands![id]!().then(m => { islands[id] = m.default })
+  await Promise.all([...page.m.filter(m => !m.s).map(m => chunk(m.id)), ...(page.i ?? []).map(island)])
+  const route = createRouteState(page, comps)
+  let bag: RoutePayload['b']
+  route.mount = (html, depth, next) => staticLevel(html, depth, next, id => islands[id]! as never, bag ?? undefined, id => Promise.resolve(island(id)))
+  route.around = (_d, _id, body) => enter(body)
+  hydrate(() => <App route={route} />, container, { data })
+  client.route = route
+  const q = (window as Window & { __wq?: Held }).__wq
+  if (q) {
+    q.w = wake
+    if (q.l) wake(q.l)
+    drain()
+  }
+
+  let current: AbortController | undefined
+  let warm: { path: string; at: number; res: Promise<Response> } | undefined
+  // A fade pictures the whole page twice, and the picture holds up every frame. Where that's slow, the page just changes.
+  let fades = !(navigator.hardwareConcurrency <= 4)
+  async function go(href: string, opts: NavigateOptions & { pop?: boolean; hops?: number } = {}): Promise<void> {
+    const url = new URL(href, location.href)
+    if (url.origin !== location.origin) return location.assign(url.href)
+    current?.abort()
+    const ctrl = (current = new AbortController())
+    const path = url.pathname + url.search
+    for (const id of guess(routes, url.pathname)) void chunk(id) // chunk loads start with the data fetch, not after it
+    let next: RoutePayload
+    try {
+      const held = warm?.path === path && performance.now() - warm.at < 10_000 ? warm.res : undefined
+      warm = undefined
+      next = await (held ?? ask(url, ctrl.signal)).then(r => r.clone().json())
+    } catch (e) {
+      if (ctrl.signal.aborted) return
+      return location.assign(url.href) // the data request failed: let the server render the page
+    }
+    if (next.r) {
+      const hops = (opts.hops ?? 0) + 1
+      return hops > 5 ? location.assign(next.r) : go(next.r, { replace: opts.pop || opts.replace, hops }) // a back/forward to a moved URL replaces its entry
+    }
+    await Promise.all([...next.m.map(m => chunk(m.id)), ...(next.i ?? []).map(island)])
+    if (ctrl.signal.aborted) return
+    if (!opts.pop) history[opts.replace ? 'replaceState' : 'pushState'](null, '', url.href)
+    at = path
+    if (next.c) client.seed ? client.seed(next.c) : (client.seeds ??= []).push(...next.c)
+    tags = next.m.map(m => m.t ?? [])
+    bag = next.b
+    const swap = () => {
+      applyMatches(route, next.m.map(revive), path, next.s)
+      if (next.m.some(m => m.s)) current_(url.pathname)
+      if (next.h) setHead(next.h, url.pathname)
+      flush()
+      if (opts.scroll !== false && !opts.pop) {
+        const target = url.hash && document.getElementById(decodeURIComponent(url.hash.slice(1)))
+        target ? target.scrollIntoView() : window.scrollTo(0, 0)
+      }
+    }
+    // The old page stays on screen, as a picture, until the new one is ready to fade in. `hidden`: nothing would show it.
+    if (fades && document.startViewTransition && !document.hidden && !matchMedia('(prefers-reduced-motion: reduce)').matches) {
+      const started = performance.now()
+      const fade = document.startViewTransition(swap)
+      void fade.ready.then(() => { if (performance.now() - started > SLOW_FADE) fades = false }, () => {})
+      // a transition the browser aborts (a second navigation, a hidden tab) rejects `finished`: the page already swapped
+      void fade.finished.catch(() => {})
+      await fade.updateCallbackDone
+    }
+    else swap()
+  }
+  client.navigate = go
+  // Dev: server code changed under the page (vite.mjs). The route's data comes again, in place.
+  const refresh = async ({ queries }: { queries: boolean }) => {
+    const url = new URL(location.href)
+    const res = await ask(url)
+    // It doesn't load yet, and the error page would replace what's here: the next save asks again.
+    if (!res.ok || (await res.clone().json()).s >= 500) return
+    if (queries) client.refreshed?.()
+    warm = { path: url.pathname + url.search, at: performance.now(), res: Promise.resolve(res) }
+    await go(url.href, { pop: true })
+  }
+  if ((import.meta as Hot).hot) (import.meta as Hot).hot!.on('weft:refresh', changed => void refresh(changed))
+  // A mutation invalidated tags: when the route's loaders read one, refetch the route data (no history entry, no scroll).
+  client.invalidated = t => {
+    warm = undefined
+    if (tags.some(l => l.some(x => t.includes(x)))) void go(location.href, { pop: true })
+  }
+
+  document.addEventListener('click', e => {
+    if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+    const url = ours(e.target)
+    if (!url) return
+    e.preventDefault()
+    void go(url.href)
+  })
+  // A link the pointer rests on, or the keyboard lands on, has its chunks and data by the time it is pressed.
+  // `data-preload="off"` on a link opts out, and so does Save-Data.
+  let pending: ReturnType<typeof setTimeout> | undefined
+  const intent = (e: Event) => {
+    clearTimeout(pending)
+    const url = ours(e.target)
+    const path = url && url.pathname + url.search
+    if (!url || warm?.path === path || (e.target as Element).closest('[data-preload="off"]') || (navigator as Navigator & { connection?: { saveData?: boolean } }).connection?.saveData) return
+    pending = setTimeout(() => {
+      for (const id of guess(routes, url.pathname)) void chunk(id)
+      warm = { path: path!, at: performance.now(), res: ask(url) }
+      warm.res.catch(() => { warm = undefined })
+    }, e.type === 'focusin' ? 0 : 80)
+  }
+  document.addEventListener('pointerover', intent)
+  document.addEventListener('focusin', intent)
+  // An in-page anchor fires this too, and the page hasn't changed: re-rendering it would lose what's been scrolled to.
+  let at = location.pathname + location.search
+  addEventListener('popstate', () => {
+    if (location.pathname + location.search !== at) void go(location.href, { pop: true })
+  })
+  return route
+}
+
+const ask = (url: URL, signal?: AbortSignal) => fetch(`/_weft/data${url.pathname === '/' ? '' : url.pathname}${url.search}`, { signal: signal ?? null, headers: { accept: 'application/json' } })
+
+/** The URL a client navigation would take from this event's link, or nothing for a link the browser should follow. */
+function ours(target: EventTarget | null) {
+  const a = (target as Element | null)?.closest?.('a')
+  if (!a || (a.target && a.target !== '_self') || a.hasAttribute('download') || a.getAttribute('rel')?.includes('external')) return
+  const url = new URL(a.href, location.href)
+  if (url.origin !== location.origin || url.pathname.startsWith('/_weft/')) return
+  return url.pathname === location.pathname && url.search === location.search && url.hash ? undefined : url // not an in-page anchor
+}
+
+/** A kept static level has no binding for its links' current-page state: the same rule as `Link`, after the swap. */
+function current_(path: string) {
+  flush()
+  for (const a of document.querySelectorAll('a[aria-current="page"]')) if (a.getAttribute('href') !== path) a.removeAttribute('aria-current')
+  for (const a of document.querySelectorAll(`a[href="${CSS.escape(path)}"]:not([aria-current])`)) a.setAttribute('aria-current', 'page')
+}
+
+/** Deferred fields arrive resolved on navigation: they become settled promises again, so resources read them alike. */
+function revive(m: Match): Match {
+  if (!m.d?.length) return m
+  const data = { ...(m.data as Record<string, unknown>) }
+  for (const k of m.d) data[k] = Promise.resolve(data[k])
+  return { ...m, data }
+}
+
+/** The route ids `pathname` probably needs (its layouts and page), from the table; the server's answer decides. */
+function guess(routes: ClientRoutes, pathname: string): string[] {
+  const parts = pathname.split('/').filter(Boolean)
+  for (const r of routes.table) {
+    const segs = r.pattern.split('/').filter(Boolean)
+    const splat = segs.at(-1) === '$'
+    if (splat ? parts.length < segs.length - 1 : parts.length !== segs.length) continue
+    if (segs.every((s, i) => s === '$' || s.startsWith('$') || s === decodeURIComponent(parts[i] ?? ''))) return [...r.layouts, r.id]
+  }
+  return []
+}