@vanilla-bean/components 2.0.1 → 2.0.3

package/Component/observeElementConnection.js

@@ -11,12 +11,12 @@ function ensureObserver() {
 		for (const mutation of mutations) {
 			for (const node of mutation.removedNodes) {
 				for (const [target, callbacks] of registry) {
-					if (node === target || node.contains?.(target)) callbacks.onDisconnected(mutation);
+					if ((node === target || node.contains?.(target)) && !target.isConnected) callbacks.onDisconnected(mutation);
 				}
 			}
 			for (const node of mutation.addedNodes) {
 				for (const [target, callbacks] of registry) {
-					if (node === target || node.contains?.(target)) callbacks.onConnected(mutation);
+					if ((node === target || node.contains?.(target)) && target.isConnected) callbacks.onConnected(mutation);
 				}
 			}
 		}
@@ -28,7 +28,7 @@ function ensureObserver() {
 /**
  * Observe DOM connection/disconnection of an element via a shared MutationObserver.
  * All registrations share one observer; the observer is torn down when no targets remain.
- * Fires correctly when the target itself or any ancestor is moved.
+ * Fires when the target itself or any ancestor is added or removed; a move within the document is not a disconnect.
  * @param {object} config - Observer registration options
  * @param {Node} config.target - Target element to watch for add/remove
  * @param {Function} config.onConnected - Called when target is added to the document

package/Component/observeElementConnection.test.js

@@ -66,6 +66,21 @@ describe('observeElementConnection', () => {
 		handle.disconnect();
 	});
 
+	test('does not fire onDisconnected when the target moves within the document', async () => {
+		const target = document.createElement('div');
+		document.body.appendChild(target);
+		await tick();
+
+		const onDisconnected = mock();
+		const handle = observeElementConnection({ target, onConnected: mock(), onDisconnected });
+
+		document.body.appendChild(target);
+		await tick();
+
+		expect(onDisconnected).not.toHaveBeenCalled();
+		handle.disconnect();
+	});
+
 	test('does not fire after disconnect', async () => {
 		const target = document.createElement('div');
 		const onConnected = mock();

package/components/BottomSheet/BottomSheet.js

@@ -104,9 +104,15 @@ class BottomSheet extends styled(
 	}
 
 	/**
-	 * Slides the sheet out of view and calls onClose if set.
+	 * Slides the sheet out of view. Calls `onClose` only if the sheet was actually open — hiding an
+	 * already-closed sheet dismisses nothing, so there is nothing to announce.
 	 */
 	hide() {
+		// `onClose` reports a dismissal. Firing it unconditionally meant a sheet that had never been
+		// shown reported being closed, and `hide()` called twice reported it twice — so a caller
+		// hiding defensively, or wiring hide() to more than one dismissal path, got spurious closes.
+		const wasOpen = this.elem.classList.contains('open');
+
 		this.removeClass('open');
 		if (this._hideOnNavigate) {
 			window.removeEventListener('hashchange', this._hideOnNavigate);
@@ -114,7 +120,7 @@ class BottomSheet extends styled(
 			this._hideOnNavigate = null;
 			this.replaceDestroyCleanup('hideOnNavigate', () => {});
 		}
-		this.options.onClose?.();
+		if (wasOpen) this.options.onClose?.();
 	}
 
 	_initDragToClose() {

package/components/BottomSheet/BottomSheet.lld.md

@@ -2,24 +2,36 @@
 
 > ./BottomSheet.js
 
-Bottom sheet overlay that slides up from the bottom. Mounts to `document.body` by default. Drag down to dismiss; `hide()` closes it from code.
+Mobile-friendly overlay that slides up from the bottom of the screen. The design decision: dismissal has three distinct triggers -- explicit `hide()`, a drag gesture past a threshold, and navigating away -- but all three converge on the same dismissal path, so cleanup and `onClose` only need to be wired once no matter how the sheet closes.
 
 ## show() / hide() control visibility
 
 - calling `show()` slides the sheet into view; calling `hide()` slides it out
-- `onClose` fires when the sheet is dismissed (either by drag or by `hide()`)
-  - does calling hide() invoke the onClose callback?
-  - does the sheet animate out before calling onClose?
+- `onClose` fires when the sheet is dismissed (either by drag or by `hide()`); hiding a sheet that is already closed dismisses nothing and announces nothing
+  - does calling show() then hide() invoke the onClose callback?
+  - does calling hide() on an already-closed sheet leave onClose uninvoked?
+  - new Array() captures atCallback then new Subject({ appendTo: document.body, onClose: () => atCallback.push(s.elem.classList.contains("open")) }) captures s then s.show() then s.hide() -> atCallback.length === 1 && atCallback[0] === false
 
 ## Drag below the threshold dismisses the sheet
 
+**browser:** true
+
+The threshold exists so that small accidental drags do not dismiss the sheet.
+
 - a drag handle at the top of the sheet captures pointer events; dragging past a distance threshold triggers `hide()`
-- the sheet should not dismiss on small accidental drags
-  - does dragging the handle downward past the threshold dismiss the sheet?
-  - does a short drag that doesn't reach the threshold leave the sheet visible?
+  - new Subject({ appendTo: document.body }) captures s then s.show() then s.elem.classList.contains("open") captures shown then s.elem.querySelector("*") captures zone then zone.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientY: 300 })) then window.dispatchEvent(new MouseEvent("mousemove", { bubbles: true, clientY: 700 })) then window.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, clientY: 700 })) -> shown === true && s.elem.classList.contains("open") === false
+  - new Subject({ appendTo: document.body }) captures s then s.show() then s.elem.querySelector("*") captures zone then zone.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, clientY: 300 })) then window.dispatchEvent(new MouseEvent("mousemove", { bubbles: true, clientY: 304 })) then window.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, clientY: 304 })) -> s.elem.classList.contains("open") === true
 
 ## Navigating away (hashchange) closes the sheet
 
