@vanilla-bean/components 1.0.0

package/components/Keyboard/Keyboard.js

@@ -0,0 +1,173 @@
+import { tactileResponse } from '../../utils';
+import { styled } from '../../styled';
+import { Component } from '../../Component';
+import Key from './Key';
+
+const KeyRow = styled(
+	Component,
+	() => `
+		display: flex;
+	`,
+);
+
+/**
+ * Virtual keyboard component with customizable layouts and tactile feedback.
+ *
+ * Provides touch-friendly keyboard interface with predefined layouts (simple, number)
+ * and configurable key definitions. Supports layout switching and key event handling.
+ * @param {object} [options={}] - Keyboard configuration options
+ * @param {string} [options.layout='simple'] - Initial keyboard layout name
+ * @param {boolean} [options.tactileResponse=true] - Whether to provide haptic feedback on key press
+ * @param {object} [options.keyDefinitions] - Key configuration object mapping key names to definitions
+ * @param {object} [options.layouts] - Layout configuration object mapping layout names to key arrays
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Keyboard} Keyboard component instance
+ */
+class Keyboard extends Component {
+	constructor(options = {}, ...children) {
+		super(
+			{
+				layout: 'simple',
+				tactileResponse: true,
+				keyDefinitions: {
+					simple: { text: 'ABC' },
+					number: { text: '123' },
+					shift: { class: 'u1_5' },
+					return: { class: 'u1_5' },
+					backspace: { class: 'u1_5' },
+					clear: { class: 'u1_5' },
+					done: { class: 'u1_5' },
+					exponent: { key: 'e', text: 'e', class: 'u1_5' },
+					space: { key: ' ', text: ' ', class: 'u6' },
+				},
+				layouts: {
+					simple: [
+						['simple', 'number'],
+						['q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p'],
+						['a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l'],
+						['shift', 'z', 'x', 'c', 'v', 'b', 'n', 'm', 'backspace'],
+						[',', '.', 'space', '!', 'return'],
+					],
+					number: [
+						['simple', 'number'],
+						['1', '2', '3', 'backspace'],
+						['4', '5', '6', 'clear'],
+						['7', '8', '9', 'done'],
+						['.', '0', '-', 'exponent'],
+					],
+				},
+				...options,
+			},
+			...children,
+		);
+
+		this.setLayout(this.options.layout);
+	}
+
+	static handlers = {
+		// Claim these keys so standard routing doesn't try to assign them as elem properties.
+		// Both are read directly from this.options in setLayout() and key resolution.
+		layouts() {},
+		keyDefinitions() {},
+		layout(value) {
+			this.setLayout(value);
+		},
+	};
+
+	// todo native keyboard events https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent
+
+	/**
+	 * Switches the keyboard to the specified layout and rebuilds the keys.
+	 * @param {string} name - Layout name to switch to
+	 */
+	setLayout(name) {
+		const rows = this.options.layouts[name];
+
+		if (typeof name !== 'string' || !rows) return;
+
+		this.children.forEach(child => child.destroy?.());
+		this.empty();
+		this.removeClass(/\blayout-\S+\b/g).addClass(`layout-${name}`);
+
+		rows.forEach(columns => {
+			const row = new KeyRow({ appendTo: this });
+
+			columns.forEach(key => {
+				let keyDefinition = this.options.keyDefinitions[key];
+
+				if (!keyDefinition) {
+					Object.entries(this.options.keyDefinitions).forEach(([keyName, definition]) => {
+						if (!keyName.startsWith('^') || !keyName.endsWith('$')) return;
+
+						if (new RegExp(keyName, 'i').test(key)) keyDefinition = definition;
+					});
+				}
+
+				new Key({
+					key,
+					...keyDefinition,
+					appendTo: row,
+					onPointerDown: event => {
+						if (this.options.tactileResponse) tactileResponse();
+
+						this.emit('keyDown', {
+							event,
+							key: keyDefinition?.key || key,
+							keyDefinition,
+							target: event.target?._component,
+						});
+					},
+					onPointerUp: event =>
+						this.emit('keyUp', {
+							event,
+							key: keyDefinition?.key || key,
+							keyDefinition,
+							target: event.target?._component,
+						}),
+					onPointerPress: event =>
+						this.emit('keyPress', {
+							event,
+							key: keyDefinition?.key || key,
+							keyDefinition,
+							target: event.target?._component,
+						}),
+				});
+			});
+		});
+	}
+
+	/**
+	 * Registers a callback for key down events.
+	 * @param {Function} callback - Event handler function
+	 * @returns {Function} Unsubscribe function
+	 */
+	onKeyDown(callback) {
+		this.addEventListener('keyDown', callback);
+
+		return () => this.removeEventListener('keyDown', callback);
+	}
+
+	/**
+	 * Registers a callback for key up events.
+	 * @param {Function} callback - Event handler function
+	 * @returns {Function} Unsubscribe function
+	 */
+	onKeyUp(callback) {
+		this.addEventListener('keyUp', callback);
+
+		return () => this.removeEventListener('keyUp', callback);
+	}
+
+	/**
+	 * Registers a callback for key press events.
+	 * @param {Function} callback - Event handler function
+	 * @returns {Function} Unsubscribe function
+	 */
+	onKeyPress(callback) {
+		this.addEventListener('keyPress', callback);
+
+		return () => this.removeEventListener('keyPress', callback);
+	}
+}
+
+export default Keyboard;

