@vanilla-bean/components 1.0.0

package/components/Form/README.md

@@ -0,0 +1,87 @@
+# Form
+
+Dynamic form component that generates labeled inputs from a configuration array and maintains reactive data state through an Oxject instance.
+
+## Usage
+
+```js
+import { Form } from '@vanilla-bean/components';
+
+const form = new Form({
+	data: { username: '', age: 0 },
+	inputs: [
+		{ key: 'username', validations: [[/.+/, 'Required']] },
+		{ key: 'age', parse: value => parseInt(value, 10) },
+	],
+});
+```
+
+## Options
+
+| Option   | Type            | Default | Description                                                             |
+| -------- | --------------- | ------- | ----------------------------------------------------------------------- |
+| `inputs` | `Array<object>` | —       | Input configuration array; see shape below                              |
+| `data`   | `object`        | `{}`    | Initial form data. Replaced with an `Oxject` instance on each `build()` |
+
+### `inputs` entry shape
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `key` | `string` | required | Key into `options.data` for reading and writing the value |
+| `label` | `string\|object` | auto | Label text. Defaults to a human-readable version of `key` (camelCase converted). Pass an object to forward options to `Label` |
+| `InputComponent` | `Component class` | `Input` | Component class to instantiate. Can be `Select`, `ColorPicker`, or any component that accepts `value` and `onChange` |
+| `onChange` | `Function` | `() => {}` | Called after the data context is updated with the new value |
+| `parse` | `Function(value, input)` | `v => v` | Transforms the raw event value before storing it in `options.data` |
+| `validations` | `Array` | — | Passed directly to the `InputComponent` (see Input validation format) |
+| `...inputOptions` | `any` | — | Any additional options forwarded to the `InputComponent` constructor |
+
+### `data` Oxject lifecycle
+
+On `build()`, any existing `options.data` Oxject instance is destroyed and replaced with a new one wrapping the current data values. Each input subscribes to its key via `options.data.subscriber(key)` so the input value stays reactive. When a user changes a field, `options.data[key]` is updated immediately.
+
+Access live form data at any time via `form.options.data`.
+
+## Methods
+
+```js
+form.validate(options?): boolean
+// Calls validate() on every input element that supports it.
+// Returns true if any validation errors exist, false if the form is valid.
+
+form.inputElements: { [key]: InputComponent }
+// Map of key → input component instances, available after build().
+```
+
+## Events
+
+Individual inputs emit their own events (`onChange`, `onInput`). The Form does not emit top-level events. Listen on `form.options.data` or supply `onChange` per input config.
+
+## Example
+
+Form with mixed input types, custom parse, and submit validation:
+
+```js
+import { Form } from '@vanilla-bean/components';
+import { Select } from '@vanilla-bean/components';
+import { Button } from '@vanilla-bean/components';
+
+const form = new Form(
+	{
+		data: { name: '', role: 'viewer', active: true },
+		inputs: [
+			{ key: 'name', validations: [[/.+/, 'Name is required']] },
+			{ key: 'role', InputComponent: Select, options: ['viewer', 'editor', 'admin'] },
+			{ key: 'active' },
+		],
+	},
+	new Button({
+		textContent: 'Submit',
+		onPointerPress: () => {
+			if (form.validate()) return console.warn('Fix errors before submitting');
+			console.log('Submitting:', { ...form.options.data });
+		},
+	}),
+);
+```
+
+Type auto-detection applies: `name` (string) becomes a text input, `active` (boolean) becomes a checkbox, automatically.

package/components/Form/index.js

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

package/components/Icon/Icon.js