-- the sheet registers a one-time `hashchange` listener on `show()` and removes it on `hide()`
-- the sheet doesn't outlive navigation
-  - does navigating to a new hash while the sheet is open dismiss it?
+The sheet does not outlive the navigation that moved away from it.
+
+- a sheet that is showing is dismissed when the location changes; a sheet that is already hidden is unaffected by navigation
+  - new Subject({ appendTo: document.body }) captures s then s.show() then s.elem.classList.contains("open") captures shown then location.hash = "#/elsewhere" then window.dispatchEvent(new HashChangeEvent("hashchange", { oldURL: "", newURL: String(location.href) })) -> shown === true && s.elem.classList.contains("open") === false
+
+## A sheet attaches to the page and offers its content region
+
+An overlay that slides over everything belongs to the page, not to whatever component happened to construct it, so `document.body` is the default parent rather than a required option. Content goes in the sheet's own region rather than against the frame, which is what keeps the drag handle and the content from sharing a parent.
+
+- a sheet with no explicit parent attaches to the document body and exposes the region its content belongs in
+  - new Subject({}) captures s -> s.elem.parentElement === document.body && !!s.body && s.body.elem.tagName === "DIV"

package/components/Button/Button.lld.md

@@ -13,9 +13,17 @@ Activatable element that unifies pointer and keyboard interaction under one hand
 ## Caller-provided onKeyUp is preserved alongside activation logic
 
 - a caller-provided `onKeyUp` runs alongside the built-in keyboard activation; registering both handlers does not suppress either
-  - does providing a custom onKeyUp still trigger onPointerPress on Space/Enter?
+  - new Array() captures calls then new Subject({ onPointerPress: () => calls.push("press"), onKeyUp: () => calls.push("custom") }) captures b then document.body.append(b.elem) then b.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "Enter", code: "Enter", bubbles: true })) -> calls.includes("press") && calls.includes("custom")
 
 ## Tooltip is automatic - no setup beyond the tooltip option
 
-- Button extends TooltipWrapper; a `tooltip` option produces tooltip behavior with no additional wiring
-  - does a Button with a tooltip option show a tooltip on hover?
+- a `tooltip` option produces tooltip behaviour with no additional wiring at the call site
+  - new Subject({ tooltip: "Save changes", appendTo: document.body }) captures b then b.elem.querySelector("[popover]") captures tip -> !!tip && tip.textContent === "Save changes"
+  - new Subject({ tooltip: "Save changes", appendTo: document.body }) captures b then b.elem.querySelector("[popover]") captures tip then tip.style.display captures before then b.elem.dispatchEvent(new PointerEvent("pointerover", { bubbles: true, clientX: 10, clientY: 10 })) then await new Promise(r => setTimeout(r, 760)) -> before === "" && tip.style.display === "block"
+
+## Only Space and Enter activate; every other key passes through
+
+Keyboard activation is deliberately two keys, not "any key". A button that fired on arrows or Tab would steal navigation from the page around it, which is the failure that makes keyboard users avoid custom controls.
+
+- Space and Enter invoke `onPointerPress`; other keys leave it uninvoked
+  - new Array() captures fired then new Subject({ onPointerPress: e => fired.push(e.code), appendTo: document.body }) captures b then ["Enter", "Space", "KeyA", "Tab", "Escape"].forEach(code => b.elem.dispatchEvent(new KeyboardEvent("keyup", { key: code, code, bubbles: true }))) -> fired.join() === "Enter,Space"

package/components/Calendar/Calendar.js

@@ -44,7 +44,14 @@ const StyledComponent = styled(
 				& div.event {
 					position: absolute;
 					pointer-events: all;
-					width: 100%;
+					/* Offsets, not a width. Overlap resolution assigns left/right percentages so
+					   simultaneous events share the row, and an explicit width over-constrained the
+					   box against them — 'right' was dropped, so every event rendered full-width and
+					   sat on top of its neighbours. Defaulting both offsets to 0 keeps a lone event
+					   spanning the container, which is what the width was for, while letting the
+					   assigned percentages actually narrow the box. */
+					left: 0;
+					right: 0;
 					text-indent: 6px;
 				}
 			}
