@vanilla-bean/components 1.0.0

package/components/Dialog/Dialog.js

@@ -0,0 +1,278 @@
+import { styled } from '../../styled';
+import { Button } from '../Button';
+import { Component } from '../../Component';
+import { Elem } from '../../Elem';
+import { isDev } from '../../utils';
+
+const DialogButton = styled(
+	Button,
+	() => `
+		margin: 4px 4px 4px 0;
+	`,
+);
+
+const size_enum = Object.freeze(['small', 'standard', 'large']);
+const variant_enum = Object.freeze(['info', 'success', 'warning', 'error']);
+
+const defaultOptions = {
+	tag: 'dialog',
+	size: 'small',
+	openOnRender: 16,
+	modal: true,
+	get appendTo() {
+		return document.body;
+	},
+	registeredEvents: new Set(['close']),
+};
+
+/**
+ * Modal and non-modal dialog component with customizable appearance and behavior.
+ *
+ * Provides native HTML dialog functionality with enhanced styling, animations, and configurable
+ * header/body/footer sections. Supports different sizes, color variants, and button configurations.
+ * @param {object} [options] - Dialog configuration options
+ * @param {string} [options.tag] - HTML tag, uses native dialog element
+ * @param {('small'|'standard'|'large')} [options.size] - Dialog size
+ * @param {('info'|'success'|'warning'|'error')} [options.variant] - Color variant
+ * @param {number|boolean} [options.openOnRender] - Auto-open delay in ms, or false to disable
+ * @param {boolean} [options.modal] - Whether to open as modal dialog
+ * @param {string} [options.header] - Header text content
+ * @param {string|Component} [options.body] - Body content
+ * @param {Array<Component>} [options.footer] - Custom footer components
+ * @param {Array<string|object>} [options.buttons] - Button configurations for default footer
+ * @param {Function} [options.onButtonPress] - Handler for button press events
+ * @param {Function} [options.closeDialog] - Custom close function
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Dialog} Dialog component instance
+ */
+class Dialog extends styled(
+	Component,
+	({ colors }) => `
+		background-color: ${colors.darker(colors.gray)};
+		color: ${colors.white};
+		flex-direction: column;
+		padding: 0;
+		margin: 0 auto;
+		border: 1px solid ${colors.alpha(colors.light(colors.teal), 0.6)};
+		box-shadow: 0 8px 40px ${colors.alpha(colors.vantablack, 0.7)};
+		border-radius: 0;
+		top: 50%;
+		transform: translateY(-50%);
+		opacity: 0;
+		transition: display 0.3s allow-discrete, overlay 0.3s allow-discrete;
+		animation: dialogFadeOut 0.3s ease-out forwards;
+
+		&[open] {
+			display: flex;
+			animation: dialogFadeIn 0.3s ease-out forwards;
+		}
+
+		& .header {
+			padding: 8px 12px;
+			font-size: 0.9em;
+			font-weight: 600;
+			color: ${colors.white};
+			background-color: ${colors.alpha(colors.vantablack, 0.25)};
+			border-bottom: 1px solid ${colors.alpha(colors.light(colors.teal), 0.2)};
+			margin: 0;
+		}
+
+		& .content {
+			flex: 1;
+			padding: 12px;
+			overflow: hidden auto;
+		}
+
+		& .footer {
+			border-top: 1px solid ${colors.alpha(colors.white, 0.06)};
+			display: flex;
+			flex-direction: row;
+			align-items: center;
+			justify-content: flex-end;
+			padding: 0 6px;
+			min-height: 40px;
+		}
+
+		&.size-small {
+			width: 420px;
+			height: 210px;
+		}
+
+		&.size-standard {
+			width: 640px;
+			height: 360px;
+		}
+
+		&.size-large {
+			width: 90vw;
+			height: 90vh;
+		}
+
+		&::backdrop {
+			background-color: ${colors.black.setAlpha(0.85)};
+			backdrop-filter: blur(2px);
+		}
+
+		&.variant-info {
+			border-color: ${colors.alpha(colors.blue, 0.6)};
+			& .header { color: ${colors.lighter(colors.blue)}; border-color: ${colors.alpha(colors.blue, 0.2)}; }
+			& .footer button { background-color: ${colors.blue}; }
+		}
+
+		&.variant-success {
+			border-color: ${colors.alpha(colors.green, 0.6)};
+			& .header { color: ${colors.lighter(colors.green)}; border-color: ${colors.alpha(colors.green, 0.2)}; }
+			& .footer button { background-color: ${colors.green}; }
+		}
+
+		&.variant-warning {
+			border-color: ${colors.alpha(colors.yellow, 0.6)};
+			& .header { color: ${colors.lighter(colors.yellow)}; border-color: ${colors.alpha(colors.yellow, 0.2)}; }
+			& .footer button { background-color: ${colors.yellow}; }
+		}
+
+		&.variant-error {
+			border-color: ${colors.alpha(colors.red, 0.6)};
+			box-shadow: 0 0 32px ${colors.alpha(colors.red, 0.14)}, 0 8px 40px ${colors.alpha(colors.vantablack, 0.7)};
+			& .header { color: ${colors.lighter(colors.red)}; border-color: ${colors.alpha(colors.red, 0.2)}; }
+			& .footer button { background-color: ${colors.red}; }
+		}
+
+		@keyframes dialogFadeIn {
+			from { opacity: 0; }
+			to { opacity: 1; }
+		}
+
+		@keyframes dialogFadeOut {
+			from { opacity: 1; }
+			to { opacity: 0; }
+		}
+	`,
+) {
+	variant_enum = variant_enum;
+	size_enum = size_enum;
+
+	static handlers = {
+		openOnRender(value) {
+			const delay = typeof value === 'number' ? value : defaultOptions.openOnRender;
+			const openDelay = value ? setTimeout(() => this.open(), delay) : null;
+			this.replaceCleanup('openOnRender', () => openDelay && clearTimeout(openDelay));
+		},
+		// Claim the key so standard routing doesn't try to call elem.showModal() or set elem.modal.
+		// The value is read directly from this.options.modal in open().
+		modal() {},
+		size(value) {
+			if (value && !size_enum.includes(value)) {
+				throw new Error(
+					`"${value}" is not a valid size. The size must be one of the following values: ${size_enum.join(', ')}`,
+				);
+			}
+
+			this.removeClass(/\bsize-\S+\b/g);
+
+			if (value) this.addClass(`size-${value}`);
+		},
+		variant(value) {
+			if (value && !variant_enum.includes(value)) {
+				throw new Error(
+					`"${value}" is not a valid variant. The variant must be one of the following values: ${variant_enum.join(', ')}`,
+				);
+			}
+
+			this.removeClass(/\bvariant-\S+\b/g);
+
+			if (value) this.addClass(`variant-${value}`);
+		},
+		body(value) {
+			this.body?.content(value);
+		},
+		header(value) {
+			this._header?.content(value);
+		},
+	};
+
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+
+	constructor(options = {}, ...children) {
+		super({ ...defaultOptions, ...options }, ...children);
+
+		this.options['aria-labelledby'] = this.uniqueId;
+	}
+
+	build() {
+		this._header = new Elem({
+			tag: 'div',
+			id: this.uniqueId,
+			addClass: ['header'],
+			content: this.options.header,
+			appendTo: this,
+		});
+
+		this._body = new Elem({ addClass: ['content'], appendTo: this });
+
+		this._footer = new Elem({
+			addClass: ['footer'],
+			append:
+				this.options.footer ||
+				this.options.buttons?.map(
+					button =>
+						new DialogButton({
+							onPointerPress: event =>
+								this.options.onButtonPress?.({
+									event,
+									button,
+									dialog: this,
+									closeDialog: this.options.closeDialog || (() => this.close()),
+								}),
+							...(typeof button === 'object' ? button : { textContent: button }),
+						}),
+				),
+			appendTo: this,
+		});
+	}
+
+	/**
+	 * Content container — primary injection point for subclass and consumer content.
+	 * @returns {Component} The dialog body component
+	 */
+	get body() {
+		return this._body;
+	}
+
+	/**
+	 * Opens the dialog, either as modal or non-modal
+	 * @param {boolean} modal - Whether to open as modal dialog (default: true)
+	 */
+	open(modal = this.options.modal) {
+		this._opener = document.activeElement;
+		try {
+			this.elem[modal ? 'showModal' : 'show']();
+			this._openRetried = false;
+			const focusable = this.elem.querySelector(
+				'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+			);
+			(focusable ?? this.elem).focus();
+		} catch (error) {
+			if (this._openRetried) return;
+
+			this._openRetried = true;
+
+			// eslint-disable-next-line no-console
+			if (isDev) console.error(error, 'Retrying...');
+
+			this.render();
+		}
+	}
+
+	/**
+	 * Closes the dialog with optional return value
+	 * @param {string} returnValue - Value to return when dialog closes
+	 */
+	close(returnValue) {
+		this.elem.close(returnValue);
+		this._opener?.focus();
+		this._opener = null;
+	}
+}
+
+export default Dialog;

package/components/Dialog/Dialog.lld.md

@@ -0,0 +1,20 @@
+# Dialog
+
+> ./Dialog.js
+
+Native `<dialog>` element wrapper. The decision to use the native element rather than a div with ARIA roles means focus trapping, ESC-to-close, and return values are handled by the platform. The component's job is structure and timing, not reimplementing dialog semantics.
+
+## Auto-open delays until the element is in the DOM
+
+- `openOnRender` defaults to a small delay so the dialog is guaranteed to be attached before `showModal()` is called; opening before attachment fails silently
+  - does setting openOnRender: false prevent the dialog from opening on its own?
+
+## Invalid sizes and variants fail loudly rather than rendering in an unknown state
+
+- an unrecognized size or variant throws at the point of assignment, not later when layout breaks
+  - does an unrecognized size value throw?
+
+## Header, body, and footer are stable references — options update them in place
+
+- the structural elements are created once in `build()` and persist across option updates; assigning a new `header` value changes the header's content, not the dialog's structure
+  - does updating the header option change the header's content without replacing the dialog structure?

package/components/Dialog/README.md

@@ -0,0 +1,96 @@
+# Dialog
+
+Modal and non-modal dialog component built on the native `<dialog>` element with animated open/close, configurable sizes, color variants, and flexible button configurations.
+
+## Usage
+
+```js
+import { Dialog } from '@vanilla-bean/components';
+
+const dialog = new Dialog({
+	header: 'Confirm Action',
+	body: 'Are you sure you want to proceed?',
+	buttons: ['Cancel', { text: 'Confirm', variant: 'success' }],
+	onButtonPress: ({ button, closeDialog }) => {
+		console.log('pressed', button);
+		closeDialog();
+	},
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `header` | `string` | — | Text rendered in the `<h2>` header |
+| `body` | `string\|Component\|Array` | — | Content for the scrollable body section. Reactive: updating `options.body` replaces content |
+| `buttons` | `Array<string\|object>` | — | Shorthand footer buttons. Each entry is a string label or `{ textContent, variant?, onPointerPress?, ...buttonOptions }` |
+| `footer` | `Array<Component>` | — | Fully custom footer components. Takes precedence over `buttons` |
+| `onButtonPress` | `Function` | — | Called when any `buttons` entry is pressed. Receives `{ button, closeDialog, event }` |
+| `openOnRender` | `number\|boolean` | `16` | Auto-open delay in ms after render. Set to `false` to disable auto-open |
+| `modal` | `boolean` | `true` | Open as a modal (with backdrop) vs. non-modal |
+| `size` | `string` | `'small'` | Dialog dimensions: `'small'` (420×210px), `'standard'` (840×420px), `'large'` (90vw×90vh) |
+| `variant` | `string` | — | Color theme: `'info'`, `'success'`, `'warning'`, `'error'` |
+| `closeDialog` | `Function` | — | Override the default close behavior used inside `onButtonPress` |
+| `appendTo` | `Element` | `document.body` | Where to append the dialog in the DOM |
+
+### `onButtonPress` callback signature
+
+```js
+onButtonPress: ({ button, closeDialog, event }) => { ... }
+// button      — the original entry from the buttons array (string or object)
+// closeDialog — function that closes the dialog (calls dialog.close() by default)
+// event       — the pointer event that triggered the press
+```
+
+## Methods
+
+```js
+dialog.open(modal?: boolean): void
+// Opens the dialog. Defaults to options.modal. Falls back to re-render on first failure.
+
+dialog.close(returnValue?: string): void
+// Closes the dialog. Passes returnValue to the native dialog close event.
+```
+
+Enums are exposed as instance properties for validation reference:
+
+```js
+dialog.size_enum; // ['small', 'standard', 'large']
+dialog.variant_enum; // ['info', 'success', 'warning', 'error']
+```
+
+## Events
+
+| Event   | Description                                         |
+| ------- | --------------------------------------------------- |
+| `close` | Native dialog close event, registered automatically |
+
+## Example
+
+Dialog with reactive body content loaded asynchronously:
+
+```js
+import { Dialog } from '@vanilla-bean/components';
+import { Button } from '@vanilla-bean/components';
+
+const dialog = new Dialog({
+	header: 'Results',
+	size: 'standard',
+	variant: 'info',
+	body: 'Loading...',
+	buttons: ['Dismiss'],
+	openOnRender: false,
+	onButtonPress: ({ closeDialog }) => closeDialog(),
+});
+
+fetchResults().then(data => {
+	dialog.options.body = data.summary;
+});
+
+new Button({
+	textContent: 'View Results',
+	onPointerPress: () => dialog.open(),
+	appendTo: document.body,
+});
+```

package/components/Dialog/index.js

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

package/components/Form/Form.js

@@ -0,0 +1,257 @@
+import { Oxject } from '@vanilla-bean/oxject';
+import { fromCamelCase, capitalize } from '../../utils';
+import { Component } from '../../Component';
+import { Elem } from '../../Elem';
+import { Input } from '../Input';
+import { Label } from '../Label';
+
+/**
+ * Dynamic form component with reactive data binding, validation, layout groups, and conditional fields.
+ *
+ * Generates form inputs with labels from a configuration array. Each entry in `inputs` is either
+ * a field definition or a group definition.
+ *
+ * **Field definition:**
+ * ```js
+ * {
+ * key: 'name',                          // required — data key
+ * label: 'Full Name',                   // optional — defaults to formatted key
+ * InputComponent: Select,               // optional — defaults to Input
+ * onChange: event => {},                // optional — called after data update
+ * parse: value => value.trim(),         // optional — transform before storing
+ * condition: data => data.type === 'x', // optional — hide field when false
+ * validate: value => value ? null : 'Required', // optional — field-level validator
+ * // ...any other InputComponent options
+ * }
+ * ```
+ *
+ * **Group definition** — renders inputs side-by-side in a layout container:
+ * ```js
+ * {
+ * type: 'group',
+ * style: { display: 'grid', gridTemplateColumns: '1fr 120px', gap: '8px' },
+ * inputs: [ ...field definitions... ],
+ * }
+ * ```
+ *
+ * Groups can be nested. Fields inside groups support `condition` as normal.
+ * When all conditional fields in a group are hidden, the group container is also hidden.
+ * Conditional and invalid fields are excluded from validation when hidden.
+ *
+ * Setting `form.options.inputs = newInputs` rebuilds the form preserving the data store.
+ * @param {object} [options={}] - Form configuration options
+ * @param {Array<object>} options.inputs - Field and group definitions
+ * @param {object} [options.data={}] - Initial form data
+ * @param {...(Component|HTMLElement|string)} children - Appended after generated inputs
+ */
+export default class Form extends Component {
+	build() {
+		if (!this.options.inputs?.length) return;
+
+		this.setStyle({ overflow: 'hidden auto' });
+
+		const currentData = this.options.data ? { ...this.options.data } : {};
+		this.options.data?.destroy?.();
+		this.options.data = new Oxject(currentData);
+		this.replaceCleanup('formData', () => this.options.data?.destroy?.());
+
+		this._resetState();
+		this._processInputs(this.options.inputs, this);
+		this._wireConditions();
+		this._setupAnnouncer();
+	}
+
+	/**
+	 * Rebuild the form when inputs change without recreating the data store.
+	 * Existing data is preserved; new keys are added with their initial values.
+	 */
+	static handlers = {
+		inputs(value) {
+			if (!this.rendered || !value || !this.options.data) return;
+			this.empty();
+			this._resetState();
+			this._processInputs(value, this);
+			this._wireConditions();
+			this._setupAnnouncer();
+		},
+	};
+
+	/** @private */
+	_resetState() {
+		clearTimeout(this._announceTimeout);
+		this._announceTimeout = null;
+		this.inputElements = {};
+		this._conditionals = [];
+		this._conditionalGroups = [];
+		this._fieldValidators = {};
+	}
+
+	/** @private */
+	_wireConditions() {
+		if (!this._conditionals.length) return;
+		const evaluate = () => this._evaluateConditions();
+		this.options.data.addEventListener('set', evaluate);
+		// replaceCleanup — safe to call multiple times (inputs handler re-wires on rebuild)
+		this.replaceCleanup('conditions', () => this.options.data.removeEventListener('set', evaluate));
+	}
+
+	/**
+	 * Recursively processes an input definition array into the given append target.
+	 * Handles both field definitions and group definitions.
+	 * @param {Array<object>} inputs - Field or group definitions
+	 * @param {Component|Elem} appendTarget - Where to append generated elements
+	 * @private
+	 */
+	_processInputs(inputs, appendTarget) {
+		const form = this;
+
+		for (const inputDef of inputs) {
+			if (inputDef.type === 'group') {
+				const group = new Component({ appendTo: appendTarget, style: inputDef.style });
+				const priorConditionalCount = this._conditionals.length;
+				this._processInputs(inputDef.inputs, group);
+				// Track groups that contain conditional fields for container-level hide/show
+				if (this._conditionals.length > priorConditionalCount) {
+					this._conditionalGroups.push(group);
+				}
+				continue;
+			}
+
+			const {
+				key,
+				label,
+				InputComponent = Input,
+				onChange = () => {},
+				parse = value => value,
+				condition,
+				validate,
+				...inputOptions
+			} = inputDef;
+
+			const input = new InputComponent({
+				value: this.options.data.subscriber(key),
+				...(InputComponent !== Component && {
+					onChange: function (event) {
+						form.options.data[key] = this.options.value = parse(event.value, input);
+						this.validate?.();
+						onChange(event);
+					},
+				}),
+				...inputOptions,
+			});
+
+			form.options.data[key] = input.options.value;
+			form.inputElements[key] = input;
+
+			if (validate) form._fieldValidators[key] = validate;
+
+			const isCheckbox = input.options.type === 'checkbox';
+			const wrapper = new Label(
+				typeof label === 'object'
+					? label
+					: { label: label || capitalize(fromCamelCase(key), true), ...(isCheckbox && { variant: 'inline' }) },
+				input,
+			);
+
+			appendTarget.append(wrapper);
+
+			if (condition) {
+				wrapper.elem.style.display = condition(form.options.data) ? '' : 'none';
+				form._conditionals.push({ key, wrapper, condition });
+			}
+		}
+	}
+
+	/** @private */
+	_setupAnnouncer() {
+		if (!this._conditionals.length) return;
+		this._announcer = new Elem({
+			'aria-live': 'polite',
+			'aria-atomic': 'true',
+			style: {
+				position: 'absolute',
+				width: '1px',
+				height: '1px',
+				padding: '0',
+				margin: '-1px',
+				overflow: 'hidden',
+				clip: 'rect(0, 0, 0, 0)',
+				whiteSpace: 'nowrap',
+				border: '0',
+			},
+			appendTo: this,
+		});
+	}
+
+	/**
+	 * Re-evaluates all conditional field and group visibility against current form data.
+	 * Called automatically when any form data key changes.
+	 * @private
+	 */
+	_evaluateConditions() {
+		const newlyVisible = [];
+
+		for (const { wrapper, condition } of this._conditionals) {
+			const wasHidden = wrapper.elem.style.display === 'none';
+			const isVisible = condition(this.options.data);
+			wrapper.elem.style.display = isVisible ? '' : 'none';
+			if (wasHidden && isVisible) {
+				const label = wrapper.elem.querySelector('label')?.textContent?.trim();
+				if (label) newlyVisible.push(label);
+			}
+		}
+
+		// Hide group containers when all their conditional children are hidden
+		for (const group of this._conditionalGroups) {
+			const children = Array.from(group.elem.children);
+			const anyVisible = !children.length || children.some(el => el.style.display !== 'none');
+			group.elem.style.display = anyVisible ? '' : 'none';
+		}
+
+		if (newlyVisible.length && this._announcer) {
+			this._announcer.textContent = '';
+			clearTimeout(this._announceTimeout);
+			this._announceTimeout = setTimeout(() => {
+				if (this._announcer) this._announcer.textContent = `${newlyVisible.join(', ')} now available`;
+			}, 50);
+		}
+	}
+
+	/**
+	 * Validates all visible form inputs and returns whether errors were found.
+	 * Runs both VBC Input validations and field-level `validate` functions from the definition.
+	 * Hidden conditional fields are excluded.
+	 * @param {object} [options] - Validation options passed to individual input validators
+	 * @returns {boolean} True if validation errors exist, false if all visible inputs are valid
+	 */
+	hasErrors(options) {
+		if (!this.inputElements) return false;
+
+		const hiddenKeys = new Set(
+			(this._conditionals || []).filter(({ wrapper }) => wrapper.elem.style.display === 'none').map(({ key }) => key),
+		);
+
+		let hasErrors = false;
+
+		for (const [key, input] of Object.entries(this.inputElements)) {
+			if (hiddenKeys.has(key)) continue;
+
+			if (input?.validate?.(options)) hasErrors = true;
+
+			const fieldValidator = this._fieldValidators?.[key];
+			if (fieldValidator) {
+				const error = fieldValidator(this.options.data[key]);
+				if (error) {
+					input?.addClass?.('validation-errors');
+					input?.elem?.setAttribute('aria-invalid', 'true');
+					hasErrors = true;
+				} else {
+					input?.removeClass?.('validation-errors');
+					input?.elem?.removeAttribute('aria-invalid');
+				}
+			}
+		}
+
+		return hasErrors;
+	}
+}

package/components/Form/Form.lld.md

@@ -0,0 +1,21 @@
+# Form
+
+> ./Form.js
+
+Declarative form from an array of input configurations. The key design decision is that the form owns data binding. Each input's changes update a shared reactive `data` context, and `hasErrors()` validates the whole form in one call.
+
+## Label text falls back to the field key — no separate label required for obvious fields
+
+- if an input config omits `label`, the key name becomes the label
+  - does an input with no label option display the key name as its label?
+
+## hasErrors validates all inputs simultaneously and returns a boolean
+
+- `hasErrors()` runs all validations and returns true if any failed, false if all passed; false means submittable
+  - does hasErrors return false when all inputs are valid?
+  - does hasErrors return true when an input's validation fails?
+
+## Form data is live — changes are visible before any submit action
+
+- each input's value feeds the shared `data` context as it changes
+  - does typing in an input field update the form's data context before any submit?