@abide/abide 0.58.0 → 0.101.0

package/src/ui/bindElement.ts

@@ -0,0 +1,44 @@
+import { isReactive } from '#shared/reactive/isReactive.ts'
+import { isThenable } from '#shared/reactive/isThenable.ts'
+import type { Disposer } from '#shared/reactive/watch.ts'
+import { holdWhileLeaving } from './leave.ts'
+
+/**
+ * Hands an element to its `bind:element` value; returns the callback's `Disposer`, if any.
+ *
+ * 32.9 — THE NODE, HANDED OVER. Two forms and one call site: a `Reactive` of an element takes
+ * the node as its value, and a callback takes it as its argument and may hand back a `Disposer`
+ * — which is what a third-party widget wants, set up where the node arrives and torn down where
+ * it goes, rather than in a pair of lifecycle hooks that have to be kept in step.
+ *
+ * THE BRAND IS READ FIRST (1.6). A `Reactive` is callable and thenable, so a test for a function
+ * answers true for one — and the reference would have been handed to the value instead of being
+ * put in it.
+ *
+ * A `Reactive` IS NOT CLEARED ON TEARDOWN. Nothing decides that it should be: the clause says
+ * the value accepts an element, and a page that reads `field.focus()` from a handler after a
+ * region swapped is reading a node that left rather than a value that emptied. The callback
+ * form is where teardown is decided, and its `Disposer` is the whole of it.
+ *
+ * 32.38 — A `Disposer` HANDING BACK A THENABLE IS AN EXIT: the element's nodes stay until it settles.
+ */
+export function bindElement(
+    element: Element,
+    value: unknown,
+): Disposer | undefined {
+    if (isReactive(value)) {
+        ;(value as unknown as { set(next: unknown): void }).set(element)
+        return undefined
+    }
+    if (typeof value !== 'function') return undefined
+    const disposer = (value as (node: Element) => (() => unknown) | undefined)(
+        element,
+    )
+    if (typeof disposer !== 'function') return undefined
+    return () => {
+        const leaving = disposer()
+        // 1.6 — the brand first: a `Reactive` is thenable, and is not an exit.
+        if (!isReactive(leaving) && isThenable(leaving))
+            holdWhileLeaving(element, leaving)
+    }
+}

package/src/ui/bindProperty.ts

@@ -0,0 +1,79 @@
+// 32.5, 32.7, 32.8 — AN ELEMENT'S PROPERTY AND A VALUE, KEPT IN STEP BOTH WAYS. A watch writes the
+// value into the property; a listener writes the property back into the value. The server wrote the
+// value standing at render as the attribute (`emitComponent`), so hydration moves nothing that is
+// already right.
+//
+// 32.7 — A BOOLEAN BIND IS A BOOLEAN: the property is set to one, and mirrored as a boolean attribute
+// rather than written as a string.
+
+import {
+    boundValue,
+    groupHolds,
+    heldValue,
+    writeBound,
+} from '#shared/boundValue.ts'
+import { numberFromText } from '#shared/numberFromText.ts'
+import type { Scope } from './Scope.ts'
+
+type Bound = HTMLInputElement & HTMLDetailsElement
+
+export function bindProperty(
+    element: Element,
+    kind: 'value' | 'checked' | 'open' | 'group',
+    operand: unknown,
+    scope: Scope,
+): void {
+    const bound = element as Bound
+    if (kind === 'value') {
+        scope.watch(() => {
+            const value = boundValue(operand)
+            const text =
+                value === undefined || value === null ? '' : String(value)
+            if (bound.value !== text) bound.value = text
+        })
+        // A `<select>` settles on `change`; everything else that takes text reports each keystroke.
+        const event = bound.tagName === 'SELECT' ? 'change' : 'input'
+        bound.addEventListener(event, () => {
+            // A value that was a number stays one: what the reader typed is text, and the value is
+            // not the reader's to retype.
+            const standing = heldValue(operand)
+            const typed = bound.value
+            writeBound(
+                operand,
+                typeof standing === 'number'
+                    ? (numberFromText(typed) ?? typed)
+                    : typed,
+            )
+        })
+        return
+    }
+    if (kind === 'group') {
+        scope.watch(() => {
+            const checked = groupHolds(boundValue(operand), bound.value)
+            bound.checked = checked
+            bound.toggleAttribute('checked', checked)
+        })
+        bound.addEventListener('change', () => {
+            const standing = heldValue(operand)
+            // A checkbox group holds a list, and keeps its order; a radio group holds the one value.
+            if (Array.isArray(standing)) {
+                const next: unknown[] = []
+                for (const member of standing)
+                    if (member !== bound.value) next.push(member)
+                if (bound.checked) next.push(bound.value)
+                writeBound(operand, next)
+            } else if (bound.checked) writeBound(operand, bound.value)
+        })
+        return
+    }
+    // `checked` on an input, `open` on a `<details>`.
+    const property = kind
+    scope.watch(() => {
+        const on = Boolean(boundValue(operand))
+        if (bound[property] !== on) bound[property] = on
+        bound.toggleAttribute(property, on)
+    })
+    bound.addEventListener(kind === 'open' ? 'toggle' : 'change', () => {
+        writeBound(operand, bound[property])
+    })
+}

