@vanilla-bean/components 1.0.0

package/components/Menu/Menu.js

@@ -0,0 +1,93 @@
+import { styled } from '../../styled';
+import { List } from '../List';
+
+const StyledList = styled(
+	List,
+	({ colors }) => `
+		margin: 0;
+		padding: 0;
+		list-style: none;
+
+		& li {
+			cursor: pointer;
+			padding: 6px 6px 9px 6px;
+			border-bottom: 1px solid ${colors.light(colors.gray)};
+
+			&:last-of-type, &:last-of-type > a {
+				border-bottom: none !important;
+			}
+
+			&:hover, &:focus, &:focus-visible, & a:hover, & a:focus, & a:focus-visible  {
+				color: ${colors.light(colors.blue)} !important;
+				border-color: ${colors.light(colors.blue)};
+			}
+
+			&:focus-visible, & a:focus-visible {
+				outline: 2px solid ${colors.light(colors.blue)};
+				outline-offset: -2px;
+			}
+		}
+	`,
+);
+
+/**
+ * Menu component for displaying interactive navigation or selection lists.
+ *
+ * Extends List component with menu-specific styling including hover effects,
+ * borders, and click handling. Provides consistent menu appearance and behavior.
+ * @param {object} [options={}] - Menu configuration options
+ * @param {Array<*>} [options.items] - Array of menu items to render
+ * @param {Function} [options.onSelect] - Handler called when menu item is selected
+ * @param {Component} [options.ListItemComponent] - Custom component class for rendering menu items
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Menu} Menu component instance
+ */
+export default class Menu extends StyledList {
+	static handlers = {
+		items(value, next) {
+			next(value);
+			if (!value) return;
+			const items = Array.from(this.elem.children).filter(el => el.tagName === 'LI');
+			items.forEach((li, i) => li.setAttribute('tabindex', i === 0 ? '0' : '-1'));
+		},
+	};
+
+	constructor(options = {}, ...children) {
+		super({ role: 'menu', ...options, onPointerPress: options.onSelect }, ...children);
+
+		this.on({
+			targetEvent: 'keydown',
+			callback: e => {
+				const items = Array.from(this.elem.children).filter(el => el.tagName === 'LI');
+				if (!items.length) return;
+
+				const currentIndex = items.indexOf(document.activeElement);
+				let next = null;
+
+				if (e.key === 'ArrowDown') {
+					e.preventDefault();
+					next = items[(currentIndex + 1) % items.length];
+				} else if (e.key === 'ArrowUp') {
+					e.preventDefault();
+					next = items[(currentIndex - 1 + items.length) % items.length];
+				} else if (e.key === 'Home') {
+					e.preventDefault();
+					next = items[0];
+				} else if (e.key === 'End') {
+					e.preventDefault();
+					next = items[items.length - 1];
+				} else if ((e.key === 'Enter' || e.key === ' ') && currentIndex >= 0) {
+					e.preventDefault();
+					this.options.onSelect?.(e);
+					return;
+				}
+
+				if (next) {
+					items.forEach(item => item.setAttribute('tabindex', '-1'));
+					next.setAttribute('tabindex', '0');
+					next.focus();
+				}
+			},
+		});
+	}
+}

package/components/Menu/Menu.lld.md

@@ -0,0 +1,15 @@
+# Menu
+
+> ./Menu.js
+
+Styled list whose items trigger an `onSelect` callback. The design decision: Menu routes selection through the same unified pointer+keyboard activation path as Button; keyboard and pointer users get the same experience without separate handlers.
+
+## Selecting a menu item works the same way regardless of input method
+
+- clicking, touching, Space/Enter, and screen reader activation all invoke `onSelect`; one handler, no separate keyboard path
+  - does clicking a menu item invoke onSelect?
+
+## Menu renders any item format that List supports
+
+- strings, objects with labels, and component instances all work as menu items
+  - does a Menu with mixed string and object items render without error?

package/components/Menu/index.js

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

package/components/Notify/Notify.js

