@vanilla-bean/components 1.0.0

package/components/Table/Table.js

@@ -0,0 +1,171 @@
+import { capitalize, orderBy } from '../../utils';
+import theme from '../../theme';
+import { Elem } from '../../Elem';
+import { Component } from '../../Component';
+import { Icon } from '../Icon';
+
+const defaultOptions = { tag: 'table' };
+
+/**
+ * Data table component with sorting, column configuration, and footer support.
+ *
+ * Renders tabular data with configurable columns, sortable headers, and optional footer.
+ * Supports custom cell rendering and automatic sorting functionality.
+ * @param {object} [options={}] - Table configuration options
+ * @param {string} [options.tag='table'] - HTML tag for the table element
+ * @param {Array<string|object>} options.columns - Column definitions with keys and optional configurations
+ * @param {Array<object>} [options.data] - Array of data objects to display in table rows
+ * @param {Array<string|object>} [options.footer] - Footer row data
+ * @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 {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Table} Table component instance
+ */
+class Table extends Component {
+	constructor(options = {}, ...children) {
+		super(
+			{
+				...defaultOptions,
+				onSort: (property, direction) => {
+					this.options.data = this.options.data.sort(orderBy({ property, direction }));
+				},
+				...options,
+				columns: (options.columns || []).map(column =>
+					typeof column === 'string' ? { key: column, content: capitalize(column) } : column,
+				),
+				footer: options.footer?.map(column => (typeof column === 'string' ? { content: capitalize(column) } : column)),
+			},
+			...children,
+		);
+	}
+
+	static handlers = {
+		sortDirection(value) {
+			if (this.rendered) this.options.onSort(this.options.sortProperty, value);
+		},
+		data() {
+			this._renderTable();
+		},
+		selection() {
+			this._renderTable();
+		},
+	};
+
+	_renderTable() {
+		const value = this.options.data;
+
+		this._sortSubscribers?.forEach(sub => sub.destroy?.());
+		this._sortSubscribers = null;
+
+		if (!value) return;
+
+		if (this.thead) this.thead.empty();
+		else this.thead = new Elem({ tag: 'thead', appendTo: this });
+
+		if (this.tbody) this.tbody.empty();
+		else this.tbody = new Elem({ tag: 'tbody', appendTo: this });
+
+		if (this.tfoot) this.tfoot.empty();
+		else this.tfoot = new Elem({ tag: 'tfoot', appendTo: this });
+
+		this._sortSubscribers = [];
+		this.replaceCleanup('sortSubscribers', () => this._sortSubscribers?.forEach(sub => sub.destroy?.()));
+
+		this.thead.append(
+			new Component(
+				{ tag: 'tr' },
+				this.options.columns.map(column => {
+					const th = new Component({ tag: 'th', ...column, scope: 'col' });
+
+					if (column.sort) {
+						const iconSub = this.options.subscriber('sortDirection', () => {
+							if (this.options.sortProperty !== column.key) return 'sort';
+
+							return this.options.sortDirection === 'asc' ? 'sort-down' : 'sort-up';
+						});
+						const styleSub = this.options.subscriber('sortDirection', () => ({
+							display: 'inline',
+							marginLeft: '6px',
+							...(this.options.sortProperty !== column.key
+								? { color: theme.colors.dark(theme.colors.gray) }
+								: { color: theme.colors.white }),
+						}));
+
+						this._sortSubscribers.push(iconSub, styleSub);
+
+						const updateAriaSort = () => {
+							let ariaSort = 'none';
+							if (this.options.sortProperty === column.key) {
+								ariaSort = this.options.sortDirection === 'asc' ? 'ascending' : 'descending';
+							}
+							th.elem.setAttribute('aria-sort', ariaSort);
+						};
+						updateAriaSort();
+
+						const sortDirHandler = () => updateAriaSort();
+						const sortPropHandler = () => updateAriaSort();
+						this.options.addEventListener('sortDirection', sortDirHandler);
+						this.options.addEventListener('sortProperty', sortPropHandler);
+						this._sortSubscribers.push({
+							destroy: () => {
+								this.options.removeEventListener('sortDirection', sortDirHandler);
+								this.options.removeEventListener('sortProperty', sortPropHandler);
+							},
+						});
+
+						new Icon({
+							icon: iconSub,
+							style: styleSub,
+							appendTo: th,
+						});
+
+						th.onPointerPress(() => {
+							if (this.options.sortProperty === column.key) {
+								this.options.sortDirection = this.options.sortDirection === 'asc' ? 'desc' : 'asc';
+								return;
+							}
+
+							this.options.sortProperty = column.key;
+							this.options.sortDirection = 'desc';
+						});
+					}
+
+					return th;
+				}),
+			),
+		);
+
+		this.tbody.append(
+			this.options.data.map(
+				rowData =>
+					new Component(
+						{ tag: 'tr' },
+						this.options.columns.map(
+							column =>
+								new Component(
+									{
+										tag: 'td',
+										...(typeof column.dataColumn === 'function'
+											? column.dataColumn({ column, rowData, table: this })
+											: column.dataColumn),
+									},
+									column.key ? rowData[column.key]?.toString() : undefined,
+								),
+						),
+					),
+			),
+		);
+
+		if (this.options.footer) {
+			this.tfoot.append(
+				new Component(
+					{ tag: 'tr' },
+					this.options.footer.map(footData => new Component({ tag: 'td', ...footData })),
+				),
+			);
+		}
+	}
+}
+
+export default Table;