package/src/ui/bindSpread.ts

@@ -0,0 +1,44 @@
+// 32.11 — AN ELEMENT'S SPREAD, KEPT WRITTEN. The server wrote what the value carried at render; a
+// watch keeps writing it, removing an attribute the value no longer carries, and an `on<event>`
+// function becomes the element's listener, replaced when the value hands over another.
+
+import { spreadEntries } from '#shared/spread.ts'
+import type { Scope } from './Scope.ts'
+
+/** Keeps an element's spread attributes and `on<event>` listeners written as the value changes. */
+export function bindSpread(
+    element: Element,
+    read: () => unknown,
+    explicit: readonly string[],
+    scope: Scope,
+): void {
+    let written = new Set<string>()
+    const listeners = new Map<string, EventListener>()
+    scope.watch(() => {
+        const wanted: [string, EventListener][] = []
+        const next = new Set<string>()
+        for (const [name, text] of spreadEntries(read(), explicit, wanted)) {
+            next.add(name)
+            if (element.getAttribute(name) !== text)
+                element.setAttribute(name, text)
+        }
+        for (const name of written)
+            if (!next.has(name)) element.removeAttribute(name)
+        written = next
+        const seen = new Set<string>()
+        for (const [event, listener] of wanted) {
+            seen.add(event)
+            const standing = listeners.get(event)
+            if (standing === listener) continue
+            if (standing !== undefined)
+                element.removeEventListener(event, standing)
+            element.addEventListener(event, listener)
+            listeners.set(event, listener)
+        }
+        for (const [event, listener] of listeners)
+            if (!seen.has(event)) {
+                element.removeEventListener(event, listener)
+                listeners.delete(event)
+            }
+    })
+}

package/src/ui/escapeless.ts

@@ -0,0 +1,14 @@
+import { textOf } from '#shared/Raw.ts'
+
+// A run's dynamic part, on the CLIENT, where it is written through `data` rather than parsed.
+// `escapeText` exists because markup is a parse; a text node's `data` is not one, so escaping
+// here would put `&lt;` on the screen where the server put `<`.
+//
+// It is a named function rather than `String(...)` inline because the emitted run has to read the
+// same on both sides: the server concatenates escaped pieces, the client concatenates raw ones,
+// and a reader comparing the two modules should see one difference in one place.
+//
+// 32.26 — WHAT THIS WRITES IS TEXT, a `Raw` included: its html, which matches the server's bytes
+// where `String(new Raw(…))` was `[object Object]`. A run holding a `Raw` part is not written
+// through here at all — its binding asks `isRaw` first and parses the markup (`setMarkup`).
+export { textOf as escapeless }