@@ -0,0 +1,96 @@
+import { styled } from '../../styled';
+import { Popover } from '../Popover';
+
+const type_enum = Object.freeze(['info', 'success', 'warning', 'error']);
+
+const StyledPopover = styled(
+	Popover,
+	({ colors, fonts }) => `
+		&:before {
+			${fonts.fontAwesomeSolid};
+
+			position: relative;
+			pointer-events: none;
+			padding: 0 9px 0 0;
+		}
+
+		&.info {
+			background-color: ${colors.blackish(colors.blue)};
+			border-color: ${colors.light(colors.blue)};
+
+			&:before {
+				color: ${colors.light(colors.blue)};
+			}
+		}
+
+		&.success {
+			background-color: ${colors.blackish(colors.green)};
+			border-color: ${colors.light(colors.green)};
+
+			&:before {
+				color: ${colors.light(colors.green)};
+			}
+		}
+
+		&.warning {
+			background-color: ${colors.blackish(colors.yellow)};
+			border-color: ${colors.light(colors.yellow)};
+
+			&:before {
+				color: ${colors.light(colors.yellow)};
+			}
+		}
+
+		&.error {
+			background-color: ${colors.blackish(colors.red)};
+			border-color: ${colors.light(colors.red)};
+
+			&:before {
+				color: ${colors.light(colors.red)};
+			}
+		}
+	`,
+);
+
+/**
+ * Notification popover component with type-based styling and auto-dismiss functionality.
+ *
+ * Extends Popover to provide notification-specific behavior including automatic icons,
+ * color-coded styling based on notification type, and optional timeout dismissal.
+ * @param {object} [options={}] - Notify configuration options
+ * @param {string} [options.type='success'] - Notification type ('info', 'success', 'warning', 'error')
+ * @param {string|Component} [options.content] - Notification content to display
+ * @param {number} [options.timeout] - Auto-dismiss timeout in milliseconds
+ * @param {string} [options.icon] - Custom icon name, defaults to type-appropriate icon
+ * @param {number} [options.x] - X position for the notification
+ * @param {number} [options.y] - Y position for the notification
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Notify} Notify component instance
+ */
+export default class Notify extends StyledPopover {
+	type_enum = type_enum;
+
+	constructor(options = {}) {
+		const { timeout, type = 'success' } = options;
+		const icon =
+			options.icon ||
+			{ info: 'circle-info', success: 'check', warning: 'triangle-exclamation', error: 'skull-crossbones' }[type];
+
+		super({
+			role: type === 'error' || type === 'warning' ? 'alert' : 'status',
+			'aria-atomic': 'true',
+			onPointerPress: e => {
+				if (!e.target.closest('button, [role="button"]')) this.destroy();
+			},
+			state: 'manual',
+			...options,
+			addClass: [type].concat(options.addClass),
+			icon,
+		});
+
+		if (timeout) {
+			this.timeout = setTimeout(() => this.destroy(), timeout);
+			this.addCleanup('timeout', () => clearTimeout(this.timeout));
+		}
+	}
+}

package/components/Notify/Notify.lld.md

@@ -0,0 +1,20 @@
+# Notify
+
+> ./Notify.js
+
+Transient notification that self-destructs. The design choice is that click-to-dismiss is always on; every notification is interactive, not a passive message. The `type` option drives icon and color selection so callers communicate intent rather than manually picking icons.
+
+## Type communicates intent; the component selects the appropriate icon
+
+- callers pass `type: 'error'` and the component picks the matching icon; a custom `icon` option overrides this only when the standard mapping doesn't fit
+  - does a success notification use a visually distinct icon from an error notification?
+
+## Clicking anywhere on the notification dismisses it — the whole surface is the target
+
+- notifications are temporary and should be easy to clear; there is no separate close button
+  - does clicking the notification body remove it from the page?
+
+## Manual dismiss cancels a pending timeout — no duplicate destroy fires
+
+- when a `timeout` is set and the user dismisses manually before it fires, the timer is cancelled so a second destroy call after the component is already gone cannot happen
+  - does manually dismissing a notification before its timeout prevent a second dismiss?

package/components/Notify/index.js

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

package/components/Page/Page.js

