@abide/abide 0.58.0 → 0.101.0

package/src/ui/reconcile.ts

@@ -0,0 +1,368 @@
+import { PATCHES } from '#shared/reactive/PATCHES.ts'
+import { LAYER_RECONCILE } from './LAYER_NAMES.ts'
+import type { List, RowBuilders } from './List.ts'
+import { HYDRATE_LOG } from './Mismatch.ts'
+import { beginLayer, endLayer } from './measureLayer.ts'
+import { moveRow, removeRow } from './rows.ts'
+import { EMPTY_SCOPE, type Scope } from './Scope.ts'
+
+// 41.8 — a KEYED list, reconciled by moving the nodes that are already there rather than by
+// rebuilding them. A rebuild produces the right screen and the wrong document: focus, selection,
+// scroll position and anything a row was in the middle of go with the nodes that were replaced.
+//
+// What a row is in the document — its element, or its anchored range — is `rows.ts`'s. Most lists
+// carry no per-row marker at all: the nodes between the region's anchors ARE the rows, and only a
+// body with several top-level nodes gets one anchor per ROW. That is ~2.5 bytes gzipped a row, not
+// the per-SLOT marker `benchGrid.ts` measured doubling a page.
+
+export type Row = {
+    key: unknown
+    /**
+     * The value the row was built from.
+     *
+     * A row that survives a reorder keeps its NODES, which is the whole point — but if the value
+     * behind that key is a different object, its content is stale and the row is remade. Identity
+     * is the signal here, the inverse of the case where a freshly built wrapper defeats one.
+     */
+    data: unknown
+    /**
+     * The row's first node: its element, or its `ROW_OPEN` anchor where the body has several —
+     * the start of a range, not the nodes `make` handed back (`rows.ts`).
+     */
+    node: ChildNode
+    /** The row's bindings, stopped when it leaves. */
+    scope: Scope
+    /**
+     * Where this row stood in the list the document currently shows.
+     *
+     * The placement walk needs "already in order" to be a question about POSITIONS rather than
+     * about nodes, and asking the document — `compareDocumentPosition`, or counting siblings — is
+     * the walk this exists to avoid. Written by every reconcile, so it is a fact about the last one
+     * rather than about the caller, and a hydration seed sets it because that IS the order the
+     * server painted.
+     */
+    at: number
+    /**
+     * The patch epoch the row was made at (32.33).
+     *
+     * Its item written past this is content the row never saw, under the same object a kept row is
+     * matched by.
+     */
+    seen: number
+}
+
+/**
+ * Rebuilds a row in place from `next`, keeping its record.
+ *
+ * 41.10 — a row that cannot be hydrated is rebuilt: the fresh nodes go where the row stood and the
+ * row's record takes the new first node, so the reconcile still reaches all of it.
+ */
+export function replaceRow(row: Row, next: Node[]): void {
+    const first = row.node
+    const parent = first.parentNode
+    if (parent === null) return
+    for (const node of next) parent.insertBefore(node, first)
+    removeRow(first)
+    row.node = next[0] as ChildNode
+}
+
+/**
+ * Reconciles a keyed list's rows to `data`, moving survivors rather than remaking them.
+ *
+ * A key it has not seen gets a row from the builders `list.setUp` answers for it (14.8). Rows that
+ * survive are MOVED, never remade.
+ */
+export function reconcile(list: List, data: unknown[]): void {
+    const region = list.region
+    const current = list.rows
+    const wanted = data.length
+    const keys = new Array<unknown>(wanted)
+    for (let at = 0; at < wanted; at += 1) keys[at] = list.key(data[at], at)
+    const held = new Map<unknown, Row>()
+    // 41.14 — A KEY THE LIST REPEATS IS STILL A ROW, and the map cannot hold two under one key.
+    // Overwritten silently, the shadowed row became unreachable from `held`, from `next` and from
+    // the cleanup below: its `stop` was never called, so its readers woke on every write for the
+    // life of the page and wrote into nodes still standing in the document, and the list grew by
+    // one on every reconcile.
+    //
+    // LAST WINS, which is what the map already did — the fix is what happens to the row it
+    // shadows, not which of the two the walk reconciles. Held aside rather than in a per-key
+    // array, which would allocate one a row on a path walked per row for a case no list should
+    // have.
+    let shadowed: Row[] | null = null
+    for (const row of current) {
+        const previous = held.get(row.key)
+        if (previous !== undefined) {
+            if (shadowed === null) shadowed = []
+            shadowed.push(previous)
+        }
+        held.set(row.key, row)
+    }
+
+    // SIZED UP FRONT because it is filled from the END: the first store into an empty array at a
+    // high index is a sparse array, and `next` is the next reconcile's `current`.
+    const next = new Array<Row>(wanted)
+    const parent = region.close.parentNode
+    if (parent === null) return
+    // OPENED AFTER THE ONLY EARLY EXIT, and closed in the `finally` below, which is where a row that
+    // throws while it is made leaves. A region with no parent reconciles nothing and is not a layer
+    // that ran.
+    beginLayer(LAYER_RECONCILE)
+    // Declared ahead of the walk for the `catch`, which drops whatever the walk was holding.
+    const survivor = new Array<Row | null>(wanted)
+    try {
+        // BEFORE THE ANCHORS ARE TAKEN, and that ordering is the whole of it: a shadowed row stands
+        // EARLIER in the document than the row that won its key, so dropping it after the placement
+        // walk would pull a node the walk is resting on out from under it.
+        if (shadowed !== null) {
+            warnRepeatedKey(list)
+            for (const row of shadowed) dropRow(row)
+        }
+
+        // RESOLVE EVERY WANTED ROW BEFORE MOVING ANY NODE. A single forward pass that moves as it
+        // decides cannot know whether the row it is about to move is the one that should move: it
+        // sees a row that is not where it wants it and moves it, and if the node it was resting on
+        // belongs LATER in the wanted order every row between the two is moved past it too.
+        // Measured, on 200 rows: swapping the 2nd and the 198th moved 197 elements where 2 are
+        // needed, and cost more wall clock (30.4 µs) than reversing the whole list (29.2 µs).
+        // Reordering two rows was dearer than reordering every row.
+        //
+        // NOTHING ABOUT THE OUTPUT SHOWS IT — the document is correct either way, which is why
+        // `list.test.ts` was green: it asserts a two-row ADJACENT swap moves one element, and that
+        // case the forward walk gets right. So this is gated as a COUNT, per case shape, carrying the
+        // numbers the forward walk reported.
+        // Its index in `current` for a row that survives, -1 for one this document does not have. A
+        // plain array rather than a typed one: it is allocated per reconcile, and an Int32Array's
+        // construction is not repaid at the sizes a list reaches.
+        //
+        // SIZED LIKE `next` ABOVE, for the same reason and none of its caveat: the loop below fills
+        // both front-to-back for exactly `wanted` iterations, so neither can go sparse, and growing
+        // them by `push` paid log2(n) reallocate-and-copy passes per reconcile on each.
+        const from = new Array<number>(wanted)
+        // Whether every survivor already stands in the wanted order, asked while `from` is built.
+        let ordered = true
+        let lastSurvivor = -1
+        for (let at = 0; at < wanted; at += 1) {
+            const key = keys[at] as unknown
+            const existing = held.get(key)
+            // `Object.is` RATHER THAN `===`, for NaN: `NaN === NaN` is false, so a row whose value is
+            // NaN never matched itself and was stopped, removed and remade on every reconcile —
+            // taking its focus, selection, scroll position and any transition mid-flight with it —
+            // while the text on screen stayed identical, so nothing about the output could show it.
+            if (
+                existing !== undefined &&
+                Object.is(existing.data, data[at]) &&
+                !patchedSince(existing)
+            ) {
+                held.delete(key)
+                existing.seen = PATCHES.epoch
+                survivor[at] = existing
+                from[at] = existing.at
+                if (existing.at < lastSurvivor) ordered = false
+                lastSurvivor = existing.at
+                continue
+            }
+            // Either a key never seen, or one whose value is a different object or one a patch wrote
+            // to — each is a row this document does not have, and each is made. A stale one's nodes go NOW: the placement
+            // walk anchors on nodes that are still attached, and a node about to be replaced is not
+            // one of them.
+            if (existing !== undefined) {
+                held.delete(key)
+                dropRow(existing)
+            }
+            survivor[at] = null
+            from[at] = -1
+        }
+
+        // THE ROWS THAT NEED NOT MOVE ARE THE LONGEST RUN ALREADY IN ORDER. Every survivor outside it
+        // moves exactly once, and that is the minimum: a row is in its final relative position or it
+        // is not. O(n log n) over the survivors against a walk that could move n.
+        //
+        // NOTHING MOVED IS THE COMMON SHAPE — an append, a removal, a row's value changing — and then
+        // the run is every survivor, which the loop above already knows. Skipping the patience sort
+        // there measured in Chromium, on a reconcile that moves nothing: 48 -> 38 µs at 1,000 rows and
+        // 630 -> 540 µs at 10,000, over two runs each. Under a frame either way — what it buys is the
+        // three allocations per reconcile the sort makes, on the reconcile most lists run.
+        const keep = ordered ? null : longestRun(from)
+
+        // BACKWARDS, because the anchor a row is placed before is the row that FOLLOWS it, and by the
+        // time the walk reaches one that row is either already placed or still standing where it was.
+        // Forwards, the anchor is whatever happens to be next in a document the walk is rewriting.
+        let anchor: ChildNode | null = region.close
+        for (let at = wanted - 1; at >= 0; at -= 1) {
+            const existing = survivor[at]
+            if (existing === undefined || existing === null) {
+                const row = makeRow(
+                    list,
+                    parent,
+                    anchor,
+                    keys[at],
+                    data[at],
+                    at,
+                )
+                next[at] = row
+                anchor = row.node
+                continue
+            }
+            // In the run that is already ordered: untouched, since a move there changes nothing and
+            // still counts as one. 32.29 — a survivor is moved without leaving the document (`moveNode`).
+            if (keep !== null && keep[at] !== 1)
+                moveRow(parent, existing.node, anchor)
+            existing.at = at
+            next[at] = existing
+            anchor = existing.node
+        }
+
+        // What the new order did not ask for.
+        for (const row of held.values()) dropRow(row)
+        list.rows = next
+    } catch (thrown) {
+        // A ROW THAT THROWS WHILE IT IS MADE leaves the walk half done: the rows after it are made
+        // and standing but recorded nowhere, and `list.rows` still names rows already dropped, so
+        // the next reconcile made those rows a second time. Every row the walk still held goes, and
+        // the next reconcile builds into an empty region. A partial record would not do: a row's
+        // `at` is where the longest-run skip believes it stands, and mid-walk that is not where it is.
+        for (let at = 0; at < wanted; at += 1) {
+            const row = survivor[at] ?? next[at]
+            if (row !== undefined && row !== null) dropRow(row)
+        }
+        for (const row of held.values()) dropRow(row)
+        list.rows = []
+        throw thrown
+    } finally {
+        endLayer(LAYER_RECONCILE)
+    }
+}
+
+/** A new row, built and inserted before `before`. */
+export function makeRow(
+    list: List,
+    parent: Node,
+    before: Node,
+    key: unknown,
+    item: unknown,
+    at: number,
+): Row {
+    // 14.8 — set up ONCE for the row, and the same builders make it and mount it.
+    const builders = list.setUp(item, at)
+    const nodes = builders.make(parent.ownerDocument as Document, item, at)
+    for (const node of nodes) parent.insertBefore(node, before)
+    return rowOf(builders, key, item, nodes[0] as ChildNode, at)
+}
+
+/**
+ * A row record over nodes already in the document, mounted.
+ *
+ * The one place a row's record is written, so its shape is fixed once for every path that makes one
+ * — a made row and a hydrated one alike. The mount is handed the RECORD, because a row it rebuilds
+ * (41.10) has a new first node to write back.
+ */
+export function rowOf(
+    builders: RowBuilders,
+    key: unknown,
+    item: unknown,
+    node: ChildNode,
+    at: number,
+): Row {
+    const row: Row = {
+        key,
+        data: item,
+        node,
+        // A `Scope` rather than `undefined` until the mount returns, so the field holds one class
+        // for the record's whole life.
+        scope: EMPTY_SCOPE,
+        at,
+        seen: PATCHES.epoch,
+    }
+    row.scope = builders.mount(row, item, at)
+    return row
+}
+
+/**
+ * Whether a patch wrote to the row's item since the row was made.
+ *
+ * 32.33 — the epoch is compared first, so a reconcile with no patch since its rows were made pays
+ * one integer compare a row and never reaches the map.
+ */
+function patchedSince(row: Row): boolean {
+    if (row.seen === PATCHES.epoch) return false
+    const item = row.data
+    if (item === null || typeof item !== 'object') return false
+    return (PATCHES.written.get(item) ?? 0) > row.seen
+}
+
+/**
+ * Stops a row's bindings, then removes its nodes.
+ *
+ * Stopped first, so a binding cannot wake over a node that is already gone.
+ */
+export function dropRow(row: Row): void {
+    row.scope.stop()
+    removeRow(row.node)
+}
+
+/**
+ * Warns about a repeated `{#for}` key, once per block.
+ *
+ * 41.15 — ONCE FOR THE BLOCK, not once a reconcile. A repeated key is a property of the `by`
+ * expression rather than of one write, so it holds for every reconcile the region ever runs and a
+ * warning per write is a console nobody reads.
+ *
+ * `abide:hydrate` RATHER THAN A CHANNEL OF ITS OWN. A repeated key is not a hydration mismatch —
+ * it survives a reconcile that no hydration was anywhere near — but the registry's meaning for
+ * that namespace is THE BROWSER LANE, not a mismatch, and it is the only namespace 28.9 gives the
+ * client runtime. A second one buys an app a second name to learn and silence for one warning,
+ * where widening the lane's one meaning costs nothing that has to be taught.
+ */
+function warnRepeatedKey(list: List): void {
+    if (list.warned) return
+    list.warned = true
+    HYDRATE_LOG.warning(
+        'abide: a {#for} key is repeated in this list, so the last row under it is the one kept and the rows it shadows are dropped. RULEBOOK 41.14.',
+    )
+}
+
+/**
+ * Flags, per wanted index, the rows in the longest subsequence already in order.
+ *
+ * Patience sorting: `tails[length - 1]` is the wanted-index of the smallest tail any increasing run
+ * of that length ends on, so the binary search finds the run each row extends, and `came` walks the
+ * answer back out.
+ *
+ * WHY A SUBSEQUENCE AND NOT A RUN OF NEIGHBOURS. The rows that can stay put are the ones already
+ * in the right order RELATIVE TO EACH OTHER — they need not be adjacent, and demanding they be
+ * would move rows that a gap of new or removed rows had merely spread apart.
+ *
+ * -1 IS A ROW THIS DOCUMENT DOES NOT HAVE, and it is skipped rather than ordered: a made row is
+ * inserted wherever the walk puts it, so it never counts as already in place and must never
+ * anchor a run that would hold a survivor still.
+ */
+function longestRun(from: number[]): Uint8Array {
+    const keep = new Uint8Array(from.length)
+    // The wanted-index each run of a given length currently ends on.
+    const tails: number[] = []
+    // For each wanted index, the index its run continues from.
+    const came = new Int32Array(from.length).fill(-1)
+    for (let at = 0; at < from.length; at += 1) {
+        const value = from[at] as number
+        if (value < 0) continue
+        let low = 0
+        let high = tails.length
+        while (low < high) {
+            const middle = (low + high) >> 1
+            if ((from[tails[middle] as number] as number) < value)
+                low = middle + 1
+            else high = middle
+        }
+        if (low > 0) came[at] = tails[low - 1] as number
+        tails[low] = at
+    }
+    for (
+        let at = tails.length === 0 ? -1 : (tails[tails.length - 1] as number);
+        at >= 0;
+    ) {
+        keep[at] = 1
+        at = came[at] as number
+    }
+    return keep
+}