package/src/ui/index.ts

@@ -0,0 +1,64 @@
+// The client runtime — what a compiled `.abide` bundle imports through `@abide/abide/runtime`.
+// Every module reached from here is in the client's static closure, so an export added here is
+// paid for on every page (CLAUDE.md, "seams and imports"). The list IS the budget.
+//
+// The steps a mount's walk takes and the checks a binding makes on what it found (`adoptWalk.ts`),
+// the write, the stringify a run's parts go through — and
+// what a DYNAMIC region needs: what WRITES into one (`fillRegion` for an arm, `fillEmpty` for a region
+// that fills itself,
+// `listAt` and `updateList` for a `{#for}` — which reconciles an array and appends an async
+// subject, 32.15 — and `replaceRow` for a row), what a hydration mismatch is answered with
+// (`warnMismatch`, 41.10), what every region's bindings are stopped through (`Scope`), what a
+// row's markup is parsed with (`markupNodes`)
+// and the anchors they are all counted from. 32.3's writes are THREE names rather than one
+// (`setAttribute`, `setStyleProperty`, `setClass`) for one reason said once: every `style:prop`
+// and every `class:name` on an element is merged by the server into the single `style` or `class`
+// attribute beside the author's own, so neither of those two attributes can be written back whole
+// — the CSSOM and `classList` are what touch the one declaration or the one token a binding owns.
+// A list is reached through `listAt` and `updateList` alone, so its rows' shape is no caller's.
+// Nothing that finds a node by something added to the document, because a compiler may not invent
+// structure an author's CSS or queries can see.
+
+// THE ROUTER IS NOT HERE. It has its own entry (`ui/routing.ts`, `@abide/abide/routing`), which is what
+// keeps the list below the budget this header calls it — a subsystem only the emitted route table
+// reaches does not belong on what every compiled module resolves through.
+
+export { REGION_CLOSE, REGION_OPEN } from '#shared/ANCHORS.ts'
+export { oneStyleValue } from '#shared/escapeText.ts'
+export { isRaw } from '#shared/Raw.ts'
+// 12.4 — the watches a component's setup opens, collected for the scope its markup makes.
+export { collectWatches } from '#shared/reactive/watch.ts'
+export { ArmRegion, ChosenRegion } from './ArmRegion.ts'
+// 41.10's adopt half of a walk the compiler emits twice from one traversal — see `adoptWalk.ts`.
+export {
+    elementHere,
+    regionFound,
+    regionHere,
+    runHere,
+    textHere,
+} from './adoptWalk.ts'
+// 39.6 — a module mounted into an empty region applies its own head, from inside its instance
+// (`emitClient`); only a module that carries its own markup and a `<head>` imports it.
+export { applyHead, liveHead } from './applyHead.ts'
+export { bindElement } from './bindElement.ts'
+export { bindProperty } from './bindProperty.ts'
+export { bindSpread } from './bindSpread.ts'
+export { escapeless } from './escapeless.ts'
+export { listAt, updateList } from './List.ts'
+export { warnMismatch } from './Mismatch.ts'
+export { markupNodes } from './parseMarkup.ts'
+export { replaceRow } from './reconcile.ts'
+export {
+    fillEmpty,
+    fillRegion,
+    isEmptyRegion,
+    type Region,
+} from './regions.ts'
+export { rowKeyOf } from './rowKeyOf.ts'
+export { EMPTY_SCOPE, Scope } from './Scope.ts'
+export { setAttribute } from './setAttribute.ts'
+export { setClass } from './setClass.ts'
+export { setMarkup } from './setMarkup.ts'
+export { setStyleProperty } from './setStyleProperty.ts'
+export { setText } from './setText.ts'
+export { TryRegion } from './TryRegion.ts'

package/src/ui/leave.ts

