@vanilla-bean/components 2.0.1 → 2.0.3

package/components/Table/Table.lld.md

@@ -6,16 +6,30 @@ Sortable data table where sort state is explicit options. The design decision: `
 
 ## Sort state lives in options - externally readable and settable
 
-- clicking a column header updates `sortProperty` and `sortDirection` as regular options; external code can read or set sort state without querying the DOM
-  - does clicking a sortable column update sortProperty to that column's key?
-  - does clicking an already-sorted column toggle sortDirection?
+- clicking a column header updates `sortProperty` and `sortDirection` as regular options; external code can read or set sort state without querying the DOM. The first click on a column sorts it descending; a second click on the same column toggles to ascending -- sorting only moves between columns, there is no click back to unsorted
+  - new Subject({ columns: [{ key: "name", content: "Name", sort: true }], data: [{ name: "b" }, { name: "a" }] }) captures t then t.elem.querySelector("th").dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) -> t.options.sortProperty === "name" && t.options.sortDirection === "desc"
+  - new Subject({ columns: [{ key: "name", content: "Name", sort: true }], data: [{ name: "b" }, { name: "a" }] }) captures t then t.elem.querySelector("th").dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then t.elem.querySelector("th").dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) -> t.options.sortDirection === "asc"
 
 ## Custom cell renderers receive the full row context, not just the cell value
 
 - a column's `dataColumn` function receives `{ column, rowData, table }` so cells can cross-reference other columns or interact with the table
-  - does a dataColumn function receive the complete rowData object for its row?
+  - new Array() captures seen then new Subject({ columns: [{ key: "name", dataColumn: arg => { seen.push(arg); return {}; } }], data: [{ name: "x" }] }) captures t -> seen.length === 1 && seen[0].rowData.name === "x" && seen[0].table === t && seen[0].column.key === "name"
 
 ## Footer aligns with data columns, not with DOM order
 
 - footer cells are positioned by column key; adding or reordering columns does not misalign footer labels from data
-  - does the footer appear in the correct columns regardless of column order?
+  - new Subject({ columns: [{ key: "name", content: "Name" }, { key: "amount", content: "Amount" }], data: [{ name: "x", amount: 1 }], footer: [{ key: "amount", content: "AMT" }, { key: "name", content: "NM" }] }) captures t then Array.from(t.elem.querySelectorAll("tfoot td")).map(c => c.textContent) captures cells -> cells.join(",") === "NM,AMT"
+
+## A sortable column advertises its state, in the markup and in the icon
+
+Sort state is not only a visual affordance: a reader using a screen reader needs to know which column the order comes from and which way it runs, which is what `aria-sort` carries. A sortable column that is not the sorted one shows the neutral affordance rather than nothing, so it reads as available rather than absent.
+
+- every sortable column starts at `aria-sort="none"` with the neutral icon; the sorted column reports its direction and shows a directional icon while the others stay neutral
+  - new Subject({ columns: [{ key: "name", label: "Name", sort: true }, { key: "age", label: "Age", sort: true }], data: [{ name: "b", age: 2 }, { name: "a", age: 1 }], appendTo: document.body }) captures t then Array.from(t.elem.querySelectorAll("th")).map(h => h.getAttribute("aria-sort")) captures initial then t.elem.querySelector("th") captures first then first.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then first.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) then Array.from(t.elem.querySelectorAll("th")).map(h => h.getAttribute("aria-sort")) captures afterFirst then first.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then first.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) -> initial.join() === "none,none" && afterFirst.join() === "descending,none" && Array.from(t.elem.querySelectorAll("th")).map(h => h.getAttribute("aria-sort")).join() === "ascending,none"
+- the sorted column's icon points the way the order runs; a sortable column that is not sorted keeps the neutral icon
+  - new Subject({ columns: [{ key: "name", label: "Name", sort: true }, { key: "age", label: "Age", sort: true }], data: [{ name: "b", age: 2 }, { name: "a", age: 1 }], appendTo: document.body }) captures t then Array.from(t.elem.querySelectorAll("th")).map(h => Array.from(h.querySelectorAll("*")).flatMap(e => Array.from(e.classList).filter(c => c.startsWith("fa-sort"))).join()) captures initial then t.elem.querySelector("th") captures first then first.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true })) then first.dispatchEvent(new PointerEvent("pointerup", { bubbles: true })) then Array.from(t.elem.querySelectorAll("th")).map(h => Array.from(h.querySelectorAll("*")).flatMap(e => Array.from(e.classList).filter(c => c.startsWith("fa-sort"))).join()) captures sorted -> initial.join("|") === "fa-sort|fa-sort" && sorted.join("|") === "fa-sort-up|fa-sort"
+- a data set that is absent renders an empty table rather than throwing
+  - new Subject({ columns: [{ key: "a", label: "A" }], data: undefined, appendTo: document.body }) captures missing then new Subject({ columns: [{ key: "a", label: "A" }], data: null, appendTo: document.body }) captures empty -> missing.elem.querySelectorAll("tbody tr").length === 0 && empty.elem.querySelectorAll("tbody tr").length === 0
+
+- option changes made before the first render are recorded without rendering; the first render then reflects them
+  - new Array() captures sorted then new Subject({ autoRender: false, columns: [{ key: "a", label: "A", sort: true }], data: [{ a: 1 }], onSort: (p, d) => sorted.push(d) }) captures t then t.options.sortDirection = "asc" then sorted.length captures beforeRender then t.render() then t.options.sortDirection = "desc" -> beforeRender === 0 && sorted.join() === "desc"

package/components/TagList/Tag.js

@@ -52,6 +52,20 @@ const StyledComponent = styled(
 	`,
 );
 