package/components/Keyboard/Keyboard.lld.md

@@ -0,0 +1,21 @@
+# Keyboard
+
+> ./Keyboard.js
+
+On-screen keyboard where layout switching rebuilds the key DOM rather than showing/hiding rows. The decision: a clean rebuild on layout change is safer than managing per-key visibility across layout transitions; no key from one layout can bleed into another.
+
+## Layout switch produces only keys from the new layout — no residual keys remain
+
+- changing `layout` removes all existing keys and builds the new set from scratch; a key that exists in layout A but not layout B is definitively absent after the switch
+  - does switching layout remove keys from the previous layout?
+  - does the new layout's keys appear after switching?
+
+## Key events carry the key definition alongside the key name
+
+- `keyDown`, `keyUp`, and `keyPress` emit with both the key name and its configuration object, so handlers can respond to semantic meaning rather than just the character pressed
+  - does a key press event include the definition object for that key?
+
+## Regex-named keys match families of keys to one definition
+
+- a key definition whose name is a regex pattern matches all physical keys that satisfy it; modifier handling and key families are expressed as patterns, not enumerated one by one
+  - does a key matching a regex definition trigger that definition's behavior?

package/components/Keyboard/index.js

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

package/components/Label/Label.js

@@ -0,0 +1,214 @@
+import { styled } from '../../styled';
+import { Component } from '../../Component';
+import { TooltipWrapper } from '../TooltipWrapper';
+
+const StyledLabel = styled(
+	TooltipWrapper,
+	({ colors, fonts }) => `
+		position: relative;
+		display: inline-block;
+		font-size: 1em;
+		width: calc(100% - 24px);
+		margin: 0 0 6px;
+		padding: 6px 12px 6px 12px;
+		background-color: ${colors.white.setAlpha(0.04)};
+		color: ${colors.white};
+		transition: all 0.5s;
+
+		&:after {
+			transition: all 0.5s;
+		}
+
+		& label {
+			display: block;
+			margin: 0;
+			color: ${colors.white};
+			padding-left: 3px;
+		}
+
+		&.variant-overlay {
+			& label {
+				position: relative;
+				z-index: 1;
+				transform: translate(0, 0);
+				transition: transform 0.5s, color 0.5s;
+			}
+
+			& input {
+				transform: translate(0, 0);
+				transition: transform 0.5s;
+			}
+		}
+
+		&.variant-overlay:not(:focus-within):has(input:placeholder-shown) {
+			& label {
+				pointer-events: none;
+				color: ${colors.gray};
+				transform: translate(12px, 20px);
+			}
+
+			& input {
+				transform: translate(0, -12px);
+			}
+		}
+
+		&.variant-inline, &.variant-inline-after {
+			display: flex;
+
+			& label {
+				display: inline-block;
+				vertical-align: top;
+				margin-top: 5px;
+				margin-right: 9px;
+				line-height: 2;
+			}
+
+			& input:not([type=checkbox]), & textarea, & select {
+				flex: 1;
+			}
+		}
+
+		&.variant-inline-after {
+			& label {
+				margin-left: 9px;
+				margin-right: 0;
+			}
+		}
+
+		&.variant-collapsible {
+			border: 2px solid ${colors.lighter(colors.teal).setAlpha(0.5)};
+			border-radius: 3px;
+
+			&.collapsed {
+				width: 50%;
+
+				& > label {
+					color: ${colors.superWhite};
+
+					&:before {
+						content: "" !important;
+						opacity: 1;
+						color: ${colors.lightest(colors.blue)};
+					}
+				}
+
+				& > *:not(label) {
+					display: none !important;
+				}
+			}
+
+			& > label {
+				cursor: pointer;
+
+				&:before {
+					${fonts.fontAwesomeSolid}
+
+					content: "";
+					opacity: 0.5;
+					font-size: 14px;
+					padding-right: 6px;
+					color: ${colors.white};
+
+					transition: opacity 0.8s, color 1s;
+				}
+			}
+		}
+
+		& > *:not(label):not(.tooltip) {
+			margin-top: 6px;
+		}
+	`,
+);
+
+const variant_enum = Object.freeze(['overlay', 'collapsible', 'inline', 'inline-after', 'simple']);
+
+const defaultOptions = { variant: 'simple' };
+
+/**
+ * Label component with multiple display variants and input association.
+ *
+ * Provides flexible label styling with support for overlay, collapsible, inline, and simple variants.
+ * Automatically associates with input components and supports interactive collapsible behavior.
+ * @param {object|string} [options={}] - Label configuration options, or label text string
+ * @param {('overlay'|'collapsible'|'inline'|'inline-after'|'simple')} [options.variant='simple'] - Label display variant
+ * @param {string|object} [options.label] - Label text content or label component options
+ * @param {Component|string} [options.for] - Input component or ID to associate label with
+ * @param {boolean} [options.collapsed] - Whether collapsible variant starts collapsed
+ * @param {string} [options.tooltip] - Tooltip text for the label
+ * @param {...(Component|HTMLElement|string)} children - Child elements, typically input components
+ * @returns {Label} Label component instance
+ */
+class Label extends StyledLabel {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+	variant_enum = variant_enum;
+
+	constructor(options = {}, ...children) {
+		if (typeof options === 'string') options = { label: options };
+
+		super(
+			{
+				...(children.length > 0 && { for: children[0] }),
+				...defaultOptions,
+				...options,
+			},
+			...children,
+		);
+	}
+
+	build() {
+		this._labelText = new Component({ tag: 'label' });
+
+		const handleClick = () => {
+			if (this.options.variant !== 'collapsible') return;
+			const nowCollapsed = !this.hasClass('collapsed');
+			this[nowCollapsed ? 'addClass' : 'removeClass']('collapsed');
+			this._labelText.elem.setAttribute('aria-expanded', nowCollapsed ? 'false' : 'true');
+		};
+
+		this._labelText.elem.addEventListener('click', handleClick);
+		this.addCleanup('labelClick', () => this._labelText.elem.removeEventListener('click', handleClick));
+
+		if (this.options.variant === 'collapsible') {
+			this._labelText.elem.setAttribute('aria-expanded', this.options.collapsed ? 'false' : 'true');
+		}
+
+		this[this.options.variant === 'inline-after' ? 'append' : 'prepend'](this._labelText);
+	}
+
+	static handlers = {
+		label(value) {
+			if (typeof value === 'object') this._labelText?.setOptions(value);
+			else if (this._labelText) this._labelText.options.content = value;
+		},
+		collapsed(value) {
+			this[value ? 'addClass' : 'removeClass']('collapsed');
+			if (this.options.variant === 'collapsible' && this._labelText) {
+				this._labelText.elem.setAttribute('aria-expanded', value ? 'false' : 'true');
+			}
+		},
+		variant(value) {
+			this.removeClass(/\bvariant-\S+\b/g);
+			this.addClass(`variant-${value}`);
+
+			if (this._labelText) {
+				const shouldBeAfter = value === 'inline-after';
+				const isAfter = this._labelText.elem === this.elem.lastElementChild;
+				if (shouldBeAfter !== isAfter) this[shouldBeAfter ? 'append' : 'prepend'](this._labelText);
+				if (value === 'collapsible') {
+					this._labelText.elem.setAttribute('aria-expanded', this.hasClass('collapsed') ? 'false' : 'true');
+				}
+			}
+		},
+		for(value) {
+			let forId = typeof value === 'string' ? value : value?.id || value?.elem?.id;
+
+			if (!forId && value?._component) {
+				forId = value.elem.id = value.uniqueId;
+			}
+
+			if (this._labelText) this._labelText.elem.htmlFor = forId ?? '';
+		},
+	};
+}
+
+export default Label;

