@vanilla-bean/components 2.0.0 → 2.0.3

package/components/Keyboard/Keyboard.js

@@ -96,8 +96,8 @@ class Keyboard extends Component {
 				}
 
 				new Key({
-					key,
 					...keyDefinition,
+					key,
 					appendTo: row,
 					onPointerDown: event => {
 						if (this.options.tactileResponse) tactileResponse();

package/components/Keyboard/Keyboard.lld.md

@@ -7,15 +7,36 @@ On-screen keyboard where layout switching rebuilds the key DOM rather than showi
 ## Layout switch produces only keys from the new layout - no residual keys remain
 
 - changing `layout` removes all existing keys and builds the new set from scratch; a key that exists in layout A but not layout B is definitively absent after the switch
-  - does switching layout remove keys from the previous layout?
-  - does the new layout's keys appear after switching?
+  - new Subject({ layout: "simple", appendTo: document.body }) captures k then Array.from(k.elem.querySelectorAll("button")).map(b => b.textContent) captures before then k.options.layout = "number" then Array.from(k.elem.querySelectorAll("button")).map(b => b.textContent) captures after -> before.includes("q") && after.includes("q") === false
+  - new Subject({ layout: "simple", appendTo: document.body }) captures k then Array.from(k.elem.querySelectorAll("button")).map(b => b.textContent) captures before then k.options.layout = "number" then Array.from(k.elem.querySelectorAll("button")).map(b => b.textContent) captures after -> before.includes("1") === false && after.includes("1")
 
 ## Key events carry the key definition alongside the key name
 
 - `keyDown`, `keyUp`, and `keyPress` emit with both the key name and its configuration object, so handlers can respond to semantic meaning rather than just the character pressed
-  - does a key press event include the definition object for that key?
+  - new Array() captures seen then new Subject({ layout: "simple", appendTo: document.body, onKeyPress: e => seen.push(e.detail) }) captures k then Array.from(k.elem.querySelectorAll("button")).find(b => b.textContent === "ABC") captures key then key.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then key.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) -> seen.length === 1 && seen[0].key === "simple" && seen[0].keyDefinition.text === "ABC"
+
+## A key is named by its layout entry, not by what it sends
+
+A definition's `key` is what a press sends; the layout entry is the key's name. Styling and labels hang off the name, so two entries that send the same key stay distinct buttons, and a definition that only changes what is sent keeps its own label and class.
+
+- a definition's `key` does not rename the button: its class and fallback label come from the layout entry
+  - new Subject({ layout: "media", keyDefinitions: { volUp: { key: "audio_vol_up", text: "" }, "!": { mod: "shift", key: "1" } }, layouts: { media: [["volUp", "!"]] }, appendTo: document.body }) captures k then Array.from(k.elem.querySelectorAll("button")) captures keys -> keys[0].classList.contains("volUp") && !keys[0].classList.contains("audio_vol_up") && keys[1].textContent === "!"
+- a press on a renamed key still emits the definition's `key`, so the handler receives what the definition sends
+  - new Array() captures seen then new Subject({ layout: "media", keyDefinitions: { volUp: { key: "audio_vol_up", text: "" } }, layouts: { media: [["volUp"]] }, appendTo: document.body, onKeyPress: e => seen.push(e.detail) }) captures k then k.elem.querySelector("button.volUp") captures key then key.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then key.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) -> seen.length === 1 && seen[0].key === "audio_vol_up"
 
 ## Regex-named keys match families of keys to one definition
 
 - a key definition whose name is a regex pattern matches all physical keys that satisfy it; modifier handling and key families are expressed as patterns, not enumerated one by one
-  - does a key matching a regex definition trigger that definition's behavior?
+  - new Subject({ layout: "number", keyDefinitions: { "^[0-9]$": { class: "digit" } }, appendTo: document.body }) captures k then Array.from(k.elem.querySelectorAll("button")) captures keys then keys.filter(b => b.className.includes("digit")).map(b => b.textContent) captures digits -> digits.length === 10 && digits.includes("0") && digits.includes("9") && !keys.some(b => b.textContent === "backspace" && b.className.includes("digit"))
+
+A name only counts as a pattern when it is anchored at both ends. Without that rule an ordinary name is a substring match against every key, so a definition called `a` would silently claim every key containing an `a`.
+
+- an unanchored name matches one key by name; only a name anchored at both ends is treated as a pattern
+  - new Subject({ layout: "number", keyDefinitions: { ".": { class: "dot" } }, appendTo: document.body }) captures k then Array.from(k.elem.querySelectorAll("button")) captures keys then keys.filter(b => b.className.includes("dot")) captures dotted -> keys.length > 5 && dotted.length === 1 && dotted[0].textContent === "."
+
+## Subscribing to a key event returns the means to stop
+
+Callers wire key handlers into components that come and go, so a subscription that cannot be undone is a leak. The subscribe helpers hand back an unsubscribe rather than requiring the caller to keep the original function around to pass to a removal call.
+
+- `onKeyDown`, `onKeyUp` and `onKeyPress` return a function that ends the subscription; after calling it, further presses are not delivered
+  - new Array() captures seen then new Subject({ layout: "simple", appendTo: document.body }) captures k then k.onKeyDown(() => seen.push("down")) captures offDown then k.onKeyUp(() => seen.push("up")) captures offUp then k.onKeyPress(() => seen.push("press")) captures offPress then Array.from(k.elem.querySelectorAll("button")).find(b => b.textContent === "q") captures key then key.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then key.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) then seen.slice() captures whileSubscribed then offDown() then offUp() then offPress() then key.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then key.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) -> whileSubscribed.length === 3 && seen.length === 3

package/components/Label/Label.js