+/**
+ * A single tag chip within a TagList.
+ *
+ * Renders its text alongside a remove button, which destroys the tag. In read-only mode the button
+ * is omitted and the chip is display-only.
+ * @param {object} [options={}] - Tag configuration options
+ * @param {string} [options.tag='li'] - HTML tag for the chip element
+ * @param {number} [options.tabIndex=0] - Tab order for the chip
+ * @param {boolean} [options.readOnly=false] - Omits the remove button and applies the readOnly class
+ * @param {string} [options.textContent] - The tag's text; also mirrored onto the element as
+ *   `data-value`, which is what TagList reads back when collecting current tags
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Tag} Tag component instance
+ */
 class Tag extends StyledComponent {
 	static schema = {
 		tag: { default: 'li' },

package/components/TagList/TagList.js

@@ -105,21 +105,3 @@ class TagList extends StyledComponent {
 }
 
 export default TagList;
-
-// Zero-arg scenarios for LLD verification
-export const duplicateRejected = () => {
-	const tagList = new TagList({ tags: ['hello'], autoRender: false });
-	tagList.render();
-	const before = tagList.elem.children.length;
-	tagList.tagInput.elem.value = 'hello';
-	tagList.tagInput.elem.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter', bubbles: true }));
-	return tagList.elem.children.length === before;
-};
-
-export const inputIsLastAfterAdd = () => {
-	const tagList = new TagList({ tags: [], autoRender: false });
-	tagList.render();
-	tagList.tagInput.elem.value = 'new-tag';
-	tagList.tagInput.elem.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter', bubbles: true }));
-	return tagList.elem.lastElementChild === tagList.addTag.elem;
-};

package/components/TagList/TagList.lld.md

@@ -8,23 +8,28 @@ Editable tag collection. The key decision: read-only mode removes the editing in
 
 - `readOnly: true` omits the input and add button entirely; `readOnly: false` includes the full editing interface
   - does a readOnly TagList contain no input element?
-  - does a non-readOnly TagList contain both an input and an add button?
+  - new Subject({ readOnly: false, tags: [] }) captures t -> !!t.elem.querySelector("input") && !!t.elem.querySelector("button")
 
 ## Duplicate tags are silently rejected - adding them does nothing
 
-**method:** `duplicateRejected`
-
 - attempting to add a tag that already exists leaves the list unchanged; there is no error
-  - duplicateRejected() → true
+  - new Subject({ tags: ["hello"], autoRender: false }) captures t then t.render() then t.elem.children.length captures before then t.tagInput.elem.value = "hello" then t.tagInput.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "Enter", bubbles: true })) -> t.elem.children.length === before
 
 ## The add interface stays at the end as tags are added and removed
 
-**method:** `inputIsLastAfterAdd`
-
 - new tags are inserted before the add-tag input; the input remains the last element automatically