@@ -0,0 +1,54 @@
+import { Component } from '../../Component';
+
+/**
+ * Icon component that renders FontAwesome icons with animation support.
+ *
+ * Automatically applies FontAwesome classes based on icon name and animation.
+ * Handles class management for dynamic icon changes and supports all FontAwesome icon variants.
+ * @param {object} [options={}] - Icon configuration options
+ * @param {string} [options.icon] - FontAwesome icon name (without 'fa-' prefix)
+ * @param {string} [options.animation] - FontAwesome animation name (without 'fa-' prefix)
+ * @param {string} [options.content] - Text content to display alongside icon
+ * @param {string} [options.textContent] - Alternative text content property
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Icon} Icon component instance
+ */
+export default class Icon extends Component {
+	static handlers = {
+		icon() {
+			this._refreshIcon();
+		},
+		animation() {
+			this._refreshIcon();
+		},
+		content(value, next) {
+			next(value);
+			this._refreshIcon();
+		},
+		textContent(value, next) {
+			next(value);
+			this._refreshIcon();
+		},
+	};
+
+	_refreshIcon() {
+		this.removeClass(/\bfa-\S+\b/g);
+
+		const { icon, animation, content, textContent } = this.options;
+
+		if (icon || animation) {
+			this.addClass(
+				...(content || textContent ? [] : ['icon']),
+				...['support', animation, icon].filter(Boolean).map(v => `fa-${v}`),
+			);
+		}
+
+		const interactive = ['button', 'a', 'input', 'select', 'textarea'].includes(this.elem.tagName.toLowerCase());
+		const labeled = this.elem.hasAttribute('aria-label') || this.elem.hasAttribute('aria-labelledby');
+		if (!interactive && !content && !textContent && !labeled) {
+			this.elem.setAttribute('aria-hidden', 'true');
+		} else {
+			this.elem.removeAttribute('aria-hidden');
+		}
+	}
+}

package/components/Icon/Icon.lld.md

@@ -0,0 +1,21 @@
+# Icon
+
+> ./Icon.js
+
+FontAwesome icon wrapper that manages FA class state as options rather than raw class strings. The design decision: callers pass `icon: "star"` and the component owns the full FA class lifecycle; callers never manually add or remove FA classes.
+
+## Changing icon leaves no residual classes from the previous value
+
+- when the icon option changes, all previous FA icon classes are removed before the new one is applied; a caller can freely update the icon option without accumulating stale classes
+  - does an element that had icon 'star' and was updated to 'moon' have only the moon icon?
+
+## Icon-only and icon-with-text render differently without the caller specifying which mode
+
+- when there is no text content, the element receives the `icon` class, which CSS uses for icon-only layout; when text accompanies the icon, that class is absent
+  - does an Icon constructed without text receive the icon-only class?
+  - does an Icon constructed with text not receive the icon-only class?
+
+## Animation and icon are independent options that compose
+
+- setting `animation` applies an animation class independently of `icon`; an Icon with both options active carries both classes simultaneously; they do not interfere
+  - does an Icon with both icon and animation options active carry both classes at the same time?

package/components/Icon/index.js

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

package/components/Input/Input.js