package/src/ui/regions.ts

@@ -0,0 +1,137 @@
+import { REGION_CLOSE, REGION_OPEN } from '#shared/ANCHORS.ts'
+import { LAYER_FILL } from './LAYER_NAMES.ts'
+import { leave } from './leave.ts'
+import { Mismatch } from './Mismatch.ts'
+import { beginLayer, endLayer } from './measureLayer.ts'
+
+export type Region = { open: Comment; close: Comment }
+
+/**
+ * Whether a comment's data opens a region: `REGION_OPEN`, or an open naming the arm the server
+ * painted (41.24, `armAnchor`).
+ *
+ * BY THE FIRST CHARACTER, so a walk counting depth reads every spelling of an open as one. No other
+ * comment a document carries starts with it: an author's comment is dropped at compile, and a
+ * run's and a row's anchors are spelled apart (`RAW_OPEN`, `ROW_OPEN`).
+ */
+export function opensRegion(data: string): boolean {
+    return data[0] === REGION_OPEN
+}
+
+/**
+ * The `REGION_CLOSE` that ends the region `open` starts, or null where it is not closed in this
+ * parent.
+ *
+ * Walked by DEPTH because a region nested inside carries its own pair.
+ */
+export function closeOf(open: Node): Comment | null {
+    let depth = 0
+    for (let node = open.nextSibling; node !== null; node = node.nextSibling) {
+        if (node.nodeType !== 8) continue
+        const data = (node as Comment).data
+        if (opensRegion(data)) depth += 1
+        else if (data === REGION_CLOSE) {
+            if (depth === 0) return node as Comment
+            depth -= 1
+        }
+    }
+    return null
+}
+
+/**
+ * The page's region, as the server wrote it; throws `Mismatch` where the host holds none.
+ *
+ * The first `REGION_OPEN` among the host's children and the close that ends it. The server writes
+ * the page between the same pair `renderComponent` writes a child between (41.9), so everything a
+ * shell puts in the host — its module script, a stylesheet link — stands outside the pair wherever
+ * the shell put it, and nothing here has to guess where the page ends.
+ */
+export function pageRegion(host: Node): Region {
+    for (let node = host.firstChild; node !== null; node = node.nextSibling) {
+        if (node.nodeType !== 8 || (node as Comment).data !== REGION_OPEN)
+            continue
+        const close = closeOf(node)
+        if (close !== null) return { open: node as Comment, close }
+    }
+    throw new Mismatch(
+        "abide: the host holds no page region, so the client and the server disagree about this document's shape (41.10).",
+    )
+}
+
+/**
+ * Whether a region is an empty anchor pair waiting to be filled.
+ *
+ * 32.17 — a component the SERVER rendered arrives with its markup between its anchors and is
+ * hydrated; one a row builder wrote in the browser arrives as the anchor pair alone, and the child
+ * fills it from its own template. The empty pair is the whole of the signal, so nothing is added to
+ * the document to carry it.
+ */
+export function isEmptyRegion(region: Region): boolean {
+    return region.open.nextSibling === region.close
+}
+
+/**
+ * Replaces everything between a region's anchors with what `build` makes, or with nothing.
+ *
+ * The anchors themselves stay, which is what keeps every sibling after them addressable across a
+ * branch change.
+ *
+ * THE BUILD IS CALLED HERE, handed the region's own document, rather than its nodes being handed
+ * in. A region's document is its anchor's, and a mount's root is a `Region`, not a node, so the
+ * root has no document to ask for. And the `abide.fill` layer then times the build as well as the
+ * insert, which is the whole of what filling a region costs.
+ *
+ * 14.1 — A BUILD EVALUATES EVERY VALUE IT WRITES, so it must not run tracked: an arm's swap runs
+ * untracked (`ArmRegion`) and so do a list's rows (`updateList`).
+ */
+export function fillRegion(
+    region: Region,
+    build?: (document: Document) => Node[],
+): void {
+    // THE PARENT IS READ BEFORE ANYTHING IS REMOVED, and the removal only happens if there is
+    // one. Written as an unguarded removal followed by a `?.`-guarded insert, a region whose
+    // close anchor had been detached emptied itself and then dropped the new content on the
+    // floor — the one silent failure in a module where every other one refuses with 41.10 on it.
+    const parent = region.close.parentNode
+    if (parent === null)
+        throw new Mismatch(
+            `abide: this region is not in a document, so the client and the server disagree about this region's shape (41.10).`,
+        )
+    removeUntil(region.open.nextSibling, region.close)
+    if (build === undefined) return
+    beginLayer(LAYER_FILL)
+    try {
+        const made = build(region.close.ownerDocument as Document)
+        for (const one of made) parent.insertBefore(one, region.close)
+    } finally {
+        endLayer(LAYER_FILL)
+    }
+}
+
+/**
+ * Fills a region nobody painted; answers whether it did.
+ *
+ * 32.17, 41.4, 30.7 — THE FIRST ENTRY OF A REGION THAT FILLS ITSELF: a component the server
+ * rendered, a page it served, a slot it wrote, arrives with its markup and is hydrated; one the
+ * browser grew, navigated to, or the server left behind a subject in flight arrives as the pair
+ * alone and is built here. What every emitted component asks once, as one call rather than the
+ * `isEmptyRegion` guard written out at each.
+ */
+export function fillEmpty(
+    region: Region,
+    build?: (document: Document) => Node[],
+): boolean {
+    if (!isEmptyRegion(region)) return false
+    fillRegion(region, build)
+    return true
+}
+
+/** Removes `from` and every sibling after it, up to and not including `end`. */
+export function removeUntil(from: ChildNode | null, end: Node | null): void {
+    let node = from
+    while (node !== null && node !== end) {
+        const next: ChildNode | null = node.nextSibling
+        leave(node)
+        node = next
+    }
+}