-  - inputIsLastAfterAdd() → true
+  - new Subject({ tags: [], autoRender: false }) captures u then u.render() then u.tagInput.elem.value = "new-tag" then u.tagInput.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "Enter", bubbles: true })) -> u.elem.lastElementChild === u.addTag.elem
 
 ## Cleanup removes the editing interface completely on destroy
 
 - the input, button, and popover are destroyed with the component, removing event listeners
   - does destroying the TagList remove its editing interface from the DOM?
+
+## Enter commits a tag; nothing else does, and nothing empty or repeated gets in
+
+Typing is not committing -- the field has to stay usable while a tag is being spelled, so only Enter turns what is typed into a tag. What arrives is then filtered on the two grounds that are always wrong: nothing at all, and something already in the list.
+
+- Enter adds the typed tag; any other key leaves the list as it was
+  - new Subject({ tags: ["one"], appendTo: document.body }) captures t then t.tagInput.elem.value = "two" then t.tagInput.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "Enter", bubbles: true })) then Array.from(t.elem.querySelectorAll("li[data-value]")).map(li => li.dataset.value) captures afterEnter then t.tagInput.elem.value = "three" then t.tagInput.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "a", bubbles: true })) -> afterEnter.join() === "one,two" && Array.from(t.elem.querySelectorAll("li[data-value]")).map(li => li.dataset.value).join() === "one,two"
+- a blank or whitespace-only entry is not added, and neither is one already present
+  - new Subject({ tags: ["one"], appendTo: document.body }) captures t then t.tagInput.elem.value = "   " then t.tagInput.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "Enter", bubbles: true })) then Array.from(t.elem.querySelectorAll("li[data-value]")).length captures afterBlank then t.tagInput.elem.value = "one" then t.tagInput.elem.dispatchEvent(new KeyboardEvent("keyup", { key: "Enter", bubbles: true })) -> afterBlank === 1 && t.elem.querySelectorAll("li[data-value]").length === 1

package/components/Tooltip/Tooltip.lld.md

@@ -6,17 +6,25 @@ Positioned popover for explanatory text with nine validated position presets. Th
 
 ## Invalid position fails immediately, not on first show
 
+Surfacing misuse at development time beats producing misaligned tooltips that only appear during interaction.
+
 - there are nine valid position values; anything else throws at assignment time, not at show time
-- this surfaces misuse at development time rather than producing misaligned tooltips that only appear during interaction
   - does passing an invalid position value throw immediately?
 
 ## Changing position removes the previous position class
 
+Callers can reassign `position` freely without cleaning up after the previous value.
+
 - only one position class is active at a time; switching position replaces, not accumulates
-- callers can safely reassign position without manual cleanup
   - does changing position from one value to another leave only the new position class active?
 
 ## Show/hide animation is declared in CSS, not scheduled in JavaScript
 
-- the transition is controlled by `:popover-open` and `@starting-style`; the component applies position classes and the platform animates
-- this means animation timing is a CSS concern, not a component lifecycle concern
+The transition is controlled by `:popover-open` and `@starting-style`. The component's only part is applying position classes; the platform animates. Animation timing is therefore a CSS concern rather than a component lifecycle one, which is why nothing here schedules it or waits on it.
+
+## A tooltip is always identifiable as one
+
+The `tooltip` class is what the stylesheet and any consumer selector key off, so it is added rather than assigned -- classes the caller passes come along with it instead of replacing it.
+
+- every tooltip carries the `tooltip` class, and caller-supplied classes are added alongside it
+  - new Subject({ textContent: "tip", addClass: "mine", appendTo: document.body }) captures t -> t.elem.classList.contains("tooltip") && t.elem.classList.contains("mine")

package/components/TooltipWrapper/TooltipWrapper.lld.md

@@ -19,3 +19,17 @@ Component that adds a tooltip to whatever it wraps. The Tooltip is created durin
 
 - when the TooltipWrapper is destroyed, the Tooltip component is also destroyed and removed from the DOM
   - does destroying the wrapper also remove the tooltip from the DOM?