@@ -246,6 +253,7 @@ export const MONTHS = [
  * @param {number} [options.year] - Initial year to display, defaults to current year
  * @param {number} [options.month] - Initial month to display (0-11), defaults to current month
  * @param {number} [options.day] - Initial day to display, defaults to current day
+ * @param {number} [options.weekday] - Day-of-week index (0-6, Sunday first) as returned by Date.getDay(); set from the selected date and read by the week view
  * @param {Array<object>} [options.events=[]] - Calendar events array, automatically converted to CalendarEvent instances
  * @param {Array<string>} [options.views] - Available view modes for toolbar
  * @param {boolean} [options.display24h] - Whether to display time in 24-hour format in day view
@@ -377,6 +385,11 @@ class Calendar extends StyledComponent {
 			event.ratio = 100;
 			elem.style.left = '0';
 
+			// Which gap slot the event starts in (fractional - a start time that falls mid-slot
+			// spills into the next one below), and how many slots its duration spans.
+			event.gapCell = (event.hour * 60 + event.minute) / minGap;
+			event.gapCount = Math.max(1, Math.ceil((event.duration || minGap) / minGap));
+
 			let totalGaps = event.gapCount;
 
 			if (Math.floor(event.gapCell) !== event.gapCell) ++totalGaps;
@@ -557,7 +570,19 @@ class Calendar extends StyledComponent {
 	}
 
 	adjustDateToView() {
-		if (this.options.view !== 'week' || this.options.weekday >= this.options.day || this.options.day > 8) return;
+		// Week view anchors on the month the week *starts* in, so a week spanning a month boundary is
+		// rendered from the earlier month. The week starts in the previous month exactly when its
+		// Sunday falls before the 1st -- `day - weekday < 1`. The guard used to ask whether
+		// `weekday < day`, which holds for most of any month's first week, so an ordinary date like
+		// Tuesday the 4th was pulled back a month and the calendar opened on the wrong week entirely.
+		// Derived, not read from `options.weekday`: that option is only populated by `setDate()`, so a
+		// caller who constructs with an explicit year/month/day leaves it undefined and any arithmetic
+		// on it yields NaN -- which compares false against everything and silently drops through.
+		if (this.options.view !== 'week') return;
+
+		const weekday = new Date(this.options.year, this.options.month, this.options.day).getDay();
+
+		if (this.options.day - weekday >= 1) return;
 
 		let { year, month } = this.options;
 		--month;
@@ -790,11 +815,3 @@ class Calendar extends StyledComponent {
 }
 
 export default Calendar;
-
-// Zero-arg scenarios for LLD verification
-export const navigateBackFromJanuary = () => {
-	const c = new Calendar({ view: 'month', year: 2024, month: 0, autoRender: false });
-	c.render();
-	c.previous();
-	return { month: c.options.month, year: c.options.year };
-};

package/components/Calendar/Calendar.lld.md

@@ -6,17 +6,53 @@ Multi-view calendar that renders the same event data differently depending on sc
 
 ## Switching view re-renders layout without carrying forward view-specific state
 
-- day, week, and month views have structurally different DOM; changing `view` produces a fresh render so residual state from the previous layout cannot persist
-  - does switching from month to day view reflect the events in the new layout?
+- changing `view` produces a fresh render, so no residual state from the previous layout persists into the new one
+  - new Subject({ view: "month", appendTo: document.body }) captures c then c.elem.querySelectorAll("td").length captures monthCells then c.options.view = "week" then await new Promise(r => setTimeout(r, 20)) -> monthCells === 49 && c.elem.querySelectorAll("td").length === 0 && c.elem.classList.contains("week") && !c.elem.classList.contains("month")
+  - new Subject({ view: "month", events: [{ at: new Date(), label: "Standup" }], appendTo: document.body }) captures c then (c.elem.textContent.match(/Standup/g) ?? []).length captures inMonth then c.options.view = "day" then await new Promise(r => setTimeout(r, 20)) -> inMonth === 1 && (c.elem.textContent.match(/Standup/g) ?? []).length === 1
+
+## Times read as clock times, and the current day is findable
+
+A 12-hour clock has no hour zero, so midnight is `12:00 AM`; `display24h` opts into the other convention. Whichever is in use, the cell for today is marked so the view has an anchor the reader can find without reading dates.
+
+- in 12-hour mode midnight reads as 12, not 0; `display24h` switches to the 24-hour convention
+  - new Subject({ view: "day", year: 2026, month: 0, day: 15, appendTo: document.body }) captures twelve then Array.from(twelve.elem.querySelectorAll("*")).map(e => e.childNodes.length === 1 ? e.textContent : "").filter(t => /^\d{1,2}:\d{2}\s?(AM|PM)$/.test(t)) captures labels then new Subject({ view: "day", display24h: true, year: 2026, month: 0, day: 15, appendTo: document.body }) captures full then Array.from(full.elem.querySelectorAll("*")).map(e => e.childNodes.length === 1 ? e.textContent : "").filter(t => /^\d{1,2}:\d{2}/.test(t)) captures labels24 -> labels[0] === "12:00 AM" && !labels.some(l => l.startsWith("0:")) && labels24[0].startsWith("0:00")
+- the cell for the current date carries a marker the other cells do not
+  - new Subject({ view: "week", appendTo: document.body }) captures c -> c.elem.querySelectorAll(".today").length === 1
+- view and date methods return the calendar so calls can be chained
+  - new Subject({ appendTo: document.body }) captures c then c.setView("week") captures returned -> returned === c
+
+## Date input is accepted in whatever form the caller has it
+
+Dates arrive from JSON, from attributes, from other components -- as strings as often as `Date` objects. Queries coerce rather than demanding the caller convert first. Option changes made before the calendar has rendered are recorded without forcing a render, so construction order does not matter.
+
+- `eventsAt` accepts a date string as readily as a `Date`
+  - new Subject({ view: "month", year: 2026, month: 0, day: 15, events: [{ at: new Date(2026, 0, 15, 9, 0, 0), label: "Standup" }], appendTo: document.body }) captures c then c.eventsAt(new Date(2026, 0, 15)) captures byDate then c.eventsAt("2026-01-15T12:00:00") captures byString -> byDate.length === 1 && byString.length === 1 && byString[0].label === "Standup"
+- setting `view` before the calendar has rendered records the value without rendering; the first render then uses it
+  - new Subject({ autoRender: false, view: "month" }) captures c then c.options.view = "week" then c.elem.childNodes.length captures beforeRender then c.render() -> beforeRender === 0 && c.options.view === "week" && c.elem.classList.contains("week")
 
 ## Day view resolves overlap so simultaneous events don't hide each other
 
+**browser:** true
+
 - when events occupy the same time slot they share the horizontal space proportionally; events are never stacked invisibly
-  - do two events at the same time render side by side rather than overlapping?
+  - new Subject({ appendTo: document.body, view: "day", year: 2026, month: 0, day: 15, events: [{ at: new Date(2026, 0, 15, 10, 0, 0), duration: 60, label: "one" }, { at: new Date(2026, 0, 15, 10, 0, 0), duration: 60, label: "two" }] }) captures c then await new Promise(r => setTimeout(r, 150)) then Array.from(c.elem.querySelectorAll("div.event")).map(e => e.getBoundingClientRect()) captures boxes -> boxes.length === 2 && boxes[0].width > 0 && boxes[1].width > 0 && boxes[0].right <= boxes[1].left
 
-## Date navigation handles year boundaries correctly
+## Week view anchors on the month the week starts in
+
+A week that straddles a month boundary belongs to the month it began in, so month-by-month navigation lands on whole weeks instead of splitting one across two screens. The re-anchoring is the exception, not the rule: a week sitting entirely inside its month must be left where it is.
 
-**method:** `navigateBackFromJanuary`
+- the week shown is the one containing the target date; only a week whose first day falls in the previous month re-anchors there
+  - new Subject({ view: "month", appendTo: document.body }) captures c then c.setDate(2026, 7, 4) then c.setView("week") -> c.options.month === 7 && c.options.day === 4 && c.elem.textContent.includes("August 2nd - 8th, 2026")
+  - new Subject({ view: "month", appendTo: document.body }) captures c then c.setDate(2026, 7, 1) then c.setView("week") -> c.options.month === 6 && c.options.day === 31 && c.elem.textContent.includes("July 26th - August 1st, 2026")
+
+## Date navigation handles year boundaries correctly
 
 - navigating backward from January produces December of the prior year; the calendar does not produce invalid dates at month boundaries
-  - navigateBackFromJanuary() captures result → result.month === 11
+  - new Subject({ year: 2026, month: 0, day: 15, view: "month" }) captures c then c.previous() -> c.options.month === 11 && c.options.year === 2025
+
+## An event only gives up horizontal space to events it actually overlaps
+
+Sharing the row is a cost paid per collision, not per day: two events at the same hour split the width between them, while an event alone in its hour keeps the full width. Charging every event for the busiest moment of the day would leave most of the column empty.
+
+- events that collide are offset from each other; an event with no collision is not offset at all
+  - new Subject({ view: "day", year: 2026, month: 0, day: 15, events: [{ at: new Date(2026, 0, 15, 10, 0, 0), duration: 60, label: "one" }, { at: new Date(2026, 0, 15, 10, 0, 0), duration: 60, label: "two" }, { at: new Date(2026, 0, 15, 14, 0, 0), duration: 60, label: "three" }], appendTo: document.body }) captures c then Array.from(c.elem.querySelectorAll("div.event")).map(e => e.style.left) captures lefts -> lefts.length === 3 && lefts[0] !== lefts[1] && lefts[2] === "0px"

package/components/Calendar/Toolbar.js

@@ -24,6 +24,22 @@ const Right = styled(
 
 export const VIEWS = Object.freeze(['day', 'week', 'month']);
 
+/**
+ * Navigation and view-switching header for a Calendar.
+ *
+ * Renders previous/today/next controls on the left, the calendar's title in the middle, and one
+ * button per available view on the right. The toolbar holds no state of its own — every control
+ * calls straight through to the calendar it was given.
+ * @param {object} [options={}] - Toolbar configuration options
+ * @param {Calendar} options.calendar - The calendar these controls drive; its `previous`, `today`,
+ *   `next` and `setView` methods are called from the buttons. Required — the toolbar constructs
+ *   without it, but every control throws on press
+ * @param {Array<string>} [options.views=VIEWS] - View names to offer, one button each
+ * @param {('day'|'week'|'month')} [options.view] - The currently active view; assigning it moves the
+ *   `pressed` class onto the matching button. Set by the calendar, not usually by a caller
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Toolbar} Toolbar component instance
+ */
 class Toolbar extends Component {
 	static schema = {
 		views: { default: VIEWS },

package/components/Code/Code.lld.md

@@ -6,9 +6,9 @@ Code display that automatically promotes from inline to block when the content s
 
 ## Multiline content renders as a block element without the caller specifying it
 
-- the component detects newlines at render time and promotes accordingly
+- content spanning multiple lines renders as a block element and single-line content renders inline; the caller passes code and never chooses between the two
   - does code with newlines render as a block (pre) rather than an inline element?
-  - does single-line code render inline?
+  - new Subject({ code: "one line", multiline: "auto", copyButton: false, language: "javascript" }) captures c -> c.elem.tagName === "CODE"
 
 ## Language class enables syntax highlighting libraries to identify the element
 
@@ -18,4 +18,4 @@ Code display that automatically promotes from inline to block when the content s
 ## Copy confirms success visually - clipboard writes can fail silently
 
 - the copy button shows a notification on success so the user knows the copy worked rather than discovering it failed on paste
-  - does a successful copy show the user a confirmation?
+  - new Subject({ code: "a\nb", copyButton: true, appendTo: document.body }) captures c then Object.defineProperty(window, "isSecureContext", { value: true, configurable: true }) then Object.defineProperty(navigator, "clipboard", { value: { writeText: () => {} }, configurable: true }) then c.elem.querySelector("button") captures btn then btn.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then btn.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) then await new Promise(r => setTimeout(r, 40)) -> document.body.textContent.includes("Copied text to clipboard!")

package/components/ColorPicker/ColorPicker.lld.md

@@ -7,15 +7,38 @@ HSL-based color picker where hue and saturation/lightness are controlled by sepa
 ## Multiple input formats are accepted without the caller normalizing first
 
 - color strings, color objects, and the sentinel 'random' all produce a valid picker state without error
-  - does initializing with a color string produce a valid picker state?
-  - does initializing with value 'random' produce a valid picker state?
+  - new Subject({ value: "#3366cc" }) captures p -> CSS.supports("color", String(p.options.value)) && p.hue >= 0
+  - new Subject({ value: "random" }) captures p -> CSS.supports("color", String(p.options.value)) && String(p.options.value) !== "random"
 
 ## Dragging outside the picker area does not produce out-of-range colors
 
+**browser:** true
+
 - the position is clamped to the picker's bounds regardless of where the pointer goes; callers receive valid color values even during aggressive drag behavior
-  - does dragging well outside the saturation area still produce a valid color value?
+  - new Subject({ appendTo: document.body, value: "#3366cc" }) captures p then await new Promise(r => setTimeout(r, 80)) then p.pickerArea.elem captures area then area.getBoundingClientRect() captures box then area.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: box.left + 5, clientY: box.top + 5 })) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: box.right + 4000, clientY: box.bottom + 4000 })) then await new Promise(r => setTimeout(r, 140)) then p.pickerIndicator.elem.getBoundingClientRect() captures ind -> ind.top - box.top >= box.height - 10 && CSS.supports("color", String(p.options.value))
 
 ## Hue and saturation areas have independent pointer tracking
 