package/src/ui/reportMenu.ts

@@ -0,0 +1,57 @@
+// 38.89 — A ROUTE'S MENU, TOLD TO THE WINDOW IT IS SHOWN IN. Loaded only inside a desktop app, where
+// the window has opened `abideMenu` to the page; anywhere else the router never imports it.
+
+import { MenuEntry, type MenuItem } from '#shared/menuItem.ts'
+import { navigate } from '#shared/navigate.ts'
+import { menuBridge } from './menuBridge.ts'
+
+/** A menu item as the window builds it: an item the page answers carries the `id` it is told by. */
+type Told =
+    | 'separator'
+    | {
+          label: string
+          key: string | undefined
+          role: string | undefined
+          id: number | undefined
+          items: Told[] | undefined
+      }
+
+// The items the last report numbered, by their `id`.
+let numbered: Exclude<MenuItem, 'separator'>[] = []
+let listening = false
+
+/** Tells the window the menus `chain` exports, layouts outermost first and the page last. */
+export function reportMenu(chain: { menu?: unknown }[]): void {
+    const bridge = menuBridge()
+    if (bridge === undefined) return
+    numbered = []
+    const told: Told[] = []
+    for (const level of chain)
+        if (Array.isArray(level.menu))
+            for (const menu of level.menu as MenuItem[]) told.push(tell(menu))
+    if (!listening) {
+        listening = true
+        // 38.91, 38.92 — the window names the item picked; the page does what it means.
+        addEventListener('abide:menu', (event) => {
+            const item = numbered[(event as CustomEvent<number>).detail]
+            if (item === undefined) return
+            if (item.href !== undefined) void navigate(item.href)
+            if (item instanceof MenuEntry) item.pick()
+        })
+    }
+    bridge.postMessage(JSON.stringify(told))
+}
+
+function tell(item: MenuItem): Told {
+    if (item === 'separator') return item
+    const answered = item.items === undefined && !('role' in item && item.role)
+    const told: Told = {
+        label: item.label,
+        key: item.key,
+        role: 'role' in item ? item.role : undefined,
+        id: answered ? numbered.length : undefined,
+        items: item.items?.map(tell),
+    }
+    if (answered) numbered.push(item)
+    return told
+}