@@ -0,0 +1,67 @@
+import { appendStyles, shimCSS } from '../../styled';
+import { Component } from '../../Component';
+
+const dependentStyleSheets = ['@fortawesome/fontawesome-free/css/all.css', '@fontsource-variable/kode-mono/index.css'];
+
+shimCSS({ styles: ({ page }) => page });
+
+/**
+ * Page component that provides full-page layout with automatic stylesheet loading.
+ *
+ * Serves as a root container for applications with automatic loading of required stylesheets
+ * including FontAwesome and fonts. Provides full viewport sizing and flexible layout.
+ * @param {object} [options={}] - Page configuration options
+ * @param {Array<string|object>} [options.styleSheets=[]] - Additional stylesheets to load
+ * @param {object} [options.style] - Additional CSS styles to apply
+ * @param {string} [options.autoRender='onload'] - When to auto-render the page
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Page} Page component instance
+ */
+class Page extends Component {
+	constructor(options = {}, ...children) {
+		const { styleSheets = [], ...optionsWithoutConfig } = options;
+
+		[...dependentStyleSheets, ...styleSheets].forEach(styleSheet => {
+			if (!styleSheet) return;
+
+			const { href, scope, id } = typeof styleSheet === 'object' ? styleSheet : { href: styleSheet };
+
+			if (scope) {
+				fetch(href)
+					.then(r => r.text())
+					.then(css => appendStyles(`${scope} { ${css} }`, id || scope));
+
+				return;
+			}
+
+			const existingLink = document.querySelector(`link[rel="stylesheet"][href="${href}"]`);
+
+			if (existingLink) return;
+
+			const newLink = document.createElement('link');
+
+			newLink.rel = 'stylesheet';
+			newLink.href = href;
+
+			document.head.append(newLink);
+		});
+
+		super(
+			{
+				...optionsWithoutConfig,
+				style: {
+					position: 'relative',
+					display: 'flex',
+					flexDirection: 'column',
+					width: '100%',
+					height: '100%',
+					...options.style,
+				},
+				autoRender: 'onload',
+			},
+			...children,
+		);
+	}
+}
+
+export default Page;

package/components/Page/Page.lld.md

@@ -0,0 +1,20 @@
+# Page
+
+> ./Page.js
+
+Top-level layout component that takes ownership of stylesheet loading. The design decision: Page loads FontAwesome and typography as part of mounting; application code does not import or configure these separately.
+
+## Required stylesheets load once — remounting does not re-fetch
+
+- Page checks whether each stylesheet is already present before injecting; remounting in a single-page app does not duplicate link elements or re-trigger network requests
+  - does mounting a Page a second time leave the stylesheet count unchanged?
+
+## External stylesheets fetch and inject as style content, not link elements
+
+- `styleSheets` URLs are fetched at mount time and their content is injected as `<style>` elements, avoiding cross-origin link restrictions
+  - does a stylesheet URL's content appear in the document as an inline style element?
+
+## Page sets a full-height flex baseline at construction
+
+- height: 100% and flex display are applied as inline styles at construction
+  - does a Page element have height: 100% applied at construction?

package/components/Page/index.js

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

package/components/Popover/Popover.js