@@ -0,0 +1,173 @@
+import { Component } from '../../Component';
+import { retry } from '../../utils';
+import { updateValidationErrors, insertTabCharacter, adjustIndentation } from './utils';
+
+const type_enum = Object.freeze([
+	'button',
+	'checkbox',
+	'color',
+	'date',
+	'datetime-local',
+	'email',
+	'file',
+	'hidden',
+	'image',
+	'month',
+	'number',
+	'password',
+	'radio',
+	'range',
+	'reset',
+	'search',
+	'submit',
+	'tel',
+	'text',
+	'time',
+	'url',
+	'week',
+]);
+const defaultOptions = {
+	tag: 'input',
+	value: '',
+	autocomplete: 'off',
+	autocapitalize: 'off',
+	autocorrect: 'off',
+	height: 'auto',
+	placeholder: '',
+};
+
+const dataTypeToInputType = { number: 'number', boolean: 'checkbox', string: 'text' };
+
+/**
+ * Versatile input component supporting all HTML input types and textarea functionality.
+ *
+ * Provides enhanced input behavior with auto-height for textareas, syntax highlighting,
+ * validation support, and automatic type detection based on value type.
+ * @param {object} [options={}] - Input configuration options
+ * @param {string} [options.tag='input'] - HTML tag ('input' or 'textarea')
+ * @param {string} [options.type] - Input type, auto-detected from value type if not specified
+ * @param {*} [options.value=''] - Initial input value
+ * @param {string} [options.placeholder=''] - Placeholder text
+ * @param {string} [options.autocomplete='off'] - Autocomplete behavior
+ * @param {string} [options.autocapitalize='off'] - Auto-capitalization behavior
+ * @param {string} [options.autocorrect='off'] - Auto-correction behavior
+ * @param {string|number} [options.height='auto'] - Height for textarea ('auto' for dynamic sizing)
+ * @param {boolean} [options.syntaxHighlighting] - Enable syntax highlighting for textarea
+ * @param {string} [options.language] - Programming language for syntax highlighting
+ * @param {Array<Function>} [options.validations] - Array of validation functions
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Input} Input component instance
+ */
+export default class Input extends Component {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+	type_enum = type_enum;
+
+	constructor(options = {}, ...children) {
+		const rawValue = options.value?.__isDerived ? options.value.toJSON() : options.value;
+		super(
+			{
+				...((options.tag || 'input') === 'input' ? { type: dataTypeToInputType[typeof rawValue] || 'text' } : {}),
+				...defaultOptions,
+				...options,
+			},
+			...children,
+		);
+
+		this.initialValue = this.options.value;
+	}
+
+	build() {
+		if (this.tag === 'textarea' && this.options.syntaxHighlighting) {
+			const handleKeydown = function (event) {
+				if (event.key == 'Tab') {
+					event.preventDefault();
+
+					this.selectionStart === this.selectionEnd && !event.shiftKey
+						? insertTabCharacter(this)
+						: adjustIndentation({ textarea: this, action: event.shiftKey ? 'remove' : 'add' });
+				}
+			};
+
+			this.elem.addEventListener('keydown', handleKeydown);
+			this.replaceCleanup('syntaxHighlightingKeydown', () => this.elem.removeEventListener('keydown', handleKeydown));
+		}
+	}
+
+	static handlers = {
+		height(value) {
+			if (this.tag !== 'textarea') return;
+
+			if (value === 'auto') {
+				this.__updateAutoHeight = () => {
+					this.elem.style.height = this.options.syntaxHighlighting
+						? `calc(${((this.elem.value?.match(/\n/g) || '').length + 1) * 1.19}em + 10px)`
+						: `calc(${((this.elem.value?.match(/\n/g) || '').length + 1) * 1.25}em + 16px)`;
+				};
+
+				this.__debouncedUpdateAutoHeight =
+					this.__debouncedUpdateAutoHeight ||
+					(() => {
+						clearTimeout(this.__autoHeightTimeout);
+						this.__autoHeightTimeout = setTimeout(this.__updateAutoHeight, 16);
+					});
+
+				this.__updateAutoHeight();
+
+				this.elem.addEventListener('input', this.__debouncedUpdateAutoHeight);
+
+				this.replaceCleanup('autoHeight', () => {
+					clearTimeout(this.__autoHeightTimeout);
+					this.elem.removeEventListener?.('input', this.__debouncedUpdateAutoHeight);
+				});
+			} else {
+				this.elem.removeEventListener('input', this.__debouncedUpdateAutoHeight);
+				clearTimeout(this.__autoHeightTimeout);
+
+				this.elem.style.height = typeof value === 'number' ? `${value + 1}em` : value;
+			}
+		},
+		value(value) {
+			if (this.options.type === 'checkbox') this.elem.checked = value;
+			else this.elem.value = value;
+
+			if (this.rendered && this.options.validations?.length) retry(() => this.validate(), { delay: 500, max: 1 });
+		},
+		syntaxHighlighting(value) {
+			this[value ? 'addClass' : 'removeClass']('syntax-highlighting');
+		},
+		language(value) {
+			if (!this.options.syntaxHighlighting) return;
+			this.removeClass(/\blanguage-\S+\b/g);
+			this.addClass(`language-${value}`);
+		},
+	};
+
+	/**
+	 * Checks if the input value has changed from its initial value
+	 * @returns {boolean} True if value is no longer the initial value
+	 */
+	get isDirty() {
+		return this.initialValue !== this.options.value;
+	}
+
+	/**
+	 * Validates the input value against configured validation rules
+	 * @param {object} options - Validation options
+	 * @param {Array} options.validations - Custom validation rules to use
+	 * @param {*} options.value - Custom value
+	 * @returns {Array|undefined} Array of validation errors, or undefined if valid
+	 */
+	validate({ validations, value } = {}) {
+		const errors = updateValidationErrors({
+			elem: this.elem,
+			validations: validations ?? this.options.validations,
+			value: value ?? this.options.value,
+		});
+
+		this[errors ? 'addClass' : 'removeClass']('validation-errors');
+		if (errors) this.elem.setAttribute('aria-invalid', 'true');
+		else this.elem.removeAttribute('aria-invalid');
+
+		return errors;
+	}
+}