+**browser:** true
+
 - interaction with the hue bar does not affect the saturation/lightness position and vice versa
-  - does adjusting the hue leave the saturation value unchanged?
+  - new Subject({ appendTo: document.body, value: "#3366cc" }) captures p then await new Promise(r => setTimeout(r, 100)) then p.pickerIndicator.elem.getBoundingClientRect() captures svBefore then p.hue captures hueBefore then p.hueArea.elem.getBoundingClientRect() captures hb then p.hueArea.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: hb.left + 20, clientY: hb.top + 15 })) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: hb.left + hb.width * 0.4, clientY: hb.top + 15 })) then await new Promise(r => setTimeout(r, 100)) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: hb.left + hb.width * 0.7, clientY: hb.top + 15 })) then await new Promise(r => setTimeout(r, 100)) then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: hb.left + hb.width * 0.7, clientY: hb.top + 15 })) then await new Promise(r => setTimeout(r, 100)) then p.pickerIndicator.elem.getBoundingClientRect() captures svAfter -> Math.round(p.hue) !== Math.round(hueBefore) && Math.abs(svAfter.left - svBefore.left) < 1 && Math.abs(svAfter.top - svBefore.top) < 1
+  - new Subject({ appendTo: document.body, value: "#3366cc" }) captures p then await new Promise(r => setTimeout(r, 100)) then p.pickerIndicator.elem.getBoundingClientRect() captures svBefore then p.hue captures hueBefore then p.pickerArea.elem.getBoundingClientRect() captures pb then p.pickerArea.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: pb.left + 10, clientY: pb.top + 10 })) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: pb.left + pb.width * 0.7, clientY: pb.top + pb.height * 0.7 })) then await new Promise(r => setTimeout(r, 100)) then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: pb.left + pb.width * 0.7, clientY: pb.top + pb.height * 0.7 })) then await new Promise(r => setTimeout(r, 100)) then p.pickerIndicator.elem.getBoundingClientRect() captures svAfter -> Math.round(p.hue) === Math.round(hueBefore) && Math.abs(svAfter.top - svBefore.top) > 1
+
+## Hue is remembered when the colour alone cannot carry it
+
+A colour string does not always determine a slider position. Fully desaturated colours have no hue to read back, and the conversion wraps 360 to 0 -- the same red, but the opposite end of the slider. In both cases the picker keeps the hue it already had, so the handle stays where the user put it. An empty value is not a colour at all and changes nothing.
+
+- a colour that reports hue 0 while the slider sits near 360 keeps its position rather than jumping to the other end
+  - new Subject({ value: "hsl(355, 80%, 50%)", appendTo: document.body }) captures p then Math.round(p.hue) captures before then p.options.value = "hsl(0, 80%, 50%)" -> before === 355 && Math.round(p.hue) === 355
+- assigning an empty value leaves the picker's state as it was
+  - new Subject({ value: "#3366cc", appendTo: document.body }) captures p then Math.round(p.hue) captures hueBefore then p.elem.style.backgroundColor captures bgBefore then p.options.value = "" -> hueBefore === 220 && Math.round(p.hue) === 220 && p.elem.style.backgroundColor === bgBefore
+
+## The `random` swatch shows that it is a choice, not a colour
+
+Every other swatch can paint itself with the colour it selects. `random` has no colour to show, so painting it any single colour would misrepresent what pressing it does -- it carries the rainbow treatment instead.
+
+- a `random` entry renders as the rainbow swatch while ordinary entries paint their own colour
+  - new Subject({ swatches: ["#ff0000", "random"], appendTo: document.body }) captures p then Array.from(p.elem.querySelectorAll("*")) captures parts -> parts.filter(e => e.className.includes("rainbow")).length === 1 && parts.some(e => e.style.backgroundColor !== "" && !e.className.includes("rainbow"))
+- the `random` swatch is left unpainted so the rainbow treatment shows through; a colour swatch paints itself with its own colour
+  - new Subject({ swatches: ["#ff0000", "random"], appendTo: document.body }) captures p then Array.from(p.elem.querySelectorAll("*")) captures parts then parts.filter(e => e.className.includes("rainbow")) captures rainbow -> rainbow.length === 1 && rainbow[0].style.backgroundColor === "" && parts.some(e => !e.className.includes("rainbow") && (e.style.backgroundColor === "#ff0000" || e.style.backgroundColor === "rgb(255, 0, 0)"))