package/components/Table/Table.lld.md

@@ -0,0 +1,21 @@
+# Table
+
+> ./Table.js
+
+Sortable data table where sort state is explicit options. The design decision: `sortProperty` and `sortDirection` are readable and writable options; the sort state is in the component's options object, not hidden inside event handlers, so it's readable and settable from outside.
+
+## 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?
+
+## 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?
+
+## 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?

package/components/Table/index.js

@@ -0,0 +1 @@
+export { default as Table } from './Table';

package/components/TagList/Tag.js

@@ -0,0 +1,84 @@
+import { Component } from '../../Component';
+import { styled } from '../../styled';
+import { Button } from '../Button';
+import { Elem } from '../../Elem';
+
+const StyledComponent = styled(
+	Component,
+	({ colors }) => `
+		padding: 3px 6px;
+		margin: 0;
+		display: inline-flex;
+		align-items: center;
+		gap: 4px;
+		font-size: 0.85em;
+		line-height: 1;
+		background-color: ${colors.black};
+		border: 1px solid ${colors.alpha(colors.teal, 0.35)};
+		border-radius: 3px;
+		white-space: nowrap;
+		user-select: none;
+		cursor: default;
+		list-style: none;
+
+		&:not(.readOnly):not(.add-tag):hover {
+			border-color: ${colors.light(colors.teal)};
+		}
+
+		&.add-tag {
+			padding: 0;
+			border: none;
+			background: none;
+			gap: 4px;
+			cursor: text;
+		}
+
+		&:not(.add-tag) button {
+			width: 14px !important;
+			height: 14px !important;
+			font-size: 8px;
+			opacity: 0.4;
+			flex-shrink: 0;
+			background: transparent !important;
+
+			&:after { display: none; }
+
+			&:hover, &:focus {
+				opacity: 0.9;
+				background: transparent !important;
+				top: -1px;
+			}
+		}
+	`,
+);
+
+const defaultOptions = { tag: 'li', readOnly: false };
+
+class Tag extends StyledComponent {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+
+	constructor(options = {}, ...children) {
+		super({ tabindex: '0', ...defaultOptions, ...options }, ...children);
+	}
+
+	build() {
+		this._textSpan = new Elem({ tag: 'span', appendTo: this });
+
+		if (!this.options.readOnly) {
+			new Button({
+				icon: 'close',
+				appendTo: this,
+				onPointerPress: () => this.destroy(),
+			});
+		}
+	}
+
+	static handlers = {
+		textContent(value) {
+			this.elem.setAttribute('data-value', value);
+			this._textSpan.elem.textContent = value;
+		},
+	};
+}
+
+export default Tag;

package/components/TagList/TagList.js