@@ -0,0 +1,35 @@
+/**
+ * 32.38 — AN ELEMENT LEAVING UNDER AN ANIMATION. A `bind:element` callback's `Disposer` that hands
+ * back a thenable — `element.animate(…).finished` — keeps the nodes holding that element in the
+ * document until it settles, wherever a region or a row removes them, and removes them then.
+ *
+ * AT THE NODE, NOT AT EACH CALLER: an arm's swap, a row the reconcile drops and a list emptied all
+ * remove through `removeUntil` and `removeRow`, and what is leaving is a property of the element, not
+ * of which of them reached it. A page with nothing leaving pays one `size` read per node removed.
+ */
+const LEAVING = new Map<Element, ChildNode[]>()
+
+/** Holds `element`'s removal until `settling` settles. */
+export function holdWhileLeaving(
+    element: Element,
+    settling: PromiseLike<unknown>,
+): void {
+    LEAVING.set(element, [])
+    const done = (): void => {
+        const held = LEAVING.get(element)
+        LEAVING.delete(element)
+        if (held !== undefined) for (const node of held) node.remove()
+    }
+    settling.then(done, done)
+}
+
+/** Removes `node`, or holds it where it is while an element it holds is leaving. */
+export function leave(node: ChildNode): void {
+    if (LEAVING.size !== 0)
+        for (const [element, held] of LEAVING)
+            if (node === element || node.contains(element)) {
+                held.push(node)
+                return
+            }
+    node.remove()
+}

package/src/ui/listenForRoutes.ts

@@ -0,0 +1,92 @@
+import type { Router } from './Router.ts'
+
+/**
+ * Routes link clicks and back/forward through the router; returns a function that stops listening.
+ *
+ * 30.7 IN THE TWO PLACES A READER ACTUALLY NAVIGATES FROM: a link, and the back button. Neither is
+ * a call to `navigate`, so a router that only answered the function would reload the document on
+ * every click — which is the clause's own "MUST NOT reload" failing exactly where it shows.
+ *
+ * ONE LISTENER ON THE DOCUMENT, not one per link: a page rebuilt between the listener and the
+ * click has different anchors, and per-link wiring is a subscription per row that the region the
+ * router just emptied cannot take back off.
+ */
+export function listenForRoutes(router: Router): () => void {
+    const onClick = (event: MouseEvent): void => {
+        if (!isPlainClick(event)) return
+        const url = sameOriginLink(event)
+        if (url === undefined || router.match(url.pathname) === undefined)
+            return
+        event.preventDefault()
+        void router.go(url)
+    }
+
+    // 30.14 — INTENT: a pointer over a link, a finger or button pressed on one, keyboard focus on
+    // one. Each asks for the route's chunks; asking again is the module cache answering, and an
+    // address with no route is `prefetch`'s to drop — its own match is the only one an intent pays.
+    const onIntent = (event: Event): void => {
+        const url = sameOriginLink(event)
+        if (url !== undefined) router.prefetch(url.pathname)
+    }
+
+    // BACK AND FORWARD HAVE ALREADY MOVED THE ADDRESS BAR by the time this runs, so the page is
+    // mounted where the bar already points and nothing is pushed for it. 30.20 — a step within the
+    // standing page, back over an in-page `#anchor` jump, is `go`'s to keep: nothing asked, nothing
+    // remounted.
+    const onPop = (): void => {
+        if (router.match(location.pathname) === undefined) {
+            location.reload()
+            return
+        }
+        void router.go(location.href, { replace: true, keepScroll: true })
+    }
+
+    const listening = new AbortController()
+    const options = { signal: listening.signal }
+    document.addEventListener('click', onClick, options)
+    document.addEventListener('pointerover', onIntent, options)
+    document.addEventListener('pointerdown', onIntent, options)
+    document.addEventListener('focusin', onIntent, options)
+    addEventListener('popstate', onPop, options)
+    return () => listening.abort()
+}
+
+/**
+ * The address a same-origin link leads to, or `undefined` for one the browser keeps whatever the
+ * routes say.
+ */
+function sameOriginLink(event: Event): URL | undefined {
+    // The nearest `<a href>` at or above the event, because the target is whatever text or icon
+    // the author put inside the link. `closest` also reaches an SVG `<a>`, whose `href` is an
+    // `SVGAnimatedString` rather than a URL, so the element type is what decides.
+    const anchor = (event.target as Element | null)?.closest?.('a[href]')
+    if (!(anchor instanceof HTMLAnchorElement)) return undefined
+    // WHAT THE BROWSER WOULD DO ANYWAY, left to the browser: a download, a new tab, another
+    // origin. An address this build has no route for is the caller's to check.
+    if (anchor.hasAttribute('download')) return undefined
+    const target = anchor.getAttribute('target')
+    if (target !== null && target !== '' && target !== '_self') return undefined
+    const href = anchor.getAttribute('href')
+    if (href === null || href.startsWith('#')) return undefined
+    const url = new URL(anchor.href, location.href)
+    if (url.origin !== location.origin) return undefined
+    return url
+}
+
+/**
+ * Whether a click is an unmodified primary click the app may take.
+ *
+ * A MODIFIED CLICK IS THE READER ASKING THE BROWSER, not the app: ctrl/cmd opens a tab, shift a
+ * window, alt downloads. Taking those is the single most complained-about thing a client router
+ * does, and it is four fields.
+ */
+function isPlainClick(event: MouseEvent): boolean {
+    return (
+        event.button === 0 &&
+        !event.metaKey &&
+        !event.ctrlKey &&
+        !event.shiftKey &&
+        !event.altKey &&
+        !event.defaultPrevented
+    )
+}