package/components/Dialog/Dialog.lld.md

@@ -18,3 +18,17 @@ Native `<dialog>` element wrapper. The decision to use the native element rather
 
 - the structural elements are created once in `build()` and persist across option updates; assigning a new `header` value changes the header's content, not the dialog's structure
   - does updating the header option change the header's content without replacing the dialog structure?
+
+## Buttons are declared in the shorthand that fits
+
+A dialog's buttons are usually just labels, so a string is enough; a button that needs more than a label carries its own options object. Both forms sit in the same array rather than in separate options.
+
+- a button entry may be a label string or an options object, and both render as buttons in order
+  - new Subject({ buttons: ["OK", { textContent: "Cancel", addClass: "cancel" }], appendTo: document.body }) captures d then Array.from(d.elem.querySelectorAll("button")) captures btns -> btns.map(b => b.textContent).join() === "OK,Cancel" && btns[1].classList.contains("cancel")
+- a dialog exposes the region its content belongs in, so callers append there rather than to the frame
+  - new Subject({ appendTo: document.body }) captures d -> !!d.body && d.body.elem.tagName === "DIV"
+
+- a dialog with no explicit parent attaches to the document body, since a modal belongs to the page rather than to its opener
+  - new Subject({}) captures d -> d.elem.parentElement === document.body
+- a numeric `openOnRender` is the delay in milliseconds; `true` takes the small default instead of waiting
+  - new Subject({ openOnRender: 400 }) captures slow then new Subject({ openOnRender: true }) captures quick then await new Promise(r => setTimeout(r, 120)) then slow.elem.open captures slowEarly then quick.elem.open captures quickEarly then await new Promise(r => setTimeout(r, 400)) -> slowEarly === false && quickEarly === true && slow.elem.open === true