@@ -0,0 +1,118 @@
+import { Component } from '../../Component';
+import { styled } from '../../styled';
+import { Button } from '../Button';
+import { Input } from '../Input';
+
+import Tag from './Tag';
+
+const StyledComponent = styled(
+	Component,
+	() => `
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: 4px;
+		list-style: none;
+		margin: 0;
+		padding: 4px;
+		box-sizing: border-box;
+
+		&.readOnly {
+			pointer-events: none;
+			padding: 0;
+		}
+	`,
+);
+
+const TagListInput = styled(
+	Input,
+	() => `
+		flex: 1;
+		min-width: 80px;
+	`,
+);
+
+const defaultOptions = { readOnly: false };
+
+/**
+ * Interactive tag list component with add/remove functionality and input support.
+ *
+ * Displays a collection of tags with optional editing capabilities including
+ * inline text input for adding new tags and removal buttons for existing tags.
+ * @param {object} [options={}] - TagList configuration options
+ * @param {string} [options.tag='ul'] - HTML tag for the container element
+ * @param {boolean} [options.readOnly=false] - Whether tags can be added/removed
+ * @param {Array<string>} [options.tags] - Initial array of tag text values
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {TagList} TagList component instance
+ */
+class TagList extends StyledComponent {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+
+	constructor(options = {}, ...children) {
+		super({ ...options, tag: 'ul' }, ...children);
+	}
+
+	_addTag(value) {
+		value = (value || '').trim();
+		if (!value) return;
+
+		const existing = Array.from(this.elem.querySelectorAll('li[data-value]')).map(el => el.dataset.value);
+		if (existing.includes(value)) return;
+
+		this.elem.insertBefore(new Tag({ textContent: value }).elem, this.addTag.elem);
+		this.tagInput.elem.value = '';
+		this.tagInput.elem.focus();
+	}
+
+	build() {
+		if (!this.options.readOnly) {
+			this.tagInput = new TagListInput({ placeholder: 'New Tag' });
+
+			this.tagInput.on({
+				targetEvent: 'keyup',
+				callback: e => {
+					if (e.key === 'Enter') this._addTag(this.tagInput.elem.value);
+				},
+			});
+
+			this.addTag = new Tag(
+				{ readOnly: true, addClass: 'add-tag' },
+				this.tagInput,
+				new Button({
+					icon: 'plus',
+					onPointerPress: () => this._addTag(this.tagInput.elem.value),
+				}),
+			);
+
+			this.replaceCleanup('tagListChildren', () => {
+				this.addTag?.destroy?.();
+			});
+		}
+
+		this.append([
+			...(this.options.tags || []).map(textContent => new Tag({ readOnly: this.options.readOnly, textContent })),
+			...(this.addTag ? [this.addTag] : []),
+		]);
+	}
+}
+
+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