package/src/ui/routing.ts

@@ -0,0 +1,18 @@
+// THE ROUTER'S OWN ENTRY, so that "the router is not part of what every page imports" is true by
+// CONSTRUCTION rather than by the bundler agreeing. `@abide/abide/runtime` is what every compiled client
+// module resolves through and its own header calls that list the budget; a whole subsystem on it
+// is a category error there whatever the bundler then manages.
+//
+// IT IS NOT A MEASURED BYTE SAVING, and the attempt is worth recording so nobody takes the
+// reasoning further than the number goes. Two entries both importing `@abide/abide/runtime`, built
+// `--splitting` so the barrel lands in a SHARED chunk — which is the configuration CLAUDE.md names
+// as where bun stops shaking — came out 7156 bytes with the router off the barrel against 7160
+// with it on, and zero router symbols in the output either way. Bun shook it out. So the argument
+// here is the structural one above, plus not resting a budget on a bundler behaviour the project's
+// own notes say not to rest one on; it is NOT "this saves the router's bytes", because it does not.
+//
+// ONE CALLER: the `routes.ts` the build emits for an app that HAS pages, through
+// `ROUTING_SPECIFIER`. An app with no `page.abide` under `pages/` never resolves this entry.
+
+export { listenForRoutes } from './listenForRoutes.ts'
+export { type PageMount, type Route, Router, startRouter } from './Router.ts'

package/src/ui/rowKeyOf.ts

@@ -0,0 +1,19 @@
+// 32.32 — A `{#for}` WITH NO KEY OVER A `Reactive` NAMED ALONE takes the value's `by`, and falls back
+// to `positional` (32.13) on anything else. Resolved ONCE, when the block is built, so a row pays
+// one call and no lookup.
+//
+// THROUGH A LEAF, NOT `Reactive.ts` — `byOf` says why.
+import { byOf } from '#shared/reactive/byOf.ts'
+
+/** The row-key function for an unkeyed `{#for}`: the `Reactive`'s `by`, else `positional`. */
+export function rowKeyOf(
+    subject: unknown,
+    positional: (item: unknown, at: number) => unknown,
+): (item: unknown, at: number) => unknown {
+    const by = byOf(subject)
+    if (by === null) return positional
+    // THE ELEMENT ALONE: an app's function declared `(element) => unknown`, and the index a row
+    // key is handed would reach a second parameter it never agreed to.
+    if (typeof by === 'function') return (item) => by(item)
+    return (item) => (item as Record<string, unknown>)[by]
+}