package/components/Form/Form.lld.md

@@ -7,15 +7,45 @@ Declarative form from an array of input configurations. The key design decision
 ## Label text falls back to the field key - no separate label required for obvious fields
 
 - if an input config omits `label`, the key name becomes the label
-  - does an input with no label option display the key name as its label?
+  - new Subject({ inputs: [{ key: "emailAddress" }], appendTo: document.body }) captures f -> f.elem.querySelector("label").textContent.toLowerCase().replace(/\s/g, "") === "emailaddress"
 
 ## hasErrors validates all inputs simultaneously and returns a boolean
 
 - `hasErrors()` runs all validations and returns true if any failed, false if all passed; false means submittable
   - does hasErrors return false when all inputs are valid?
-  - does hasErrors return true when an input's validation fails?
+  - new Subject({ inputs: [{ key: "name", validations: [[v => !!v, "required"]] }], appendTo: document.body }) captures f -> f.hasErrors() === true
 
 ## Form data is live - changes are visible before any submit action
 
 - each input's value feeds the shared `data` context as it changes
-  - does typing in an input field update the form's data context before any submit?
+  - new Subject({ inputs: [{ key: "name" }], appendTo: document.body }) captures f then f.elem.querySelector("input") captures input then input.value = "typed" then input.dispatchEvent(new Event("change", { bubbles: true })) -> f.options.data.name === "typed"
+
+## A conditional field is absent until its condition holds, and so are its rules
+
+A field that does not apply yet must not block submission, so hiding a field and excluding it from validation are the same decision rather than two -- otherwise a form becomes unsubmittable because of a rule on a question nobody was asked. Conditions are re-evaluated whenever form data changes, not only at build.
+
+- a field whose condition is unmet is hidden and its validation is not enforced; satisfying the condition reveals it and its rules start to apply
+  - new Subject({ inputs: [{ key: "wantsPet", type: "checkbox", label: "Wants pet" }, { key: "petName", label: "Pet name", condition: d => d.wantsPet, validate: v => (v ? undefined : "required") }], appendTo: document.body }) captures f then f.hasErrors() captures errorsWhileHidden then Array.from(f.elem.querySelectorAll("label")).map(l => l.parentElement.style.display).join() captures displayWhileHidden then f.options.data.wantsPet = true then await new Promise(r => setTimeout(r, 80)) -> errorsWhileHidden === false && displayWhileHidden === ",none" && Array.from(f.elem.querySelectorAll("label")).map(l => l.parentElement.style.display).join() === "," && f.hasErrors() === true
+
+## A field that becomes available is announced, not just shown
+
+A field appearing partway down a form is easy to miss and impossible to see for a screen reader user, who has already read past that point. The form says which fields became available rather than leaving the change silent.
+
+- revealing a conditional field announces it by name
+  - new Subject({ inputs: [{ key: "wantsPet", type: "checkbox", label: "Wants pet" }, { key: "petName", label: "Pet name", condition: d => d.wantsPet, validate: v => (v ? undefined : "required") }], appendTo: document.body }) captures f then f.options.data.wantsPet = true then await new Promise(r => setTimeout(r, 80)) -> f._announcer.textContent === "Pet name now available"
+
+## A checkbox is labelled beside itself, not above
+
+A checkbox is narrow and its label reads as a sentence with it, so the label sits inline; every other field takes the default stacked arrangement. The form decides this from the field's type rather than asking the caller to specify layout per field.
+
+- a checkbox field's label is laid out inline while other fields keep the default variant
+  - new Subject({ inputs: [{ key: "wantsPet", type: "checkbox", label: "Wants pet" }, { key: "petName", label: "Pet name", condition: d => d.wantsPet, validate: v => (v ? undefined : "required") }], appendTo: document.body }) captures f then Array.from(f.elem.querySelectorAll("label")).map(l => l.parentElement.className.includes("variant-inline")) captures inline -> inline[0] === true && inline[1] === false
+
+## Reassigning `inputs` rebuilds the fields around the data that is already there
+
+A form whose field list changes -- a step added, a section swapped -- must not discard what the user has already typed, so the rebuild replaces the fields while the data store survives it. The listener that watches data for conditions is only attached when there is a condition to evaluate, so a form without any adds no subscription to clean up.
+
+- assigning a new `inputs` list renders the new fields and keeps the values already collected
+  - new Subject({ inputs: [{ key: "a", label: "A" }], appendTo: document.body }) captures f then f.options.data.a = "kept" then Array.from(f.elem.querySelectorAll("label")).length captures beforeCount then f.options.inputs = [{ key: "a", label: "A" }, { key: "b", label: "B" }] then await new Promise(r => setTimeout(r, 40)) -> beforeCount === 1 && f.elem.querySelectorAll("label").length === 2 && f.options.data.a === "kept"
+- a form with no conditional fields registers no data subscription; one with them does
+  - new Subject({ inputs: [{ key: "x", label: "X" }], appendTo: document.body }) captures plain then new Subject({ inputs: [{ key: "x", label: "X" }, { key: "y", label: "Y", condition: d => d.x }], appendTo: document.body }) captures conditional -> !plain.cleanup.conditions && !!conditional.cleanup.conditions