package/components/Label/Label.lld.md

@@ -0,0 +1,20 @@
+# Label
+
+> ./Label.js
+
+Labeling wrapper with five structural variants. The key decision is that `variant` selects a DOM structure, not just a CSS class; each variant builds a different composition of elements suited to its use case.
+
+## Each variant applies a distinct class that drives its CSS behavior
+
+- 'collapsible', 'overlay', 'inline', 'inline-after', and 'simple' each apply their own class to the component element; swapping `variant` changes the class and the structural CSS rules that attach to it
+  - does the 'collapsible' variant produce a clickable element that shows and hides content?
+
+## Collapsed state is externally controllable, not just toggle-driven
+
+- `collapsed: true` sets the initial collapsed state; assigning to it later expands or collapses programmatically without simulating user interaction
+  - does setting collapsed: true hide the wrapped content?
+  - does setting collapsed: false after construction show the previously hidden content?
+
+## Overlay label visibility is driven by CSS pseudo-class, not JavaScript
+
+- the overlay variant's label visibility responds to whether the input has content via the `:placeholder-shown` pseudo-class; the component adds the structural class and the CSS handles the rest

package/components/Label/index.js

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

package/components/Link/Link.js

@@ -0,0 +1,43 @@
+import { TooltipWrapper } from '../TooltipWrapper';
+
+const defaultOptions = {
+	tag: 'a',
+	variant: 'link',
+	get tooltip() {
+		return { icon: 'link', style: { fontSize: '12px' } };
+	},
+};
+const variant_enum = Object.freeze(['link', 'button']);
+
+/**
+ * Link component with tooltip support and display variants.
+ *
+ * Extends TooltipWrapper to provide enhanced anchor elements with automatic tooltip icons
+ * and configurable styling variants for different use cases.
+ * @param {object} [options={}] - Link configuration options
+ * @param {string} [options.tag='a'] - HTML tag, defaults to anchor element
+ * @param {string} [options.variant='link'] - Link display variant ('link', 'button')
+ * @param {string} [options.href] - URL to link to
+ * @param {string} [options.target] - Link target attribute
+ * @param {string} [options.textContent] - Link text content
+ * @param {object|string} [options.tooltip] - Tooltip configuration or text
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Link} Link component instance
+ */
+class Link extends TooltipWrapper {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+	variant_enum = variant_enum;
+
+	constructor(options = {}, ...children) {
+		super({ ...defaultOptions, ...options }, ...children);
+	}
+
+	static handlers = {
+		variant(value) {
+			this.removeClass(/\bvariant-\S+\b/g);
+			this.addClass(`variant-${value}`);
+		},
+	};
+}
+
+export default Link;