+
+## The tooltip option takes a string or a full set of options
+
+Most tooltips are a line of text, so a string is the common case and stays the shortest thing to write. Anything more -- extra classes, placement, markup -- is the same option carrying a full options object instead.
+
+- a string `tooltip` becomes the tooltip's text; an object is used as the tooltip's own options
+  - new Subject({ tooltip: "plain", appendTo: document.body }) captures s then new Subject({ tooltip: { textContent: "rich", addClass: "fancy" }, appendTo: document.body }) captures o then s.elem.querySelector("[popover]") captures plain then o.elem.querySelector("[popover]") captures rich -> plain.textContent === "plain" && rich.textContent === "rich" && rich.classList.contains("fancy")
+
+## Moving the pointer away does not close a tooltip the keyboard is holding open
+
+Hover and focus both open the tooltip, so the pointer leaving is only half the story: if the control still has focus, the tooltip is being held open by the keyboard and closing it would take away what a keyboard user is reading.
+
+- `pointerout` hides the tooltip only when focus has also left the control
+  - new Subject({ tooltip: "tip", appendTo: document.body }) captures held then new Subject({ tooltip: "tip", appendTo: document.body }) captures loose then held.elem.querySelector("[popover]") captures heldTip then loose.elem.querySelector("[popover]") captures looseTip then held.elem.dispatchEvent(new PointerEvent("pointerover", { bubbles: true, clientX: 5, clientY: 5 })) then loose.elem.dispatchEvent(new PointerEvent("pointerover", { bubbles: true, clientX: 5, clientY: 5 })) then await new Promise(r => setTimeout(r, 760)) then held.elem.focus() then held.elem.dispatchEvent(new PointerEvent("pointerout", { bubbles: true })) then loose.elem.dispatchEvent(new PointerEvent("pointerout", { bubbles: true })) -> heldTip.style.display === "block" && looseTip.style.display === "none"

package/components/Whiteboard/Whiteboard.js

@@ -107,7 +107,10 @@ export default class Whiteboard extends Component {
 
 				this.drawEvent.call(this, event);
 			}).bind(this),
-			this.options.drawThrottle || Math.max(Math.min(this.options.lineWidth + 3, 24), 6),
+			// `??`, not `||`: 0 is a legitimate throttle meaning "draw every move event", and `||`
+			// discarded it in favour of the derived rate -- so the one value a caller reaching for
+			// maximum fidelity would pass was the one value that silently did nothing.
+			this.options.drawThrottle ?? Math.max(Math.min(this.options.lineWidth + 3, 24), 6),
 		);
 		const removePointer = event => {
 			if (!this.pointers[event.pointerId]) return;
@@ -192,9 +195,14 @@ export default class Whiteboard extends Component {
 	}
 
 	/**
-	 * Clears the entire canvas.
+	 * Clears the entire canvas and discards any stroke currently being tracked.
 	 */
 	clearCanvas() {
 		this.canvas.clearRect(0, 0, this.elem.width, this.elem.height);
+
+		// Erasing the picture and forgetting the in-progress gesture are two separate jobs. Clearing
+		// only the pixels left every active pointer still registered, so the next pointermove resumed
+		// the old stroke and drew a line from wherever the pointer had been before the clear.
+		this.pointers = {};
 	}
 }

package/components/Whiteboard/Whiteboard.lld.md

@@ -6,30 +6,44 @@ Multi-touch drawing canvas that tracks each pointer independently. The design de
 
 ## Each pointer draws an independent line
 
+Each active pointer is tracked by its own ID, which is what keeps concurrent strokes from being interleaved into one.
+
 - two simultaneous touches produce two independent strokes; neither interferes with the other
-- the whiteboard tracks each active pointer by its ID
-  - does a second finger touching the canvas start a separate line from the first?
+  - new Subject({ drawThrottle: 0, appendTo: document.body }) captures w then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 10, clientY: 10 })) then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 2, clientX: 40, clientY: 40 })) then Object.keys(w.pointers) captures both then w.elem.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: 10, clientY: 10 })) -> both.length === 2 && Object.keys(w.pointers).join() === "2"
+
+Lifting one finger ends one stroke, not the gesture. The document listeners that track movement stay attached until the last pointer leaves, and a pointer that is no longer down contributes nothing even while they are.
+
+- a pointer that has lifted stops contributing while the others keep drawing; the move listeners are released only when the last pointer leaves
+  - new Array() captures drawn then new Subject({ drawThrottle: 0, appendTo: document.body }) captures w then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 10, clientY: 10 })) then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 2, clientX: 40, clientY: 40 })) then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: 10, clientY: 10 })) then w.drawLine = () => drawn.push(1) then w.elem.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: 99, clientY: 99 })) then drawn.length captures fromLifted then w.elem.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 2, clientX: 99, clientY: 99 })) then drawn.length captures fromHeld then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 2, clientX: 99, clientY: 99 })) then w.elem.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 2, clientX: 120, clientY: 120 })) -> fromLifted === 0 && fromHeld === 1 && drawn.length === 1
+  - new Subject({ drawThrottle: 0, appendTo: document.body }) captures w then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 2, clientX: 5, clientY: 5 })) then w.drawEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 77, clientX: 9, clientY: 9 })) -> Object.keys(w.pointers).join() === "2"
 
 ## Draw throttle rate adapts to line width - no separate configuration needed
 