package/components/Icon/Icon.js

@@ -7,7 +7,8 @@ import { Component } from '../../Component';
  * Handles class management for dynamic icon changes and supports all FontAwesome icon variants.
  * @param {object} [options={}] - Icon configuration options
  * @param {string} [options.icon] - FontAwesome icon name (without 'fa-' prefix)
- * @param {string} [options.animation] - FontAwesome animation name (without 'fa-' prefix)
+ * @param {string} [options.animation] - FontAwesome animation name (without 'fa-' prefix), run on the whole element
+ * @param {string} [options.iconAnimation] - FontAwesome animation name (without 'fa-' prefix), run on the glyph alone
  * @param {string} [options.content] - Text content to display alongside icon
  * @param {string} [options.textContent] - Alternative text content property
  * @param {...(Component|HTMLElement|string)} children - Child elements to append
@@ -25,6 +26,11 @@ export default class Icon extends Component {
 				this._refreshIcon();
 			},
 		},
+		iconAnimation: {
+			set() {
+				this._refreshIcon();
+			},
+		},
 		content: {
 			set(value, next) {
 				next(value);
@@ -41,8 +47,9 @@ export default class Icon extends Component {
 
 	_refreshIcon() {
 		this.removeClass(/\bfa-\S+\b/g);
+		this.removeClass(/\bicon-animation-\S+\b/g);
 
-		const { icon, animation, content, textContent } = this.options;
+		const { icon, animation, iconAnimation, content, textContent } = this.options;
 
 		if (icon || animation) {
 			this.addClass(
@@ -51,8 +58,22 @@ export default class Icon extends Component {
 			);
 		}
 
+		// A FontAwesome animation class animates whatever element carries it. On a bare Icon the
+		// element and the glyph are the same box, so that reads correctly; on a subclass with a
+		// label — Button, Link — it takes the whole control with it. iconAnimation is the same set
+		// of animations aimed at the :before that draws the glyph, so the two are separable.
+		if (iconAnimation) this.addClass(`icon-animation-${iconAnimation}`);
+
 		const interactive = ['button', 'a', 'input', 'select', 'textarea'].includes(this.elem.tagName.toLowerCase());
-		const labeled = this.elem.hasAttribute('aria-label') || this.elem.hasAttribute('aria-labelledby');
+		// The options are consulted as well as the element. This runs while options are still being
+		// applied, so a caller-supplied `aria-label` is not on the element yet -- reading only the
+		// element concluded the icon was unlabelled and hid it, leaving an icon carrying both a label
+		// and `aria-hidden="true"`, which is the one combination that helps nobody.
+		const labeled =
+			this.elem.hasAttribute('aria-label') ||
+			this.elem.hasAttribute('aria-labelledby') ||
+			this.options['aria-label'] !== undefined ||
+			this.options['aria-labelledby'] !== undefined;
 		if (!interactive && !content && !textContent && !labeled) {
 			this.elem.setAttribute('aria-hidden', 'true');
 		} else {

package/components/Icon/Icon.lld.md

@@ -12,10 +12,28 @@ FontAwesome icon wrapper that manages FA class state as options rather than raw
 ## Icon-only and icon-with-text render differently without the caller specifying which mode
 
 - when there is no text content, the element receives the `icon` class, which CSS uses for icon-only layout; when text accompanies the icon, that class is absent
-  - does an Icon constructed without text receive the icon-only class?
-  - does an Icon constructed with text not receive the icon-only class?
+  - new Subject({ icon: "star" }) captures i -> i.elem.classList.contains("icon") === true
+  - new Subject({ icon: "star", textContent: "hi" }) captures i -> i.elem.classList.contains("icon") === false
 
 ## Animation and icon are independent options that compose
 
 - setting `animation` applies an animation class independently of `icon`; an Icon with both options active carries both classes simultaneously; they do not interfere
-  - does an Icon with both icon and animation options active carry both classes at the same time?
+  - new Subject({ icon: "star", animation: "spin" }) captures i -> i.elem.classList.contains("fa-star") && i.elem.classList.contains("fa-spin")
+
+## Animating the glyph is a separate choice from animating the element
+
+A FontAwesome animation class animates whatever element carries it. On a bare Icon that reads correctly, because the element and the glyph are the same box. On a subclass that also renders a label (Button, Link) it takes the whole control with it, background and text included, which is rarely what a caller asking for a spinner meant. `animation` keeps that element-level behavior; `iconAnimation` runs the same set of animations against the `:before` that draws the glyph. The two are independent, so a caller can run either or both.
+
+- setting `iconAnimation` never applies the element-level FA animation class, and setting `animation` never applies the glyph one
+  - new Subject({ icon: "spinner", iconAnimation: "spin" }) captures i -> i.elem.classList.contains("icon-animation-spin") && !i.elem.classList.contains("fa-spin")
+  - new Subject({ icon: "spinner", animation: "beat", iconAnimation: "spin" }) captures i -> i.elem.classList.contains("fa-beat") && i.elem.classList.contains("icon-animation-spin")
+
+- an icon animation decorates the glyph and says nothing about layout; it never makes the element icon-only
+  - new Subject({ icon: "spinner", iconAnimation: "spin", textContent: "Saving" }) captures i -> i.elem.classList.contains("icon") === false
+
+## A decorative icon is hidden from assistive technology; a meaningful one is not
+
+An icon with nothing but a glyph carries no information a screen reader can convey, and announcing its class name is worse than silence. An icon that has text beside it, carries its own label, or is itself the control is content, and must stay announceable.
+
+- an icon with no text, no label and no interactive role is marked `aria-hidden`; text, a label, or an interactive tag each keep it announced
+  - new Subject({ icon: "star", appendTo: document.body }) captures bare then new Subject({ icon: "star", textContent: "Save", appendTo: document.body }) captures withText then new Subject({ icon: "star", "aria-label": "Save", appendTo: document.body }) captures labelled then new Subject({ icon: "star", tag: "button", appendTo: document.body }) captures control -> bare.elem.getAttribute("aria-hidden") === "true" && withText.elem.getAttribute("aria-hidden") === null && labelled.elem.getAttribute("aria-hidden") === null && control.elem.getAttribute("aria-hidden") === null

package/components/Input/Input.lld.md

@@ -7,22 +7,46 @@ Input element that infers its type from the value it receives rather than requir
 ## Type is communicated by the value, not by a separate option
 
 - callers pass a value; the input determines its type from that value's type
-  - does a number value produce an input that accepts numeric entry?
-  - does a boolean value produce an input that represents a checked/unchecked state?
+  - new Subject({ value: 7 }) captures i -> i.elem.type === "number"
+  - new Subject({ value: true }) captures i -> i.elem.type === "checkbox"
 
 ## isDirty reflects whether the value has changed from its initial state
 
 - the initial value is recorded at construction; `isDirty` answers "has the user changed this?" without external tracking
   - does isDirty return false when the value matches the initial value?
-  - does isDirty return true after the value has been changed?
+  - new Subject({ value: "start" }) captures i then i.isDirty captures before then i.options.value = "changed" -> before === false && i.isDirty === true
 
 ## Validation errors are surfaced as element state, not return values
 
 - when a validation fails, the element enters an error state that CSS can target; passing clears it
-  - does a failing validation leave the input in an error state?
-  - does a passing validation clear the error state?
+  - new Subject({ value: "", validations: [[v => !!v, "required"]], appendTo: document.body }) captures i then i.validate() -> i.elem.classList.contains("validation-errors")
+  - new Subject({ value: "", validations: [[v => !!v, "required"]], appendTo: document.body }) captures i then i.validate() then i.options.value = "filled" then i.validate() -> i.elem.classList.contains("validation-errors") === false
 
 ## Textarea height follows content automatically
 
+**browser:** true
+
 - when `tag: 'textarea'`, the element resizes to fit its content without the caller managing height
-  - does a textarea grow taller when its content exceeds its current height?
+  - new Subject({ tag: "textarea", appendTo: document.body, value: "one line" }) captures i then i.elem.offsetHeight captures before then i.elem.value = "a\nb\nc\nd\ne\nf\ng\nh" then i.elem.dispatchEvent(new Event("input", { bubbles: true })) then await new Promise(r => setTimeout(r, 60)) -> i.elem.offsetHeight > before
+
+## Sizing and checkbox state read from the same `value`/`height` options
+
+`height` is a number when the caller is thinking in rows and a string when they are thinking in CSS, so the number is interpreted as text rows and anything else is passed to the style as written. A checkbox has no useful text value either, so for that type `value` drives the checked state instead.
+
+- a numeric `height` is interpreted as rows of text; a string is used as the CSS length verbatim
+  - new Subject({ tag: "textarea", height: 3, appendTo: document.body }) captures rows then new Subject({ tag: "textarea", height: "40px", appendTo: document.body }) captures css -> rows.elem.style.height === "4em" && css.elem.style.height === "40px"
+- for `type: 'checkbox'` the value sets the checked state rather than the element's text value
+  - new Subject({ type: "checkbox", value: true, appendTo: document.body }) captures on then new Subject({ type: "checkbox", value: false, appendTo: document.body }) captures off -> on.elem.checked === true && off.elem.checked === false
+- an input with no `validations` option has an empty list rather than none, so callers can append without checking
+  - new Subject({ appendTo: document.body }) captures i -> Array.isArray(i.options.validations) && i.options.validations.length === 0
+
+## Syntax highlighting is opt-in, and the element's defaults follow its tag
+
+A `language` on its own says what the content is, not that it should be coloured -- highlighting is a separate decision because it costs a stylesheet and changes how the field reads. The text-input defaults are likewise scoped to the tags they make sense for: a `select` is an Input but not a text field.
+
+- `language` alone adds no highlighting class; `syntaxHighlighting` is what turns it on
+  - new Subject({ language: "js", appendTo: document.body }) captures off then new Subject({ language: "js", syntaxHighlighting: true, appendTo: document.body }) captures on -> off.elem.className.includes("language-js") === false && on.elem.classList.contains("language-js")
+- text-input defaults apply to `input` and `textarea` and not to other tags an Input can take
+  - new Subject({ appendTo: document.body }) captures text then new Subject({ tag: "select", appendTo: document.body }) captures select -> text.elem.getAttribute("autocomplete") === "off" && select.elem.getAttribute("autocomplete") === null
+- `validate()` returns the messages it produced and marks the element invalid; a value that passes returns nothing and clears the mark
+  - new Subject({ validations: [[v => v === "ok", "must be ok"]], value: "no", appendTo: document.body }) captures bad then bad.validate() captures errors then new Subject({ validations: [[v => v === "ok", "must be ok"]], value: "ok", appendTo: document.body }) captures good then good.validate() captures none -> errors.join() === "must be ok" && bad.elem.getAttribute("aria-invalid") === "true" && none === undefined && good.elem.getAttribute("aria-invalid") === null