package/src/ui/measureLayer.ts

@@ -0,0 +1,34 @@
+import { LAYERS_ARMED } from './LAYER_NAMES.ts'
+
+// WHAT GIVES `shares()` A NUMERATOR. The engine lane reads its numerator out of the
+// `performance.measure` pairs THE CODE UNDER TEST EMITS, and these are abide's.
+//
+// DISARMED BY DEFAULT, AND READ ONCE. `performance.mark` is not free, and a framework that pays
+// for its own telemetry on every navigation is a framework nobody measures twice. The flag is read
+// at module load into a `const` so the branch is one monomorphic test the engine can fold, which
+// means THE HARNESS MUST ARM IT BEFORE ABIDE'S MODULE GRAPH LOADS — `page.addInitScript` followed
+// by a navigation, the pattern `compiled.spec.ts` already uses. Arming after boot does nothing,
+// and that is the trade for not branching on a global per op.
+//
+// PAIRED, NOT WRAPPED. A `withLayer(name, body)` would allocate a closure at every call site; the
+// open/close pair allocates nothing and costs one branch when disarmed.
+const ARMED =
+    (globalThis as unknown as Record<string, unknown>)[LAYERS_ARMED] === true
+
+/** The mark an `endLayer` measures back to. The concatenation is only paid when armed. */
+const OPENED = ':opened'
+
+export function beginLayer(name: string): void {
+    if (ARMED) performance.mark(name + OPENED)
+}
+
+/**
+ * Closes a layer opened by `beginLayer`, recording its `performance.measure`.
+ *
+ * `shares()` REFUSES A LAYER THAT RUNS OUTSIDE ITS OP, so an unbalanced pair is a throw in the
+ * spec rather than a wrong fraction. Every `beginLayer` owes one of these on every path out,
+ * including the ones that return early.
+ */
+export function endLayer(name: string): void {
+    if (ARMED) performance.measure(name, name + OPENED)
+}

package/src/ui/menuBridge.ts