-- the throttle delay is derived from `lineWidth + 3` (clamped to a range); thicker lines are visually coarser and tolerate a longer delay
-- callers set `lineWidth` and the draw rate adjusts automatically; they do not configure throttle separately
+The delay is derived from the line width and clamped to a usable range: thicker lines are visually coarser, so they tolerate a longer gap between sampled points without looking angular. Callers set `lineWidth` and the draw rate follows; there is no separate throttle to configure.
+
 - explicitly setting `drawThrottle` overrides the derived rate when the default does not fit the use case
+  - new Array() captures derived then new Array() captures overridden then new Subject({ lineWidth: 20, appendTo: document.body }) captures a then a.drawEvent = () => derived.push(1) then a.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 0, clientY: 0 })) then [1, 2, 3, 4, 5].forEach(i => a.elem.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: i * 5, clientY: i * 5 }))) then new Subject({ lineWidth: 20, drawThrottle: 0, appendTo: document.body }) captures b then b.drawEvent = () => overridden.push(1) then b.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 0, clientY: 0 })) then [1, 2, 3, 4, 5].forEach(i => b.elem.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: i * 5, clientY: i * 5 }))) -> derived.length === 1 && overridden.length === 5
 
 ## Completed strokes are emitted as complete lines, not as individual points
 
+Callers receive whole lines, suitable for persistence or replay, rather than a stream of coordinate events they would have to reassemble.
+
 - when a pointer lifts, the full array of points recorded during that stroke is emitted as a line event
-- callers receive whole lines for persistence or replay, not a stream of coordinate events
-  - does lifting a pointer emit all the points recorded during that stroke?
+  - new Array() captures seen then new Subject({ appendTo: document.body, onLine: e => seen.push(e) }) captures w then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 1, clientY: 1 })) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: 5, clientY: 5 })) then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: 9, clientY: 9 })) -> seen.length === 1 && Array.isArray(seen[0].detail.line)
 
 ## readOnly prevents new strokes without clearing the canvas
 
+**browser:** true
+
+Read-only mode is non-destructive: content survives the mode switch, so toggling it is safe at any time.
+
 - existing content remains visible; only new pointer interactions are blocked
-- the whiteboard is non-destructive in read-only mode; content survives the mode switch
-  - does enabling readOnly prevent a new stroke from starting while preserving existing content?
+  - new Array() captures lines then new Subject({ appendTo: document.body, onLine: e => lines.push(e) }) captures w then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 10, clientY: 10 })) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 1, clientX: 40, clientY: 40 })) then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 1, clientX: 60, clientY: 60 })) then await new Promise(r => setTimeout(r, 80)) then [lines.length, w.elem.getContext("2d").getImageData(0, 0, w.elem.width, w.elem.height).data.reduce((n, v, i) => i % 4 === 3 && v !== 0 ? n + 1 : n, 0)] captures drawn then w.options.readOnly = true then await new Promise(r => setTimeout(r, 80)) then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 2, clientX: 10, clientY: 10 })) then document.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, pointerId: 2, clientX: 40, clientY: 40 })) then document.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, pointerId: 2, clientX: 60, clientY: 60 })) then await new Promise(r => setTimeout(r, 80)) -> drawn[0] === 1 && drawn[1] > 0 && lines.length === drawn[0] && w.elem.getContext("2d").getImageData(0, 0, w.elem.width, w.elem.height).data.reduce((n, v, i) => i % 4 === 3 && v !== 0 ? n + 1 : n, 0) === drawn[1]
 
 ## clearCanvas wipes content without removing the element
 