@@ -0,0 +1,175 @@
+import { styled } from '../../styled';
+import { Icon } from '../Icon';
+
+const StyledIcon = styled(
+	Icon,
+	({ colors }) => `
+		position: absolute;
+		background-color: ${colors.darkest(colors.gray)};
+		color: ${colors.white};
+		padding: 12px;
+		border: 1px solid ${colors.lightest(colors.gray)};
+		border-radius: 3px;
+		margin: 0;
+
+		&:popover-open {
+			display: flex;
+		}
+	`,
+);
+
+const defaultOptions = {
+	uniqueId: true,
+	state: 'manual',
+	outsideClose: false,
+	get viewport() {
+		return document.documentElement;
+	},
+	get appendTo() {
+		return document.body;
+	},
+};
+const state_enum = Object.freeze(['auto', 'manual']);
+
+/**
+ * Popover component using native HTML popover API with edge-aware positioning.
+ *
+ * Provides positioned overlay content with automatic edge detection and placement adjustment.
+ * Supports manual and automatic dismiss behavior with customizable positioning and sizing.
+ * @param {object} [options={}] - Popover configuration options
+ * @param {string} [options.state='manual'] - Popover state ('auto', 'manual')
+ * @param {boolean} [options.autoOpen=true] - Whether to automatically open on render
+ * @param {number} [options.x] - X position for the popover
+ * @param {number} [options.y] - Y position for the popover
+ * @param {number} [options.maxWidth=264] - Maximum width in pixels
+ * @param {number} [options.maxHeight=132] - Maximum height in pixels
+ * @param {HTMLElement} [options.viewport] - Viewport element for edge detection
+ * @param {string} [options.icon] - Icon to display in the popover
+ * @param {string|Component} [options.content] - Popover content
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Popover} Popover component instance
+ */
+export default class Popover extends StyledIcon {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+	state_enum = state_enum;
+
+	constructor({ autoOpen = true, onConnected: userOnConnected, ...options } = {}, ...children) {
+		super(
+			{
+				...defaultOptions,
+				onConnected: () => {
+					if (autoOpen) {
+						const timeoutId = setTimeout(() => this.show(), 200);
+						this.replaceCleanup('autoOpen', () => clearTimeout(timeoutId));
+					}
+					userOnConnected?.();
+				},
+				...options,
+			},
+			...children,
+		);
+
+		if (this.options.x !== undefined && this.options.y !== undefined) this.edgeAwarePlacement(this.options);
+	}
+
+	static handlers = {
+		state(value) {
+			this.elem.popover = value;
+		},
+	};
+
+	edgeAwarePlacement({
+		x,
+		y,
+		maxHeight = this.options.maxHeight ?? 132,
+		maxWidth = this.options.maxWidth ?? 264,
+		padding = 24,
+		viewport = this.options.viewport || this.options.appendTo,
+	}) {
+		const { left, bottom, right } = (viewport?.elem ?? viewport).getBoundingClientRect();
+
+		const cursorOffset = 12;
+
+		let pastRight = x + maxWidth + padding >= right;
+		const pastLeft = x - maxWidth + padding <= left;
+		const pastBottom = y + maxHeight + padding >= bottom;
+		// const pastTop = y - maxHeight + padding <= top;
+
+		if (pastLeft && pastRight) {
+			x = padding;
+			pastRight = false;
+		}
+
+		this.elem.style.maxWidth = `${maxWidth}px`;
+		this.elem.style.maxHeight = `${maxHeight}px`;
+		this.elem.style.top = pastBottom ? 'unset' : `${y + cursorOffset}px`;
+		this.elem.style.bottom = pastBottom ? `${document.documentElement.clientHeight + cursorOffset - y}px` : 'unset';
+		this.elem.style.left = pastRight ? 'unset' : `${x + cursorOffset}px`;
+		this.elem.style.right = pastRight ? `${document.documentElement.clientWidth + cursorOffset - x}px` : 'unset';
+	}
+
+	/**
+	 * Shows the popover with optional position update.
+	 * @param {object} [options] - Position and sizing options
+	 */
+	show(options) {
+		if (options) this.edgeAwarePlacement(options);
+
+		if (!this.elem.isConnected) return;
+
+		this.elem.showPopover();
+
+		if (this.options.outsideClose) {
+			// Cancel any pending registration from a previous show()
+			if (this._outsideDismissRaf) cancelAnimationFrame(this._outsideDismissRaf);
+			if (this._outsideDismissListener) {
+				document.removeEventListener('pointerdown', this._outsideDismissListener, { capture: true });
+			}
+
+			const onOutsidePress = e => {
+				if (!this.elem.contains(e.target)) this.hide();
+			};
+
+			this._outsideDismissListener = onOutsidePress;
+
+			// Defer one frame so the current press that opened us isn't immediately caught
+			this._outsideDismissRaf = requestAnimationFrame(() => {
+				this._outsideDismissRaf = null;
+				document.addEventListener('pointerdown', onOutsidePress, { capture: true });
+			});
+		}
+	}
+
+	/**
+	 * Hides the popover.
+	 */
+	hide() {
+		try {
+			this.elem.hidePopover();
+		} catch {
+			// Popover not shown or not connected
+		}
+
+		if (this._outsideDismissRaf) {
+			cancelAnimationFrame(this._outsideDismissRaf);
+			this._outsideDismissRaf = null;
+		}
+		if (this._outsideDismissListener) {
+			document.removeEventListener('pointerdown', this._outsideDismissListener, { capture: true });
+			this._outsideDismissListener = null;
+		}
+	}
+
+	/**
+	 * Checks if the popover is currently open.
+	 * @returns {boolean} True if popover is open
+	 */
+	get isOpen() {
+		return this.elem.matches(':popover-open');
+	}
+
+	destroy() {
+		this.hide();
+		super.destroy?.();
+	}
+}

package/components/Popover/Popover.lld.md