package/components/Input/Input.lld.md

@@ -0,0 +1,28 @@
+# Input
+
+> ./Input.js
+
+Input element that infers its type from the value it receives rather than requiring callers to declare it. The deeper design decision is that `isDirty` makes unsaved-change detection a first-class property; forms don't need to track initial values themselves.
+
+## Type is communicated by the value, not by a separate option
+
+- callers pass a value; the input determines its type from that value's type
+  - does a number value produce an input that accepts numeric entry?
+  - does a boolean value produce an input that represents a checked/unchecked state?
+
+## isDirty reflects whether the value has changed from its initial state
+
+- the initial value is recorded at construction; `isDirty` answers "has the user changed this?" without external tracking
+  - does isDirty return false when the value matches the initial value?
+  - does isDirty return true after the value has been changed?
+
+## Validation errors are surfaced as element state, not return values
+
+- when a validation fails, the element enters an error state that CSS can target; passing clears it
+  - does a failing validation leave the input in an error state?
+  - does a passing validation clear the error state?
+
+## Textarea height follows content automatically
+
+- when `tag: 'textarea'`, the element resizes to fit its content without the caller managing height
+  - does a textarea grow taller when its content exceeds its current height?

package/components/Input/README.md

@@ -0,0 +1,97 @@
+# Input
+
+Versatile input component supporting all HTML input types, textarea with auto-height, syntax highlighting, validation, and automatic type detection from value type.
+
+## Usage
+
+```js
+import { Input } from '@vanilla-bean/components';
+
+const input = new Input({
+	type: 'text',
+	value: 'hello',
+	placeholder: 'Enter text...',
+	onChange: ({ value }) => console.log(value),
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tag` | `string` | `'input'` | HTML tag: `'input'` or `'textarea'` |
+| `type` | `string` | auto-detected | Input type (see `type_enum`). Auto-detected from value: `number` → `'number'`, `boolean` → `'checkbox'`, `string` → `'text'` |
+| `value` | `any` | `''` | Initial value. Setting `options.value` reactively updates the element |
+| `placeholder` | `string` | `''` | Placeholder text |
+| `autocomplete` | `string` | `'off'` | Native autocomplete attribute |
+| `autocapitalize` | `string` | `'off'` | Native autocapitalize attribute |
+| `autocorrect` | `string` | `'off'` | Native autocorrect attribute |
+| `height` | `string\|number` | `'auto'` | Height for textarea. `'auto'` dynamically sizes to content; a number sets `em` units |
+| `syntaxHighlighting` | `boolean` | — | Adds `syntaxHighlighting` class and Tab key indentation handling (textarea only) |
+| `language` | `string` | — | Adds `language-<value>` class for Prism-compatible highlighting (requires `syntaxHighlighting`) |
+| `validations` | `Array` | — | Validation rules; see Validation section below |
+| `onInput` | `Function` | — | Called on every keystroke with an enhanced event containing `.value` |
+| `onChange` | `Function` | — | Called on change with an enhanced event containing `.value` |
+| `onKeyUp` | `Function` | — | Called on keyup with an enhanced event containing `.value` |
+
+### Supported `type` values
+
+`button`, `checkbox`, `color`, `date`, `datetime-local`, `email`, `file`, `hidden`, `image`, `month`, `number`, `password`, `radio`, `range`, `reset`, `search`, `submit`, `tel`, `text`, `time`, `url`, `week`
+
+### Validation rule format
+
+Each entry in `validations` is a tuple: `[test, message]`
+
+- `test`: a `RegExp` tested against the value, or a `Function(value) => boolean` (truthy = error)
+- `message`: a `string` or `Function() => string` describing the error
+
+```js
+validations: [
+	[/.+/, 'This field is required'],
+	[/^.{3,20}$/, 'Must be 3–20 characters'],
+	[value => value === 'forbidden', 'That value is not allowed'],
+];
+```
+
+Validation errors are applied to the underlying element via `setCustomValidity` and the `validationErrors` CSS class is toggled on the component.
+
+## Methods
+
+```js
+input.validate({ validations?, value? }): Array | undefined
+// Runs validation rules. Returns array of error messages if invalid, undefined if valid.
+// Calling with no args uses options.validations and options.value.
+
+input.isDirty: boolean  // getter — true if current value differs from the initial value
+```
+
+## Events
+
+Input components emit enhanced native events. All handlers (`onInput`, `onChange`, `onKeyUp`, etc.) receive a standard DOM event augmented with a `.value` property containing the current input value.
+
+The `close` event is registered by default via `registeredEvents`.
+
+## Example
+
+Textarea with auto-height and syntax highlighting:
+
+```js
+import { Input } from '@vanilla-bean/components';
+
+const editor = new Input({
+	tag: 'textarea',
+	height: 'auto',
+	syntaxHighlighting: true,
+	language: 'javascript',
+	value: 'const x = 1;',
+	validations: [[/.+/, 'Editor must not be empty']],
+	onChange: ({ value }) => {
+		editor.options.value = value;
+		const errors = editor.validate();
+		if (errors) console.warn(errors);
+	},
+	appendTo: document.body,
+});
+```
+
+Tab and shift-Tab adjust indentation within the textarea when `syntaxHighlighting` is enabled.