@@ -0,0 +1,19 @@
+/**
+ * The channel a desktop app's window opens to the page for its menu, or `undefined` in a browser.
+ *
+ * ITS OWN MODULE, so the router asks without importing the reporter: `reportMenu` is a chunk only a
+ * page inside a desktop app loads. 38.89.
+ */
+export function menuBridge():
+    | { postMessage(message: string): void }
+    | undefined {
+    return (
+        globalThis as {
+            webkit?: {
+                messageHandlers?: {
+                    abideMenu?: { postMessage(message: string): void }
+                }
+            }
+        }
+    ).webkit?.messageHandlers?.abideMenu
+}

package/src/ui/moveNode.ts

@@ -0,0 +1,34 @@
+// MOVING A NODE WITHOUT TAKING IT OUT OF THE DOCUMENT FIRST.
+//
+// `insertBefore` on a node that is already in the document is a REMOVE and then an INSERT, and it
+// is the remove that costs: an `<iframe>` reloads its document, a `<video>` pauses, a CSS
+// animation and a running transition restart, and focus leaves the element. `moveBefore` is the
+// same reorder with the node never leaving the tree, so none of that happens.
+//
+// THIS IS A CORRECTNESS SWAP AND NOT A PERFORMANCE ONE, and the distinction is the reason it is
+// worth writing down. `harness/measure`'s `elementsMoved` counts ONE move either way — both calls
+// move exactly one node — so the count that prices every other reconcile change is blind to this
+// one, and a gate built on it would be green against both arms. What separates them is an event:
+// the `load` an iframe fires when it is torn out, n per reorder against 0.
+//
+// PROBED, NOT VERSIONED. Where `moveBefore` is absent this is exactly the call the reconcile made
+// before it existed, so the fallback is today's behaviour rather than a degraded one. happy-dom
+// does not implement it, which is why the gate for this belongs in the browser lane — see
+// `packages/harness/e2e`.
+const CAN_MOVE =
+    typeof Element !== 'undefined' && 'moveBefore' in Element.prototype
+
+/**
+ * Moves an attached node to before `before`, keeping it in the document where the browser can.
+ *
+ * `node` MUST already be in the document under a parent — this is the SURVIVOR path, where a row
+ * the reconcile kept is being put back in a new order. A node with no parent is `moveBefore`'s
+ * one throwing case and `makeRow` is where those go, through `insertBefore`.
+ */
+export function moveNode(parent: Node, node: Node, before: Node | null): void {
+    if (CAN_MOVE)
+        (
+            parent as ParentNode & { moveBefore(n: Node, b: Node | null): void }
+        ).moveBefore(node, before)
+    else parent.insertBefore(node, before)
+}

package/src/ui/parseMarkup.ts

@@ -0,0 +1,35 @@
+// MARKUP PARSED IN THE DOCUMENT `near` BELONGS TO, not the global one. A page mounted into a second
+// document (an example `<iframe>`) parsed its `{#if}` arms in the right one and its `{#for}` rows in
+// the page's while the two were separate copies of this; one copy is one answer.
+//
+// ONE TEMPLATE PER DOCUMENT, reused: setting `innerHTML` replaces what the last parse left, and
+// every caller moves those nodes out before it parses again.
+const TEMPLATES = new WeakMap<Document, HTMLTemplateElement>()
+
+/** Parses markup in `near`'s document; the fragment is reused by the next parse. */
+export function parseMarkup(near: Node, markup: string): DocumentFragment {
+    const document = near.ownerDocument ?? (near as Document)
+    let template = TEMPLATES.get(document)
+    if (template === undefined) {
+        template = document.createElement('template')
+        TEMPLATES.set(document, template)
+    }
+    template.innerHTML = markup
+    return template.content
+}
+
+/**
+ * The parsed nodes as an array, which is what a row holds.
+ *
+ * Indexed rather than spread, so no iterator runs per row.
+ */
+export function markupNodes(near: Node, markup: string): Node[] {
+    const nodes: Node[] = []
+    for (
+        let node = parseMarkup(near, markup).firstChild;
+        node !== null;
+        node = node.nextSibling
+    )
+        nodes.push(node)
+    return nodes
+}