@@ -0,0 +1,19 @@
+# Popover
+
+> ./Popover.js
+
+Native popover element with edge-aware placement. The design decision: position is calculated at show time, not at construction; the popover adapts to wherever in the viewport it needs to appear, at the moment it appears.
+
+## Placement adapts to viewport edges at the moment of showing
+
+- when the popover would overflow an edge, the position flips; this calculation runs on each `show()` call so it stays accurate as the page scrolls or resizes
+
+## autoOpen fires after a short delay, not immediately
+
+- `autoOpen: true` queues `show()` after 200ms; failing immediately would break when the popover's anchor isn't yet in the DOM
+  - does a popover with autoOpen not open synchronously on construction?
+  - does cancelling the popover before 200ms prevent it from opening?
+
+## Manual and auto state are distinct dismiss models
+
+- `state: 'auto'` delegates dismiss to the platform's native light-dismiss; `state: 'manual'` requires explicit `close()`; the choice belongs to the use site

package/components/Popover/index.js

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

package/components/RadioButton/RadioButton.js

@@ -0,0 +1,108 @@
+import { styled } from '../../styled';
+import { Component } from '../../Component';
+
+const RadioButtonLabel = styled(
+	Component,
+	({ colors }) => `
+		line-height: 1.1;
+		display: grid;
+		grid-template-columns: 1em auto;
+		gap: 0.5em;
+		width: fit-content;
+		cursor: pointer;
+
+		&:focus-within {
+			color: ${colors.blue};
+		}
+
+		& + label {
+			margin-top: 1em;
+		}
+	`,
+);
+
+const RadioButtonInput = styled(
+	Component,
+	({ colors }) => `
+		/* Remove most all native input styles */
+		appearance: none;
+
+		margin: 0;
+		font: inherit;
+		color: currentColor;
+		width: 1.15em;
+		height: 1.15em;
+		border: 0.15em solid currentColor;
+		border-radius: 50%;
+		transform: translateY(-0.075em);
+		display: grid;
+		place-content: center;
+		cursor: pointer;
+
+		&:before {
+			content: "";
+			width: 0.65em;
+			height: 0.65em;
+			border-radius: 50%;
+		}
+
+		&:checked:before {
+			box-shadow: inset 1em 1em ${colors.blue};
+		}
+
+		&:focus-visible {
+			outline: 2px solid ${colors.blue};
+			outline-offset: 2px;
+		}
+	`,
+);
+
+/**
+ * Radio button group component with custom styled radio inputs.
+ *
+ * Renders a group of radio button options with consistent styling and behavior.
+ * Each radio button is properly labeled and grouped for exclusive selection.
+ * @param {object} [options={}] - RadioButton configuration options
+ * @param {Array<string|object>} [options.options] - Array of radio button options
+ * @param {*} [options.value] - Currently selected value
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {RadioButton} RadioButton component instance
+ */
+class RadioButton extends Component {
+	static handlers = {
+		options(value) {
+			this.empty();
+
+			if (!value) return;
+
+			this.append(
+				value.map(
+					option =>
+						new RadioButtonLabel({
+							tag: 'label',
+							append: [
+								new RadioButtonInput({
+									tag: 'input',
+									type: 'radio',
+									value: option?.value || option,
+									name: this.uniqueId,
+									checked: this.options.value === (option?.value || option),
+									onChange: event => {
+										if (event.target.checked) this.options.value = event.target.value;
+									},
+								}),
+								option?.label || option,
+							],
+						}),
+				),
+			);
+		},
+		value(value) {
+			this.elem.querySelectorAll('input[type="radio"]').forEach(input => {
+				input.checked = input.value === String(value);
+			});
+		},
+	};
+}
+
+export default RadioButton;

package/components/RadioButton/RadioButton.lld.md

@@ -0,0 +1,15 @@
+# RadioButton
+
+> ./RadioButton.js
+
+Radio group from an array of options. The design decision: the HTML `name` coordination that makes radios mutually exclusive is handled automatically; callers pass values and get a working group without managing name attributes.
+
+## All radios in the group share one name — mutual exclusivity is provided by the browser
+
+- the component generates a shared `name` attribute; the browser enforces that only one radio in the group can be checked at a time
+  - does each radio input in the group share the same name attribute?
+
+## Options can separate their stored value from their display label
+
+- a string option uses its value as both the label and stored datum; an object with `label` and `value` lets them differ, useful when the stored value (an ID, a code) would be confusing as a visible label
+  - does an object option with a separate label display the label rather than the raw value?

package/components/RadioButton/index.js

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