@@ -0,0 +1,30 @@
+# TagList
+
+> ./TagList.js
+
+Editable tag collection. The key decision: read-only mode removes the editing interface entirely rather than disabling it; a read-only TagList is structurally simpler, not just interaction-blocked.
+
+## Read-only mode produces a different structure, not just disabled controls
+
+- `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?
+
+## 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
+
+## 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
+
+## 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?

package/components/TagList/index.js

@@ -0,0 +1,2 @@
+export { default as TagList } from './TagList';
+export { default as Tag } from './Tag';

package/components/Tooltip/Tooltip.js

@@ -0,0 +1,139 @@
+import { styled } from '../../styled';
+import { Popover } from '../Popover';
+
+const StyledPopover = styled(
+	Popover,
+	({ colors }) => `
+		position: absolute;
+		padding: 3px;
+		z-index: 1;
+		pointer-events: none;
+		max-width: 240px;
+		margin: auto;
+		background-color: ${colors.white};
+		color: ${colors.black};
+		opacity: 0;
+		transform: scaleX(0);
+		transition: opacity 0.4s, transform 0.1s, overlay 0.4s allow-discrete, display 0.4s allow-discrete;
+		text-indent: 0;
+
+		&:popover-open {
+			opacity: 1;
+			transform: scaleX(1);
+			transition: overlay 0.4s allow-discrete, display 0.4s allow-discrete, opacity 0.4s, transform 0.4s;
+		}
+
+		@starting-style {
+			&:popover-open {
+				opacity: 0;
+				transform: scaleX(-1);
+			}
+		}
+
+		&:before {
+			padding: 0 6px 0 3px;
+		}
+
+		&:empty:before {
+			padding: 0;
+		}
+
+		&.center {
+			top: 2px;
+			left: 50%;
+			transform: translateX(-50%);
+		}
+		&.top {
+			left: 50%;
+			bottom: calc(100% - 3px);
+			transform: translateX(-50%);
+		}
+		&.bottom {
+			left: 50%;
+			top: calc(100% - 3px);
+			transform: translateX(-50%);
+		}
+		&.left {
+			top: 2px;
+			right: calc(100% + 2px);
+		}
+		&.right {
+			top: 2px;
+			left: calc(100% + 2px);
+		}
+		&.topLeft {
+			right: calc(100% - 9px);
+			bottom: calc(100% - 9px);
+		}
+		&.topRight {
+			left: calc(100% - 9px);
+			bottom: calc(100% - 9px);
+		}
+		&.bottomLeft {
+			right: calc(100% - 9px);
+			top: calc(100% - 9px);
+		}
+		&.bottomRight {
+			left: calc(100% - 9px);
+			top: calc(100% - 9px);
+		}
+	`,
+);
+
+const defaultOptions = { position: 'topRight', autoOpen: false };
+
+const position_enum = Object.freeze([
+	'center',
+	'top',
+	'bottom',
+	'left',
+	'right',
+	'topLeft',
+	'topRight',
+	'bottomLeft',
+	'bottomRight',
+]);
+
+/**
+ * Tooltip popover component with configurable positioning and smooth animations.
+ *
+ * Extends Popover to provide tooltip-specific styling and positioning options.
+ * Supports multiple position presets and animated show/hide transitions.
+ * @param {object} [options={}] - Tooltip configuration options
+ * @param {('center'|'top'|'bottom'|'left'|'right'|'topLeft'|'topRight'|'bottomLeft'|'bottomRight')} [options.position='topRight'] - Tooltip position relative to parent
+ * @param {boolean} [options.autoOpen=false] - Whether tooltip opens automatically
+ * @param {string} [options.textContent] - Tooltip text content
+ * @param {string} [options.icon] - Icon to display in tooltip
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Tooltip} Tooltip component instance
+ */
+class Tooltip extends StyledPopover {
+	position_enum = position_enum;
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+
+	constructor(options = {}, ...children) {
+		super(
+			{
+				...defaultOptions,
+				...options,
+				addClass: ['tooltip'].concat(options.addClass),
+			},
+			...children,
+		);
+	}
+
+	static handlers = {
+		position(value) {
+			if (!position_enum.includes(value)) {
+				throw new Error(
+					`"${value}" is not a valid position. The position must be one of the following values: ${position_enum.join(', ')}`,
+				);
+			}
+
+			this.removeClass(...position_enum);
+			this.addClass(value);
+		},
+	};
+}
+
+export default Tooltip;

package/components/Tooltip/Tooltip.lld.md

@@ -0,0 +1,22 @@
+# Tooltip
+
+> ./Tooltip.js
+
+Positioned popover for explanatory text with nine validated position presets. The design decision: `position` is validated immediately on assignment; invalid values fail at the point of use, not when the tooltip is shown.
+
+## Invalid position fails immediately, not on first show
+
+- 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
+
+- 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

package/components/Tooltip/index.js

@@ -0,0 +1 @@
+export { default as Tooltip } from './Tooltip';

package/components/TooltipWrapper/TooltipWrapper.js

@@ -0,0 +1,89 @@
+import { styled } from '../../styled';
+import { Icon } from '../Icon';
+import { Tooltip } from '../Tooltip';
+
+const StyledIcon = styled(
+	Icon,
+	() => `
+		&.has-tooltip {
+			position: relative;
+			display: inline-block;
+
+			&:hover {
+				overflow: visible;
+				vertical-align: top;
+			}
+		}
+	`,
+);
+
+/**
+ * Wrapper component that adds tooltip functionality to any component.
+ *
+ * Extends Icon to provide automatic tooltip management with hover triggers,
+ * positioning, and lifecycle management. Tooltips appear on hover with configurable delay.
+ * @param {object} [options={}] - TooltipWrapper configuration options
+ * @param {string|object} [options.tooltip] - Tooltip text or configuration object
+ * @param {string} [options.icon] - Icon to display in the component
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {TooltipWrapper} TooltipWrapper component instance
+ */
+export default class TooltipWrapper extends StyledIcon {
+	static handlers = {
+		tooltip(value) {
+			if (value == null) return;
+			const tooltipOptions = typeof value === 'object' ? value : { textContent: value };
+
+			if (this._tooltip) {
+				this._tooltip.setOptions(tooltipOptions);
+			} else {
+				this._tooltip = new Tooltip({
+					appendTo: this.elem,
+					...tooltipOptions,
+				});
+
+				this.addClass('has-tooltip');
+
+				this.on({
+					targetEvent: 'pointerover',
+					callback: ({ clientX, clientY }) => {
+						this.tooltipTimeout = setTimeout(() => this._tooltip?.show({ x: clientX, y: clientY }), 700);
+					},
+				});
+
+				this.on({
+					targetEvent: 'pointerout',
+					callback: () => {
+						clearTimeout(this.tooltipTimeout);
+						if (!this.elem.contains(document.activeElement)) this._tooltip?.hide();
+					},
+				});
+
+				this.on({
+					targetEvent: 'focus',
+					callback: () => {
+						clearTimeout(this.tooltipTimeout);
+						const { left, bottom } = this.elem.getBoundingClientRect();
+						this._tooltip?.show({ x: left, y: bottom });
+					},
+				});
+
+				this.on({
+					targetEvent: 'blur',
+					callback: () => {
+						clearTimeout(this.tooltipTimeout);
+						this._tooltip?.hide();
+					},
+				});
+
+				this.replaceCleanup('tooltip', () => {
+					if (this._tooltip) {
+						this._tooltip.destroy?.();
+						this._tooltip = null;
+					}
+					clearTimeout(this.tooltipTimeout);
+				});
+			}
+		},
+	};
+}