-- `clearCanvas()` clears the 2D context and resets stroke state
-- the canvas element itself remains in the DOM, reusable for new drawing
-  - does clearCanvas produce a blank canvas without removing it from the page?
+The canvas element itself stays in the DOM and is immediately reusable for new drawing.
+
+- `clearCanvas()` has two separate jobs: erase the drawn content, and reset any stroke currently being tracked -- clearing the picture does not by itself imply an in-progress gesture is also reset, so both happen explicitly
+  - new Array() captures cleared then new Subject({ appendTo: document.body }) captures w then w.canvas.clearRect = () => cleared.push(1) then w.clearCanvas() -> cleared.length === 1 && w.elem.isConnected
+  - new Subject({ appendTo: document.body }) captures w then w.elem.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, pointerId: 1, clientX: 0, clientY: 0 })) then Object.keys(w.pointers).length captures during then w.clearCanvas() -> during === 1 && Object.keys(w.pointers).length === 0

package/devTools/lldRunner.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+
+// Bridge to the lldtdd engine for the demo's "Run" button. lldtdd is a real dependency now,
+// resolved from node_modules like everything else -- the sibling-checkout era is over
+// (.githooks/pre-commit made the same move). Still run as a subprocess by demo/server.js so a
+// crash in parsing or translation reports as JSON instead of taking the dev server down.
+//
+// runDocument() would be simpler but returns only counts; the demo paints a status icon onto
+// every claim line, so it needs the per-case results, which means composing the pipeline the
+// way lldtdd's own runner does: parse, translate, synthesize, run.
+//
+// Usage: bun run devTools/lldRunner.js <path-to-file.lld.md>
+
+const [, , targetFile] = process.argv;
+
+/**
+ *
+ */
+async function main() {
+	if (!targetFile) {
+		console.log(JSON.stringify({ error: 'usage: lldRunner.js <path-to-file.lld.md>' }));
+		return;
+	}
+
+	try {
+		const { parseFile, translate, synthesize, runSuite } = await import('lldtdd');
+
+		const doc = await parseFile(targetFile);
+		const translated = await translate(doc, { execute: true });
+		const suite = await synthesize(translated);
+		const result = await runSuite(suite);
+
+		// An array, because lldMarkdown's resultsByDescription walks `for (const result of
+		// runResult) visit(result.cases)` -- one document still arrives as a list of one.
+		console.log(JSON.stringify([result]));
+	} catch (error) {
+		console.log(JSON.stringify({ error: error?.stack || String(error) }));
+	}
+}
+
+await main();

package/eslint.config.cjs