@@ -171,8 +171,16 @@ class Label extends StyledLabel {
 			set(value) {
 				let forId = typeof value === 'string' ? value : value?.id || value?.elem?.id;
 
-				if (!forId && value?._component) {
-					forId = value.elem.id = value.uniqueId;
+				if (!forId) {
+					// Two shapes reach here: a component, which carries `elem` and `uniqueId`, and a raw
+					// element, which carries a `_component` backreference. The guard tested for the element
+					// shape while the body used the component shape, so neither worked -- a component
+					// produced an empty `for` and an element threw on `value.elem.id`. A label that looks
+					// associated but is not is worse than one that never claimed to be.
+					const component = value?.uniqueId ? value : value?._component;
+					const elem = value?.elem ?? (value?._component ? value : undefined);
+
+					if (component && elem) forId = elem.id = component.uniqueId;
 				}
 
 				if (this._labelText) this._labelText.elem.htmlFor = forId ?? '';

package/components/Label/Label.lld.md

@@ -6,8 +6,10 @@ Labeling wrapper with five structural variants. The key decision is that `varian
 
 ## Each variant applies a distinct class that drives its CSS behavior
 
+**browser:** true
+
 - 'collapsible', 'overlay', 'inline', 'inline-after', and 'simple' each apply their own class to the component element; swapping `variant` changes the class and the structural CSS rules that attach to it
-  - does the 'collapsible' variant produce a clickable element that shows and hides content?
+  - new Subject({ variant: "collapsible", label: "Section", appendTo: document.body }, Object.assign(document.createElement("div"), { id: "lld-content", textContent: "wrapped" })) captures l then l.elem.querySelector("label") captures lab then l.elem.querySelector("#lld-content") captures content then getComputedStyle(content).display captures atFirst then lab.click() then await new Promise(r => setTimeout(r, 80)) then getComputedStyle(content).display captures afterClick then lab.click() then await new Promise(r => setTimeout(r, 80)) -> getComputedStyle(lab).cursor === "pointer" && atFirst !== "none" && afterClick === "none" && getComputedStyle(content).display === atFirst
 
 ## Collapsed state is externally controllable, not just toggle-driven
 
@@ -17,4 +19,32 @@ Labeling wrapper with five structural variants. The key decision is that `varian
 
 ## Overlay label visibility is driven by CSS pseudo-class, not JavaScript
 
+**browser:** true
+
 - the overlay variant's label visibility responds to whether the input has content via the `:placeholder-shown` pseudo-class; the component adds the structural class and the CSS handles the rest
+  - new Subject({ variant: "overlay", label: "Name", appendTo: document.body }, Object.assign(document.createElement("input"), { placeholder: "type here" })) captures l then await new Promise(r => setTimeout(r, 700)) then l.elem.querySelector("label") captures lab then getComputedStyle(lab).transform captures whileEmpty then l.elem.querySelector("input").value = "filled" then await new Promise(r => setTimeout(r, 700)) -> whileEmpty !== "matrix(1, 0, 0, 1, 0, 0)" && getComputedStyle(lab).transform === "matrix(1, 0, 0, 1, 0, 0)"
+
+## The variant decides which side the label text sits on, and moving it is a move
+
+`inline-after` is the only variant that puts the text after the control, so switching variants has to relocate the existing text node rather than render a second one. Reassigning a variant is a reposition, not a rebuild.
+
+- the label text precedes the control except under `inline-after`, and changing variant moves the same text rather than adding another
+  - new Subject({ label: "Name", variant: "inline", appendTo: document.body, append: document.createElement("input") }) captures l then Array.from(l.elem.children).indexOf(l._labelText.elem) captures asInline then l.options.variant = "inline-after" then Array.from(l.elem.children).indexOf(l._labelText.elem) captures asAfter then l.options.variant = "inline" -> asInline === 0 && asAfter === 1 && Array.from(l.elem.children).indexOf(l._labelText.elem) === 0 && l.elem.children.length === 2
+
+## A collapsible label reports its own expanded state
+
+The label text is what a reader activates to open and close the section, so it is the element that has to carry `aria-expanded` -- and it has to stay in step with the `collapsed` option rather than being set once at construction.
+
+- a collapsible label starts expanded and follows the `collapsed` option
+  - new Subject({ label: "Sect", variant: "collapsible", appendTo: document.body }) captures l then l._labelText.elem.getAttribute("aria-expanded") captures atStart then l.options.collapsed = true -> atStart === "true" && l._labelText.elem.getAttribute("aria-expanded") === "false" && l.hasClass("collapsed")
+- becoming collapsible is what adds the state; a label that is not collapsible does not claim one
+  - new Subject({ label: "Sect", variant: "inline", appendTo: document.body }) captures l then l._labelText.elem.getAttribute("aria-expanded") captures asInline then l.options.variant = "collapsible" -> asInline === null && l._labelText.elem.getAttribute("aria-expanded") === "true"
+
+## The label is text or a full set of options, and `for` takes whatever identifies the control
+
+A label is usually a string, and stays that short. When it needs more it carries the label element's own options instead. `for` is the same idea applied to the target: a string id when the caller has one, and otherwise the control itself -- as a component or as an element -- with the label assigning an id if the control has none, because an association that silently fails is indistinguishable from a label that was never wired.
+
+- a string `label` becomes the text; an object is used as the label element's options
+  - new Subject({ label: "Str", appendTo: document.body }) captures s then new Subject({ label: { textContent: "Obj", addClass: "fancy" }, appendTo: document.body }) captures o -> s._labelText.elem.textContent === "Str" && o._labelText.elem.textContent === "Obj" && o._labelText.elem.classList.contains("fancy")
+- `for` accepts an id string, a component, or an element, and gives an unidentified control an id so the association actually holds
+  - new Subject({ label: "L", for: "explicit", appendTo: document.body }) captures byString then new Subject({ tag: "input" }) captures control then document.body.append(control.elem) then new Subject({ label: "L", for: control, appendTo: document.body }) captures byComponent -> byString._labelText.elem.htmlFor === "explicit" && control.elem.id.length > 0 && byComponent._labelText.elem.htmlFor === control.elem.id

package/components/Link/Link.js

@@ -1,5 +1,8 @@
 import { TooltipWrapper } from '../TooltipWrapper';
 
+/** The decoration every Link tooltip carries, merged onto whatever the caller passed. */
+const linkTooltip = { icon: 'link', style: { fontSize: '12px' } };
+
 /**
  * Link component with tooltip support and display variants.
  *
@@ -27,8 +30,22 @@ class Link extends TooltipWrapper {
 			},
 		},
 		tooltip: {
+			// One source for the decoration, read by both the default and the merge below; it used to
+			// be spelled out twice, once here and once inline in `set()`.
+			//
+			// The `default` has to stay. Replacing its *contents* with null changes no rendered
+			// tooltip -- `set()` supplies the decoration either way -- but removing the descriptor
+			// entirely means `set()` never runs for a Link that was given no tooltip, and the link
+			// decoration disappears. What the default provides is the presence of a value to set,
+			// not the value itself.
 			get default() {
-				return { icon: 'link', style: { fontSize: '12px' } };
+				return linkTooltip;
+			},
+			// Merge the decoration onto the caller's value so a plain string tooltip still gets the
+			// link icon, not just the object form. `next` continues the schema chain to
+			// TooltipWrapper's own tooltip set(), which expects an object or a string.
+			set(value, next) {
+				next(typeof value === 'object' ? { ...linkTooltip, ...value } : { ...linkTooltip, textContent: value });
 			},
 		},
 	};

package/components/Link/Link.lld.md

@@ -12,4 +12,11 @@ Anchor element with optional button styling. The decision: `variant: 'button'` c
 ## Tooltip includes a link icon automatically
 
 - when a tooltip string is provided, the tooltip is configured with a link icon alongside the text
-  - does a Link's tooltip show a link icon alongside the provided tooltip text?
+  - new Subject({ href: "#x", tooltip: "hello", textContent: "go" }) captures l -> l._tooltip.options.icon === "link" && l._tooltip.options.textContent === "hello"
+
+## The link icon comes with the tooltip, however the tooltip was written
+
+A link's tooltip is what tells a reader it leaves the page, so the icon is part of the default rather than something each call site remembers. A caller passing a plain string still gets it -- the default is merged onto their value, not replaced by it.
+
+- the tooltip carries the link icon whether the caller passed a string or nothing at all
+  - new Subject({ href: "https://example.com", textContent: "o", tooltip: "text tip", appendTo: document.body }) captures withString then new Subject({ href: "https://example.com", textContent: "o", appendTo: document.body }) captures byDefault -> withString.elem.querySelector("[popover]").style.fontSize === "12px" && byDefault.elem.querySelector("[popover]").style.fontSize === "12px" && withString.elem.querySelector("[popover]").textContent === "text tip"

package/components/List/List.lld.md

@@ -8,12 +8,19 @@ Flexible list that meets items where they are. The core design decision: items c
 
 - a single `items` array can contain mixed formats without error
   - does a List render a mix of string and object items without failing?
+  - new Subject({ items: undefined, appendTo: document.body }) captures missing then new Subject({ items: null, appendTo: document.body }) captures empty -> missing.elem.querySelectorAll("li").length === 0 && empty.elem.querySelectorAll("li").length === 0
+  - new Array() captures received then new Subject({ items: [{ textContent: "hi", listItemOptions: { addClass: "wrap" }, ListItemComponent: class { constructor(o) { received.push(Object.keys(o).join(",")); this.elem = document.createElement("b"); this.elem.textContent = "C"; } } }], appendTo: document.body }) captures l then l.elem.querySelector("li") captures li -> li.classList.contains("wrap") && received.length === 1 && !received[0].includes("listItemOptions")
 
 ## Per-item component overrides compose cleanly with the global default
 
 - the component set globally on the list applies to all items; a per-item `ListItemComponent` overrides for that item only
-  - does a per-item ListItemComponent render that item differently from the default?
+  - new Subject({ items: ["plain", { textContent: "x", ListItemComponent: class { constructor(o) { this.elem = document.createElement("b"); this.elem.textContent = "CUSTOM"; } } }] }) captures l then document.body.append(l.elem) then Array.from(l.elem.querySelectorAll("li")) captures items -> items.length === 2 && items[0].textContent === "plain" && items[1].querySelector("b").textContent === "CUSTOM"
 
 ## noStyle opts out of default list chrome for embedding contexts
 
-- `noStyle: true` removes bullets, padding, and line-height defaults via a CSS class so the embedding layout can control spacing
+**browser:** true
+
+The chrome being removed is CSS, so the check has to ask a real engine what it computed; a class name on the element proves only that the class was set.
+
+- `noStyle: true` removes the default list chrome (bullets, padding and line-height), leaving spacing to the embedding layout
+  - new Subject({ items: ["a"], noStyle: true, appendTo: document.body }) captures plain then new Subject({ items: ["a"], appendTo: document.body }) captures styled then getComputedStyle(plain.elem) captures ps then getComputedStyle(styled.elem) captures ss -> ps.listStyleType === "none" && ps.paddingLeft === "0px" && ss.listStyleType !== "none"

package/components/Menu/Menu.js

@@ -61,7 +61,16 @@ export default class Menu extends StyledList {
 		this.on({
 			targetEvent: 'pointerdown',
 			id: 'menuSelect',
-			callback: event => this.emit('select', event),
+			callback: event => {
+				// Selecting requires an item, the same way the keyboard path below requires a focused
+				// one. Emitting for any pointerdown on the menu meant clicking the padding, the gap
+				// between items, or the border fired `select` with nothing selected, leaving every
+				// consumer to work out from the event whether an item had actually been hit.
+				const item = event.target?.closest?.('li');
+				if (!item || !this.elem.contains(item)) return;
+
+				this.emit('select', event);
+			},
 		});
 
 		this.on({

package/components/Menu/Menu.lld.md

@@ -2,14 +2,35 @@
 
 > ./Menu.js
 
-Styled list whose items emit a registered `select` CustomEvent, with the activation event in `detail`. The design decision: Menu routes selection through the same unified pointer+keyboard activation path as Button; keyboard and pointer users get the same experience without separate handlers. `onSelect` is the option-form listener for the event.
+Styled list whose items emit a registered `select` CustomEvent, with the activation event in `detail`. The design decision: pointer and keyboard activation both resolve to the same `select` event -- the same principle Button applies to `onPointerPress` -- so keyboard and pointer users get the same experience without separate handlers. `onSelect` is the option-form listener for the event.
 
 ## Selecting a menu item works the same way regardless of input method
 
-- clicking, touching, Space/Enter, and screen reader activation all emit `select`; one handler, no separate keyboard path
+- clicking, touching, Space/Enter, and screen reader activation all emit `select`; one event, no separate keyboard path
   - does clicking a menu item invoke onSelect?
+  - does pressing Enter on a focused menu item invoke onSelect?
 
 ## Menu renders any item format that List supports
 
 - strings, objects with labels, and component instances all work as menu items
   - does a Menu with mixed string and object items render without error?
+
+## Exactly one item is in the tab order at a time
+
+A menu is one stop for the keyboard, not one stop per item: tabbing past a ten-item menu should take one press, and arrow keys move within it. That means a roving tabindex -- the first item is focusable, the rest are reachable only from inside.
+
+- the first item carries `tabindex=0` and every other item `-1`, so the menu is a single tab stop
+  - new Subject({ items: [{ textContent: "a" }, { textContent: "b" }, { textContent: "c" }], appendTo: document.body }) captures m then Array.from(m.elem.querySelectorAll("li")).map(li => li.getAttribute("tabindex")) captures tabs -> tabs.join() === "0,-1,-1"
+- an items list that is absent renders an empty menu rather than throwing
+  - new Subject({ items: undefined, appendTo: document.body }) captures missing then new Subject({ items: null, appendTo: document.body }) captures empty -> missing.elem.querySelectorAll("li").length === 0 && empty.elem.querySelectorAll("li").length === 0
+- activation on a node outside the menu selects nothing, so a menu never claims an event that was not its own
+  - new Array() captures fired then new Subject({ items: [{ textContent: "a" }], onSelect: () => fired.push(1), appendTo: document.body }) captures m then document.createElement("li") captures outsider then document.body.append(outsider) then outsider.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then outsider.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) -> fired.length === 0
+- pressing the menu's own padding selects nothing either; only a press that lands on an item counts
+  - new Array() captures fired then new Subject({ items: [{ textContent: "a" }], onSelect: () => fired.push(1), appendTo: document.body }) captures m then m.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then m.elem.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) then fired.length captures afterRootPress then m.elem.querySelector("li") captures item then item.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then item.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) -> afterRootPress === 0 && fired.length === 1
+
+## Arrow keys move focus within the menu and wrap at both ends
+
+The roving tabindex makes the menu one tab stop; arrow keys are what move inside it. Wrapping means a reader holding the key never lands on nothing, and it is what makes the first and last items reachable from each other without a Home/End convention.
+
+- ArrowDown advances and wraps past the last item; ArrowUp retreats and wraps past the first
+  - new Subject({ items: [{ textContent: "a" }, { textContent: "b" }, { textContent: "c" }], appendTo: document.body }) captures m then Array.from(m.elem.querySelectorAll("li")) captures lis then lis[0].focus() then new Array() captures seq then seq.push(lis.indexOf(document.activeElement)) then ["ArrowDown", "ArrowDown", "ArrowDown", "ArrowUp"].forEach(key => { m.elem.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true })); seq.push(lis.indexOf(document.activeElement)); }) -> seq.join() === "0,1,2,0,2"

package/components/Notify/Notify.lld.md

@@ -7,14 +7,26 @@ Transient notification that self-destructs. The design choice is that click-to-d
 ## Type communicates intent; the component selects the appropriate icon
 
 - callers pass `type: 'error'` and the component picks the matching icon; a custom `icon` option overrides this only when the standard mapping doesn't fit
-  - does a success notification use a visually distinct icon from an error notification?
+  - new Subject({ type: "success", textContent: "x" }) captures ok then new Subject({ type: "error", textContent: "x" }) captures bad then [ok, bad].map(n => (n.elem.className.match(/fa-[\w-]+/g) || []).join(" ")) captures icons -> icons[0].includes("fa-") && icons[1].includes("fa-") && icons[0] !== icons[1]
 
 ## Clicking anywhere on the notification dismisses it - the whole surface is the target
 
-- notifications are temporary and should be easy to clear; there is no separate close button
-  - does clicking the notification body remove it from the page?
+Notifications are temporary and should be easy to clear, so there is no separate close button to aim at.
+
+- a click anywhere on the notification dismisses it, its body included, rather than only on a dedicated control
+  - new Subject({ textContent: "hi", appendTo: document.body }) captures n then n.elem.isConnected captures shown then n.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) -> shown === true && n.elem.isConnected === false
 
 ## Manual dismiss cancels a pending timeout - no duplicate destroy fires
 
 - when a `timeout` is set and the user dismisses manually before it fires, the timer is cancelled so a second destroy call after the component is already gone cannot happen
-  - does manually dismissing a notification before its timeout prevent a second dismiss?
+  - new Array() captures calls then new Subject({ timeout: 50, appendTo: document.body, textContent: "hi" }) captures n then n.destroy = (...a) => { calls.push(1); return Object.getPrototypeOf(n).destroy.call(n, ...a); } then n.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then await new Promise(r => setTimeout(r, 160)) -> calls.length === 1
+
+## Severity decides how assertively the notification announces
+
+A screen reader interrupts for `alert` and waits for a quiet moment for `status`. Errors and warnings are worth interrupting for; a success or an informational note is not, and interrupting for those trains people to ignore the ones that matter.
+
+- `error` and `warning` announce as alerts; every other type announces politely
+  - new Subject({ type: "error", content: "m", appendTo: document.body }) captures err then new Subject({ type: "warning", content: "m", appendTo: document.body }) captures warn then new Subject({ type: "success", content: "m", appendTo: document.body }) captures ok then new Subject({ type: "info", content: "m", appendTo: document.body }) captures info -> err.elem.getAttribute("role") === "alert" && warn.elem.getAttribute("role") === "alert" && ok.elem.getAttribute("role") === "status" && info.elem.getAttribute("role") === "status"
+
+- a falsy `timeout` means the notification stays until something dismisses it; a positive one dismisses it after that long
+  - new Subject({ content: "stay", timeout: 0, appendTo: document.body }) captures kept then new Subject({ content: "go", timeout: 30, appendTo: document.body }) captures going then await new Promise(r => setTimeout(r, 90)) -> kept.elem.isConnected === true && going.elem.isConnected === false

package/components/Page/Page.lld.md

@@ -7,14 +7,25 @@ Top-level layout component that takes ownership of stylesheet loading. The desig
 ## Required stylesheets load once - remounting does not re-fetch
 
 - Page checks whether each stylesheet is already present before injecting; remounting in a single-page app does not duplicate link elements or re-trigger network requests
-  - does mounting a Page a second time leave the stylesheet count unchanged?
+  - new Subject({ styleSheets: ["/lld-dedup-probe.css"], appendTo: document.body }) captures first then document.querySelectorAll('link[rel="stylesheet"][href="/lld-dedup-probe.css"]').length captures afterFirst then new Subject({ styleSheets: ["/lld-dedup-probe.css"], appendTo: document.body }) captures second -> afterFirst === 1 && document.querySelectorAll('link[rel="stylesheet"][href="/lld-dedup-probe.css"]').length === 1
 
-## External stylesheets fetch and inject as style content, not link elements
+## A stylesheet is scoped by fetching it; otherwise it is linked
 
-- `styleSheets` URLs are fetched at mount time and their content is injected as `<style>` elements, avoiding cross-origin link restrictions
-  - does a stylesheet URL's content appear in the document as an inline style element?
+A caller that needs a stylesheet confined to part of the page gives it a `scope`, and the only way to
+wrap third-party CSS in a selector is to fetch the text and re-emit it. Without a scope there is
+nothing to rewrite, so the ordinary link is used.
+
+- an entry with a `scope` is fetched and its rules are emitted inline under that selector; a plain URL becomes a stylesheet link
+  - new Subject({ styleSheets: ["/lld-plain.css"], appendTo: document.body }) captures p -> document.querySelectorAll('link[rel="stylesheet"][href="/lld-plain.css"]').length === 1
 
 ## Page sets a full-height flex baseline at construction
 
 - height: 100% and flex display are applied as inline styles at construction
   - does a Page element have height: 100% applied at construction?
+
+## A stylesheet list tolerates gaps
+
+Stylesheet lists are usually built by concatenating conditionals, so holes in them are normal rather than a mistake. A hole is skipped; the entries around it still load.
+
+- falsy entries in `styleSheets` are skipped and the real entries beside them are still injected
+  - new Subject({ styleSheets: [null, "/real.css", undefined, ""], appendTo: document.body }) captures p -> Array.from(document.querySelectorAll("link[rel=stylesheet]")).some(l => l.getAttribute("href") === "/real.css")

package/components/Popover/Popover.lld.md

@@ -6,14 +6,18 @@ Native popover element with edge-aware placement. The design decision: position
 
 ## Placement adapts to viewport edges at the moment of showing
 
+**browser:** true
+
 - when the popover would overflow an edge, the position flips; this calculation runs on each `show()` call so it stays accurate as the page scrolls or resizes
+  - new Subject({ ...{ maxWidth: 264, maxHeight: 132, state: "manual", outsideClose: false, autoOpen: false, uniqueId: true }, x: 10, y: 10 }) captures near then near.show() then new Subject({ ...{ maxWidth: 264, maxHeight: 132, state: "manual", outsideClose: false, autoOpen: false, uniqueId: true }, x: window.innerWidth - 10, y: 10 }) captures far then far.show() -> near.elem.style.left !== "unset" && far.elem.style.left === "unset" && far.elem.style.right !== "unset"
 
 ## autoOpen fires after a short delay, not immediately
 
 - `autoOpen: true` queues `show()` after 200ms; failing immediately would break when the popover's anchor isn't yet in the DOM
   - does a popover with autoOpen not open synchronously on construction?
-  - does cancelling the popover before 200ms prevent it from opening?
+  - new Subject({ autoOpen: true, state: "manual", uniqueId: true, appendTo: document.body }) captures cancelled then new Subject({ autoOpen: true, state: "manual", uniqueId: true, appendTo: document.body }) captures control then await new Promise(r => setTimeout(r, 40)) then Object.keys(cancelled.cleanup) captures armed then cancelled.processCleanup() then await new Promise(r => setTimeout(r, 320)) -> armed.includes("autoOpen") && cancelled.elem.style.display !== "block" && control.elem.style.display === "block"
 
 ## Manual and auto state are distinct dismiss models
 
 - `state: 'auto'` delegates dismiss to the platform's native light-dismiss; `state: 'manual'` requires explicit `close()`; the choice belongs to the use site
+  - new Subject({ state: "auto", autoOpen: false, uniqueId: true, maxWidth: 264, maxHeight: 132, outsideClose: false }) captures a then new Subject({ state: "manual", autoOpen: false, uniqueId: true, maxWidth: 264, maxHeight: 132, outsideClose: false }) captures m -> a.elem.getAttribute("popover") === "auto" && m.elem.getAttribute("popover") === "manual"

package/components/RadioButton/RadioButton.js

@@ -85,7 +85,12 @@ class RadioButton extends Component {
 									new RadioButtonInput({
 										tag: 'input',
 										type: 'radio',
-										value: option?.value || option,
+										// As an attribute, not a bare option: `value` is an own property on Component, so
+										// the plain option set it on the component and never reached the element. Every
+										// radio kept the browser default of "on", which made `event.target.value` the
+										// same string for all of them and left the `value` setter below unable to match
+										// any input -- assigning a value cleared the selection instead of moving it.
+										attributes: { value: option?.value || option },
 										name: this.uniqueId,
 										checked: this.options.value === (option?.value || option),
 										onChange: event => {

package/components/RadioButton/RadioButton.lld.md

@@ -12,4 +12,17 @@ Radio group from an array of options. The design decision: the HTML `name` coord
 ## Options can separate their stored value from their display label
 
 - a string option uses its value as both the label and stored datum; an object with `label` and `value` lets them differ, useful when the stored value (an ID, a code) would be confusing as a visible label
-  - does an object option with a separate label display the label rather than the raw value?
+  - new Subject({ options: [{ label: "Visible", value: "v" }], value: "v" }) captures r -> r.elem.textContent.includes("Visible") && r.elem.textContent.includes("v") === false
+
+## The selected option is named by `value`, in both directions
+
+A radio group has one value, and it is the option's own value -- not the browser's default `on`, which would make every option report the same string. Assigning `value` moves the selection; picking an option reports that option back.
+
+- each option's value reaches its input, so the group's value identifies which option is selected
+  - new Subject({ options: ["a", "b", "c"], value: "b", appendTo: document.body }) captures r then Array.from(r.elem.querySelectorAll("input")).map(i => i.value + (i.checked ? "*" : "")) captures state -> state.join() === "a,b*,c"
+- assigning `value` moves the selection to the matching option rather than clearing it
+  - new Subject({ options: ["a", "b", "c"], value: "b", appendTo: document.body }) captures r then r.options.value = "c" then Array.from(r.elem.querySelectorAll("input")).map(i => i.value + (i.checked ? "*" : "")) captures state -> state.join() === "a,b,c*"
+- choosing an option reports that option's value, not a shared default
+  - new Subject({ options: ["a", "b", "c"], value: "b", appendTo: document.body }) captures r then r.elem.querySelectorAll("input")[0] captures first then first.checked = true then first.dispatchEvent(new Event("change", { bubbles: true })) -> r.options.value === "a"
+- an options list that is absent renders an empty group rather than throwing
+  - new Subject({ options: undefined, appendTo: document.body }) captures missing then new Subject({ options: null, appendTo: document.body }) captures empty -> missing.elem.querySelectorAll("input").length === 0 && empty.elem.querySelectorAll("input").length === 0

package/components/Router/Router.js

@@ -135,22 +135,14 @@ class Router extends Component {
 
 		if (this.options.views[route]) {
 			this.view = new this.options.views[route]({ appendTo: this.elem, ...this.parseRouteParameters() });
+		} else if (
+			this.options.defaultPath &&
+			this.options.views[this.options.defaultPath] &&
+			this.path !== this.options.defaultPath
+		) {
+			this.path = this.options.defaultPath;
 		} else if (this.options.notFound) this.view = new this.options.notFound({ appendTo: this.elem, route });
-		else if (this.options.defaultPath && this.path !== this.options.defaultPath) this.path = this.options.defaultPath;
 	}
 }
 
 export default Router;
-
-// Zero-arg scenarios for LLD verification
-export const hashStripsQueryString = () => {
-	const r = new Router({ views: { '/path': Component }, autoRender: false });
-	window.location.hash = '#/path?query=1&sort=name';
-	return r.path;
-};
-
-export const paramExtractedFromRoute = () => {
-	const r = new Router({ views: { '/users/:id': Component }, autoRender: false });
-	window.location.hash = '#/users/42';
-	return r.parseRouteParameters('/users/42')?.id;
-};

package/components/Router/Router.lld.md

@@ -6,26 +6,31 @@ Hash-based router that maps URL fragments to component classes. The design decis
 
 ## Query strings are stripped before route matching
 
-**method:** `hashStripsQueryString`
-
 - `#/path?foo=bar` matches the `/path` route; query strings are stripped before matching so callers write route patterns without accounting for query parameters
-  - hashStripsQueryString() → "/path"
+  - new Subject({ views: { "/path": null }, autoRender: false }) captures r then window.location.hash = "#/path?foo=bar" -> r.route === "/path"
 
 ## Route parameters are extracted and passed to the rendered view
 
-**method:** `paramExtractedFromRoute`
-
 - patterns like `/users/:id` match `/users/42` and produce `{ id: '42' }` for the view without any URL parsing at the view level
-  - paramExtractedFromRoute() → "42"
+  - new Subject({ views: { "/users/:id": null }, autoRender: false }) captures r then r.parseRouteParameters("/users/42") captures p -> p.id === "42"
+- a path that does not fit the pattern produces no parameters rather than partial ones
+  - new Array() captures got then (location.hash = "#/things/42") then new Subject({ views: { "/things/:id": class { constructor(o) { got.push(o.id); this.elem = document.createElement("div"); } } }, appendTo: document.body }) captures r -> r.parseRouteParameters("/things/42").id === "42" && Object.keys(r.parseRouteParameters("/nothing/here")).length === 0 && got.join() === "42"
 
 ## Same-route navigation does not rebuild the view
 
+View state is preserved across same-route navigations, so callers do not have to guard against them.
+
 - if the new hash resolves to the same route as what's currently rendered, the component skips re-render
-- this preserves view state across same-route navigations without the caller guarding against them
-  - does navigating to the currently active route leave the rendered view unchanged?
+  - new Array() captures renders then window.location.hash = "#/route-a" then new Subject({ views: { "/route-a": Object }, onRenderView: x => renders.push(x) }) captures r then r.view captures firstView then r.renderView() then r.renderView() -> renders.length === 1 && r.view === firstView
 
 ## Unmatched routes fall back rather than rendering nothing
 
-- an unmatched hash tries `defaultPath` before showing the notFound component
-- the notFound component is only shown when no fallback matches either
-  - does navigating to an unknown route eventually show the notFound component?
+- an unmatched hash tries `defaultPath` before showing the notFound component; notFound is the last resort, not the first response to a miss
+  - new Array() captures seen then window.location.hash = "#/nowhere" then new Subject({ views: { "/known": function (o) { seen.push("known"); } }, defaultPath: "/known", notFound: function (o) { seen.push("notFound"); } }) captures r then r.renderView() -> seen.includes("known") && seen.includes("notFound") === false
+
+## Where the path comes from is the only difference between the two modes
+
+`hash` mode reads the fragment and `history` mode reads the pathname; everything downstream -- matching, parameters, view construction -- is identical. Keeping the difference to one accessor is what makes the mode a deployment choice rather than a different router.
+
+- in hash mode the path is the fragment, normalised and stripped of any query; in history mode it is the pathname
+  - new Array() captures seen then (location.hash = "#/things/42") then new Subject({ views: { "/things/:id": class extends Object {} }, appendTo: document.body }) captures hashed then new Subject({ mode: "history", views: {}, appendTo: document.body }) captures historied -> hashed.path === "/things/42" && historied.path === window.location.pathname

package/components/Select/Select.js

@@ -39,8 +39,21 @@ class Select extends Input {
 					}
 				}
 
-				// Re-apply the current value - option elements may not have existed when value was processed
-				if (this.options.value !== undefined) this.elem.value = this.options.value;
+				// Re-apply the current value - option elements may not have existed when value was processed.
+				//
+				// The empty case is excluded because `value` is inherited from Input with a default of
+				// '', so by the time this runs there is no way to tell an unset value from one the
+				// caller chose. Assigning '' to a select whose options all carry real values sets
+				// selectedIndex to -1: nothing is highlighted, and `select.value` reports '' for a
+				// control the user sees as populated. Skipping leaves the platform's own selection --
+				// the first option -- which is what the control actually displays.
+				//
+				// An explicit '' is still honoured when an option carries it, since then it names a real
+				// choice rather than "no value at all".
+				const selected = this.options.value;
+				const emptyIsSelectable = () => Array.from(this.elem.options).some(option => option.value === '');
+
+				if (selected !== undefined && (selected !== '' || emptyIsSelectable())) this.elem.value = selected;
 			},
 		},
 	};
@@ -53,7 +66,13 @@ class Select extends Input {
 		// Use elem.options (HTMLOptionsCollection) - works across optgroups
 		const selected = Array.from(this.elem.options).find(({ selected }) => selected);
 
-		return selected?.value ?? selected?.label ?? selected?.textContent ?? this.elem.value;
+		if (!selected) return this.elem.value;
+
+		// option.value is never null/undefined per spec (it's the value attribute, or
+		// textContent when absent) - hasAttribute is required to actually reach the label fallback
+		if (selected.hasAttribute('value')) return selected.value;
+
+		return selected.label || selected.textContent;
 	}
 
 	/**

package/components/Select/Select.lld.md

@@ -8,13 +8,37 @@ Dropdown select that extends Input. The design decision: Select inherits Input's
 
 - `isDirty`, validations, and onChange all work the same way as Input without any Select-specific API
   - does a Select have isDirty?
-  - does a Select value change trigger onChange the same way as an Input?
+  - new Array() captures fired then new Subject({ options: ["a", "b"], onChange: () => fired.push(1) }) captures s then s.elem.value = "b" then s.elem.dispatchEvent(new Event("change", { bubbles: true })) -> fired.length === 1
 
 ## Options map in order, preserving sequence
 
+Options frequently arrive from a fetch, so the list is routinely absent on the first render. A select with nothing to show is a normal state, not an error.
+
+- an options list that is absent or not yet loaded renders an empty select rather than throwing, so a caller can pass the value straight through while it resolves
+  - new Subject({ options: undefined, appendTo: document.body }) captures missing then new Subject({ options: null, appendTo: document.body }) captures empty -> missing.elem.options.length === 0 && empty.elem.options.length === 0
+
 - items in the `options` array become select options in the same order; no automatic sorting or reindexing
-  - does the options array order match the dropdown order?
+  - new Subject({ options: ["alpha", "beta", "gamma"] }) captures s then Array.from(s.elem.querySelectorAll("option")).map(o => o.value) captures rendered -> rendered.join(",") === "alpha,beta,gamma"
+
+An entry that carries its own `options` array is a group rather than a choice, so the array is one level of nesting rather than a flat list. Grouping is presentation only -- a grouped option is still an option, and reading `value` must not care which level it came from.
+
+- an entry with a nested `options` array becomes an optgroup holding those choices; plain entries stay at the top level, and the value getter reaches a grouped option the same as an ungrouped one
+  - new Subject({ options: [{ label: "Group A", options: ["a1", "a2"] }, "loose"], appendTo: document.body }) captures s then Array.from(s.elem.children).map(c => c.tagName) captures shape then s.elem.querySelector("optgroup") captures group -> shape.join(",") === "OPTGROUP,OPTION" && group.label === "Group A" && Array.from(group.children).map(o => o.value).join(",") === "a1,a2"
+  - new Subject({ options: [{ label: "Group A", options: ["a1", "a2"] }, "loose"], appendTo: document.body }) captures s then s.value captures fromGroup then s.elem.options[2].selected = true then s.value captures fromTop -> fromGroup === "a1" && fromTop === "loose"
 
 ## The value getter returns the selected option's value, with label as fallback
 
 - `select.value` returns the option's `value` attribute; if absent it falls back to `label`, then `textContent`
+  - new Subject({ options: [{ value: "v1", label: "L1" }, { label: "L2" }, { textContent: "T3" }], appendTo: document.body }) captures s then s.elem.options[0].selected = true then s.value captures byAttr then s.elem.options[1].selected = true then s.value captures byLabel then s.elem.options[2].selected = true then s.value captures byText -> byAttr === "v1" && byLabel === "L2" && byText === "T3"
+  - new Subject({ options: [], appendTo: document.body }) captures s -> s.value === "" && s.elem.selectedIndex === -1
+
+## A select with options always reports the option it is showing
+
+`value` is inherited from Input, which defaults it to the empty string, so a caller who never mentions a value is indistinguishable from one who asked for `''`. Treating the two the same deselects every option -- the control still displays its first entry while `select.value` reports nothing, and the mismatch only surfaces when the form is read. What the getter returns has to be the option the user can see.
+
+- constructing a select with options and no explicit value reports the first option, matching what the closed control displays; an explicit value is still applied once the options exist
+  - new Subject({ options: ["alpha", "beta"], appendTo: document.body }) captures s -> s.value === "alpha" && s.elem.selectedIndex === 0
+  - new Subject({ options: [{ value: "v1", label: "L1" }, { value: "v2" }], appendTo: document.body }) captures byAttr then new Subject({ options: [{ label: "L2" }, { label: "L3" }], appendTo: document.body }) captures byLabel then new Subject({ options: [{ textContent: "T3" }, { textContent: "T4" }], appendTo: document.body }) captures byText -> byAttr.value === "v1" && byLabel.value === "L2" && byText.value === "T3"
+  - new Subject({ options: ["alpha", "beta"], value: "beta", appendTo: document.body }) captures s -> s.value === "beta" && s.elem.selectedIndex === 1
+  - new Subject({ value: "beta", options: ["alpha", "beta"], appendTo: document.body }) captures valueFirst then new Subject({ options: ["alpha", "beta"], value: "beta", appendTo: document.body }) captures optionsFirst -> valueFirst.elem.selectedIndex === 1 && optionsFirst.elem.selectedIndex === 1
+  - new Subject({ options: [{ label: "none", value: "" }, "alpha"], value: "", appendTo: document.body }) captures s -> s.value === "" && s.elem.selectedIndex === 0

package/components/Table/Table.js

@@ -17,6 +17,10 @@ import { Icon } from '../Icon';
  * @param {Function} [options.onSort] - Custom sort function, defaults to built-in sorting
  * @param {string} [options.sortProperty] - Currently sorted column key
  * @param {string} [options.sortDirection] - Sort direction ('asc' or 'desc')
+ * @param {*} [options.selection] - Caller-owned selection state. The table stores it and re-renders
+ *   when it is reassigned, but never interprets it; `dataColumn` functions read it back off
+ *   `table.options.selection` to render per-row state. Mutating a property of it deliberately does
+ *   not re-render, so toggling one row's checkbox does not rebuild the table under the pointer
  * @param {...(Component|HTMLElement|string)} children - Child elements to append
  * @returns {Table} Table component instance
  */
@@ -67,9 +71,14 @@ class Table extends Component {
 		const columns = (this.options.columns || []).map(column =>
 			typeof column === 'string' ? { key: column, content: capitalize(column) } : column,
 		);
-		const footer = this.options.footer?.map(column =>
-			typeof column === 'string' ? { content: capitalize(column) } : column,
-		);
+		// Footer entries pair with columns by key, not by declaration order - an entry may
+		// declare its own `key`; otherwise it falls back to the column at the same index, so
+		// existing footer configs that never set `key` keep working unless columns are reordered.
+		const footer = this.options.footer?.map((column, index) => {
+			const normalized = typeof column === 'string' ? { content: capitalize(column) } : column;
+
+			return { key: columns[index]?.key, ...normalized };
+		});
 
 		this._sortSubscribers?.forEach(sub => sub.destroy?.());
 		this._sortSubscribers = null;
@@ -177,10 +186,16 @@ class Table extends Component {
 		);
 
 		if (footer) {
+			const footerByKey = new Map(footer.map(footData => [footData.key, footData]));
+
 			this.tfoot.append(
 				new Component(
 					{ tag: 'tr' },
-					footer.map(footData => new Component({ tag: 'td', ...footData })),
+					columns.map(column => {
+						const { key: _footKey, ...footOptions } = footerByKey.get(column.key) || {};
+
+						return new Component({ tag: 'td', ...footOptions });
+					}),
 				),
 			);
 		}