package/components/Link/Link.lld.md

@@ -0,0 +1,15 @@
+# Link
+
+> ./Link.js
+
+Anchor element with optional button styling. The decision: `variant: 'button'` changes Link's appearance but not its element; it remains an anchor, preserving right-click, middle-click, open-in-tab, and keyboard semantics that a styled div cannot provide.
+
+## Button variant changes appearance without surrendering anchor semantics
+
+- a Link with `variant: 'button'` looks like a button but behaves like a link; it is still an anchor element, which is what provides right-click menus, keyboard focus, and tab semantics natively
+  - does a Link with variant 'button' remain an anchor element?
+
+## Tooltip includes a link icon automatically
+
+- when a tooltip string is provided, the tooltip is configured with a link icon alongside the text
+  - does a Link's tooltip show a link icon alongside the provided tooltip text?

package/components/Link/index.js

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

package/components/List/List.js

@@ -0,0 +1,82 @@
+import { Component } from '../../Component';
+import { styled } from '../../styled';
+import { TooltipWrapper } from '../TooltipWrapper';
+
+const StyledComponent = styled(
+	Component,
+	() => `
+		margin: 6px 0;
+		padding-left: 32px;
+
+		&.no-style {
+			padding-left: 0;
+			list-style: none;
+
+			& li {
+				line-height: 1;
+				text-indent: 0;
+			}
+		}
+	`,
+);
+
+const ListItem = styled(
+	TooltipWrapper,
+	() => `
+		line-height: 1.3;
+		text-indent: 6px;
+	`,
+);
+
+/**
+ * List component for rendering unordered lists with customizable list items.
+ *
+ * Provides dynamic list rendering with support for custom ListItemComponent classes
+ * and flexible item configuration. Automatically wraps items in styled list item elements.
+ * @param {object} [options={}] - List configuration options
+ * @param {string} [options.tag='ul'] - HTML tag for the list container
+ * @param {Array<*>} [options.items] - Array of list items to render
+ * @param {Component} [options.ListItemComponent] - Custom component class for rendering items
+ * @param {boolean} [options.noStyle] - Whether to apply no-style class for plain list
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {List} List component instance
+ */
+export default class List extends StyledComponent {
+	constructor(options = {}, ...children) {
+		super(
+			{
+				...options,
+				tag: 'ul',
+			},
+			...children,
+		);
+	}
+
+	static handlers = {
+		noStyle(value) {
+			this.toggleClass('no-style', !!value);
+		},
+		items(value) {
+			if (!value) {
+				this.empty();
+				return;
+			}
+
+			this.content(
+				value.map(item => {
+					const isContent = typeof item === 'string' || item?.elem || Array.isArray(item);
+					const listItem = new ListItem({ tag: 'li', ...item?.listItemOptions });
+
+					if (this.options.ListItemComponent) {
+						listItem.content(new this.options.ListItemComponent(isContent ? { content: item } : item));
+					} else if (item.ListItemComponent) {
+						listItem.content(new item.ListItemComponent(item));
+					} else if (isContent) listItem.content(item);
+					else listItem.setOptions(item);
+
+					return listItem;
+				}),
+			);
+		},
+	};
+}

package/components/List/List.lld.md

@@ -0,0 +1,19 @@
+# List
+
+> ./List.js
+
+Flexible list that meets items where they are. The core design decision: items can be strings, DOM nodes, component instances, or configuration objects; the component figures out what to do with each format. Callers don't normalize data before passing it.
+
+## Items render correctly regardless of their input format
+
+- a single `items` array can contain mixed formats without error
+  - does a List render a mix of string and object items without failing?
+
+## Per-item component overrides compose cleanly with the global default
+
+- the component set globally on the list applies to all items; a per-item `ListItemComponent` overrides for that item only
+  - does a per-item ListItemComponent render that item differently from the default?
+
+## noStyle opts out of default list chrome for embedding contexts
+
+- `noStyle: true` removes bullets, padding, and line-height defaults via a CSS class so the embedding layout can control spacing

package/components/List/index.js

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