@@ -32,6 +32,10 @@ module.exports = [
 		},
 		rules: {
 			'no-console': 'warn',
+			// Destructure-to-omit (`const { key: _omitted, ...rest } = x`) is the idiomatic way to
+			// exclude a field while spreading, and the recommended config flags the discarded
+			// binding as unused. ignoreRestSiblings is the rule's own carve-out for exactly this.
+			'no-unused-vars': ['error', { ignoreRestSiblings: true }],
 			'no-nested-ternary': 'error',
 			'no-var': 'error',
 			'prefer-const': 'error',

package/index.d.ts

@@ -229,7 +229,7 @@ export declare class BottomSheet extends Component {
 	readonly body: Component;
 	/** Slides the sheet into view and registers navigation listeners to auto-dismiss. */
 	show(): void;
-	/** 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 */
 	hide(): void;
 }
 
@@ -255,12 +255,13 @@ export interface CalendarOptions extends ComponentOptions {
 	month?: number;
 	/** Initial day to display, defaults to current day */
 	day?: number;
+	/** Day-of-week index (0-6, Sunday first) as returned by Date.getDay(); set from the selected date and read by the week view */
+	weekday?: number;
 	/** Available view modes for toolbar */
 	views?: Array<string>;
 	/** Whether to display time in 24-hour format in day view (default: false) */
 	display24h?: boolean;
 	events?: Array<any>;
-	weekday?: any;
 }
 
 export declare class Calendar extends Component {
@@ -364,8 +365,10 @@ export declare class Form extends Component {
 export interface IconOptions extends ComponentOptions {
 	/** FontAwesome icon name (without 'fa-' prefix) */
 	icon?: string;
-	/** FontAwesome animation name (without 'fa-' prefix) */
+	/** FontAwesome animation name (without 'fa-' prefix), run on the whole element */
 	animation?: string;
+	/** FontAwesome animation name (without 'fa-' prefix), run on the glyph alone */
+	iconAnimation?: string;
 }
 
 export declare class Icon extends Component {
@@ -622,6 +625,7 @@ export interface TableOptions extends ComponentOptions {
 	sortProperty?: string;
 	/** Sort direction ('asc' or 'desc') */
 	sortDirection?: 'asc' | 'desc';
+	/** 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 */
 	selection?: any;
 }
 
@@ -687,7 +691,7 @@ export declare class Whiteboard extends Component {
 	constructor(options?: WhiteboardOptions, ...children: Array<Elem | HTMLElement | string>);
 	/** Draws a line on the canvas with specified properties. */
 	drawLine(options: Record<string, any>): void;
-	/** Clears the entire canvas. */
+	/** Clears the entire canvas and discards any stroke currently being tracked. */
 	clearCanvas(): void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vanilla-bean/components",
-	"version": "2.0.1",
+	"version": "2.0.3",
 	"type": "module",
 	"module": "./index.js",
 	"types": "./index.d.ts",
@@ -32,7 +32,7 @@
 		"/utils/**/*",
 		"index.js",
 		"index.d.ts",
-		"./FontWithASyntaxHighlighter-Regular.woff2",
+		"FontWithASyntaxHighlighter-Regular.woff2",
 		"!/components/**/demo.js",
 		"!/components/**/*.test.js",
 		"!/utils/**/*.test.js",
@@ -73,6 +73,8 @@
 		"create:component": "bun run devTools/createComponent.js",
 		"lint": "bun --bun eslint",
 		"lint:fix": "bun --bun eslint --fix",
+		"lld": "lldtdd run",
+		"lld:lint": "lldtdd lint",
 		"format": "BROWSERSLIST_IGNORE_OLD_DATA=1 bun run lint:fix && bun --bun prettier --write . --log-level warn",
 		"test": "bun test",
 		"test:watch": "bun test --watch",
@@ -114,6 +116,7 @@
 		"eslint-plugin-write-good-comments": "^0.2.0",
 		"globals": "17",
 		"happy-dom": "20",
+		"lldtdd": "^0.1.0",
 		"marked": "18",
 		"moresketchy": "wbern/MoreSketchy.js",
 		"prettier": "^3.9.5"

package/spellcheck.config.cjs

@@ -6,6 +6,7 @@ module.exports = {
 	templates: true,
 	lang: 'en_US',
 	skipWords: [
+		'bezier',
 		'ecma',
 		'compat',
 		'eslintrc',

package/theme/button.js

@@ -29,6 +29,15 @@ export default ({ colors, fonts }) => `
 		padding: 0 6px 0 3px;
 	}
 
+	/*
+	 * An animated glyph turns about the center of its own box, and the padding above is heavier on
+	 * one side, which would swing it off-center. Evening it out keeps the same total width, so
+	 * starting an animation never shifts the label beside it.
+	 */
+	&[class*='icon-animation-']:before {
+		padding: 0 4.5px;
+	}
+
 	&:after {
 		content: '';
 		position: absolute;

package/theme/page.js

@@ -211,4 +211,66 @@ export default theme => `
 		${fonts.fontAwesomeSolid}
 		content: var(--fa);
 	}
+
+	/*
+	 * Icon's iconAnimation option. FontAwesome's own animation classes animate the element that
+	 * carries them, which is what you want on a bare Icon and not what you want on anything that
+	 * also renders a label — Button and Link extend Icon, so an fa animation there spins the
+	 * control, background and text included. These aim the same animations at the :before that
+	 * draws the glyph, reusing FontAwesome's keyframes and honoring the same --fa-animation-*
+	 * overrides, so a caller can animate the glyph and the element independently.
+	 */
+	[class*='icon-animation-']:before {
+		animation-delay: var(--fa-animation-delay, 0s);
+		animation-direction: var(--fa-animation-direction, normal);
+		animation-iteration-count: var(--fa-animation-iteration-count, infinite);
+	}
+
+	.icon-animation-spin:before {
+		animation-name: fa-spin;
+		animation-duration: var(--fa-animation-duration, 2s);
+		animation-timing-function: var(--fa-animation-timing, linear);
+	}
+
+	.icon-animation-spin-pulse:before {
+		animation-name: fa-spin;
+		animation-duration: var(--fa-animation-duration, 1s);
+		animation-timing-function: var(--fa-animation-timing, steps(8));
+	}
+
+	.icon-animation-beat:before {
+		animation-name: fa-beat;
+		animation-duration: var(--fa-animation-duration, 1s);
+		animation-timing-function: var(--fa-animation-timing, ease-in-out);
+	}
+
+	.icon-animation-fade:before {
+		animation-name: fa-fade;
+		animation-duration: var(--fa-animation-duration, 1s);
+		animation-timing-function: var(--fa-animation-timing, ease-in-out);
+	}
+
+	.icon-animation-beat-fade:before {
+		animation-name: fa-beat-fade;
+		animation-duration: var(--fa-animation-duration, 1s);
+		animation-timing-function: var(--fa-animation-timing, ease-in-out);
+	}
+
+	.icon-animation-bounce:before {
+		animation-name: fa-bounce;
+		animation-duration: var(--fa-animation-duration, 1s);
+		animation-timing-function: var(--fa-animation-timing, cubic-bezier(0.28, 0.84, 0.42, 1));
+	}
+
+	.icon-animation-flip:before {
+		animation-name: fa-flip;
+		animation-duration: var(--fa-animation-duration, 1.5s);
+		animation-timing-function: var(--fa-animation-timing, ease-in-out);
+	}
+
+	.icon-animation-shake:before {
+		animation-name: fa-shake;
+		animation-duration: var(--fa-animation-duration, 0.75s);
+		animation-timing-function: var(--fa-animation-timing, ease-in-out);
+	}
 `;

package/Component/Component.scenarios.js

@@ -1,88 +0,0 @@
-import Component from './Component.js';
-
-export const __lld_api = `
-  destructiveRender() -> boolean | renders a component twice; returns true if child count matches (1) - second render cleared the first
-  optionReactionFires() -> number | assigns to option after render; returns how many times _setOption was called (1 = reactive)
-  buildBeforeOptions() -> boolean | verifies build() DOM structure exists when _setOption runs (true = ordering is correct)
-  priorityRunsFirst() -> boolean | textContent (priority option) runs before style (non-priority); returns true if correct order
-  replaceCleanupRunsOnce() -> number | replaceCleanup called 3x with same key; returns count of fns that ran at processCleanup time (1 = no accumulation)
-`;
-
-export const destructiveRender = () => {
-	class TestComp extends Component {
-		build() {
-			this.elem.append(document.createElement('span'));
-		}
-	}
-	const comp = new TestComp({ autoRender: false });
-	comp.render();
-	const afterFirst = comp.elem?.children?.length ?? 0;
-	comp.render();
-	const afterSecond = comp.elem?.children?.length ?? 0;
-	return afterFirst === 1 && afterSecond === 1;
-};
-
-export const optionReactionFires = () => {
-	let reactions = 0;
-	class TestComp extends Component {
-		_setOption(key, value) {
-			if (key === 'textContent' && this.rendered) reactions++;
-			super._setOption(key, value);
-		}
-	}
-	const comp = new TestComp({ autoRender: false });
-	comp.render();
-	const baseline = reactions;
-	comp.options.textContent = 'hello';
-	return reactions - baseline;
-};
-
-export const buildBeforeOptions = () => {
-	let buildRanBeforeOption = false;
-	let buildRan = false;
-	class TestComp extends Component {
-		build() {
-			buildRan = true;
-			this.elem.append(document.createElement('span'));
-		}
-		_setOption(key, value) {
-			if (key === 'textContent') buildRanBeforeOption = buildRan;
-			super._setOption(key, value);
-		}
-	}
-	const comp = new TestComp({ textContent: 'hello', autoRender: false });
-	comp.render();
-	return buildRanBeforeOption;
-};
-
-export const priorityRunsFirst = () => {
-	const order = [];
-	class TestComp extends Component {
-		build() {}
-		_setOption(key, value) {
-			if (key === 'textContent' || key === 'style') order.push(key);
-			super._setOption(key, value);
-		}
-	}
-	// textContent is a priority option; style is not
-	const comp = new TestComp({ textContent: 'hello', style: { color: 'red' }, autoRender: false });
-	comp.render();
-	return order[0] === 'textContent';
-};
-
-export const replaceCleanupRunsOnce = () => {
-	const comp = new Component({ autoRender: false });
-	let count = 0;
-	comp.replaceCleanup('test', () => {
-		count++;
-	});
-	comp.replaceCleanup('test', () => {
-		count++;
-	}); // runs previous = 1
-	comp.replaceCleanup('test', () => {
-		count++;
-	}); // runs previous = 2, stores latest
-	const countBeforeCleanup = count;
-	comp.processCleanup(); // runs only the latest = 3
-	return count - countBeforeCleanup; // 1 - only latest ran at cleanup time
-};