package/components/Input/index.js

@@ -0,0 +1,2 @@
+export { default as Input } from './Input';
+export * from './utils';

package/components/Input/utils.js

@@ -0,0 +1,122 @@
+import { Component } from '../../Component';
+import { styled } from '../../styled';
+import { Button } from '../Button';
+import { Popover } from '../Popover';
+
+export const InputValidationError = styled(
+	Component,
+	({ colors }) => `
+		background-color: ${colors.red};
+		padding: 6px;
+		margin: 3px;
+		border-radius: 3px;
+	`,
+);
+
+export const updateValidationErrors = ({ elem, validations, value }) => {
+	if (!validations?.length) return;
+
+	// Destroy previous validation components before re-evaluating
+	const parent = elem.parentElement;
+	if (parent) {
+		parent.querySelectorAll('[data-validation-error]').forEach(el => {
+			el._component?.destroy?.() ?? el._elem?.destroy?.() ?? el.remove();
+		});
+	}
+
+	const errors = [];
+
+	validations.forEach(([validation, message]) => {
+		const isValid = validation instanceof RegExp ? validation.test(value) : validation(value);
+
+		const resolvedMessage = typeof message == 'function' ? message(value) : message;
+
+		if (!isValid) {
+			errors.push(resolvedMessage);
+			const validationError = new InputValidationError({ content: resolvedMessage });
+			validationError.elem.dataset.validationError = '';
+
+			const [inputLabel] = elem.parentElement.getElementsByTagName('label');
+
+			if (inputLabel) {
+				const errorPopover = new Popover({ autoOpen: false, state: 'auto' });
+				errorPopover.elem.dataset.validationError = '';
+				elem.parentElement.insertBefore(errorPopover.elem, elem);
+
+				const errorButton = new Button({
+					appendTo: inputLabel,
+					icon: 'exclamation',
+					styles: ({ colors }) => ({
+						marginLeft: '6px',
+						width: '18px',
+						height: '18px',
+						fontSize: '12px',
+						padding: 0,
+						backgroundColor: colors.red,
+					}),
+					onPointerPress: event => errorPopover.show({ x: event.clientX, y: event.clientY }),
+				});
+				errorButton.elem.dataset.validationError = '';
+
+				errorPopover.append(validationError.elem);
+			}
+
+			// Insert directly before the input element in case there are other stacked elements
+			else elem.parentElement.insertBefore(validationError.elem, elem);
+		}
+	});
+
+	return errors.length > 0 ? errors : undefined;
+};
+
+export const insertTabCharacter = input => {
+	const { value, selectionEnd } = input;
+
+	input.value = `${value.slice(0, Math.max(0, selectionEnd))}\t${value.slice(Math.max(0, selectionEnd))}`;
+	input.selectionStart = input.selectionEnd = selectionEnd + 1;
+};
+
+export const adjustIndentation = ({ textarea, action = 'add' }) => {
+	const { value, selectionStart, selectionEnd } = textarea;
+	const remove = action === 'remove';
+
+	const startLine = value.slice(0, Math.max(0, selectionStart)).split('\n').length - 1;
+	const endLine = value.slice(0, Math.max(0, selectionEnd)).split('\n').length - 1;
+
+	let modifiedStartLine = false;
+	let modifiedLines = 0;
+
+	const updateLine = (line, index) => {
+		if (remove) {
+			if (!/^\t/.test(line)) return line;
+
+			++modifiedLines;
+			if (index === startLine) modifiedStartLine = true;
+			return line.replace(/^\t/, '');
+		}
+
+		++modifiedLines;
+		if (index === startLine) modifiedStartLine = true;
+		return `\t${line}`;
+	};
+
+	const newValue = value
+		.split('\n')
+		.map((line, index) => (index >= startLine && index <= endLine ? updateLine(line, index) : line))
+		.join('\n');
+
+	const changedText = value !== newValue;
+
+	if (!changedText) {
+		textarea.selectionStart = selectionStart;
+		textarea.selectionEnd = selectionEnd;
+		return;
+	}
+
+	textarea.value = newValue;
+
+	const selectionModification = remove ? -1 : 1;
+
+	textarea.selectionStart = selectionStart + (modifiedStartLine ? selectionModification : 0);
+	textarea.selectionEnd = selectionEnd + modifiedLines * selectionModification;
+};

package/components/Keyboard/Key.js

@@ -0,0 +1,38 @@
+import { styled } from '../../styled';
+import { Button } from '../Button';
+
+const StyledButton = styled(
+	Button,
+	() => `
+		user-select: none;
+		display: inline-block;
+		border: none;
+		padding: 0;
+		border-radius: unset;
+		margin-bottom: 1px;
+		margin-right: 1px;
+		height: 32px;
+		flex: 1;
+
+		${[1.25, 1.5, 1.75, 2, 2.25, 2.75, 6, 6.25, 7]
+			.map(unit => `&.u${unit.toString().replace('.', '_')} { flex: ${unit}; }`)
+			.join('\n\t\t')}
+	`,
+);
+
+class Key extends StyledButton {
+	constructor(options = {}, ...children) {
+		const { key, text, class: keyClass, ...optionsWithoutConfig } = options;
+
+		super(
+			{
+				textContent: text ?? key,
+				...optionsWithoutConfig,
+				addClass: [key, keyClass].concat(options.addClass),
+			},
+			...children,
+		);
+	}
+}
+
+export default Key;