@vanilla-bean/components 1.0.0

package/components/Router/README.md

@@ -0,0 +1,160 @@
+# Router
+
+Hash-based client-side router that maps URL fragments to component classes. Each route pattern maps to a view class; the Router instantiates the matching view and destroys the previous one on navigation.
+
+## Usage
+
+```js
+import { Router, View, Page } from '@vanilla-bean/components';
+
+class HomeView extends View {
+	build() {
+		// render view content here — no Page needed, the shell provides it
+	}
+}
+
+class UserView extends View {
+	build() {
+		// route parameters from /users/:id are passed as options
+		console.log(this.options.id);
+	}
+}
+
+class NotFoundView extends View {
+	build() {
+		// 404 content
+	}
+}
+
+const page = new Page({ title: 'My App', appendTo: document.body });
+
+new Router({
+	views: {
+		'/': HomeView,
+		'/users/:id': UserView,
+	},
+	defaultPath: '/',
+	notFound: NotFoundView,
+	appendTo: page,
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `views` | `object` | — | **Required.** Maps route patterns to component classes. Patterns may contain `:param` segments. |
+| `defaultPath` | `string` | First key of `views` | Route used when the hash is empty and for fallback on unmatched routes. |
+| `notFound` | `typeof Component` | — | Component class rendered when no route matches and `defaultPath` fallback also fails. Receives `{ route }` as an option. |
+| `onRenderView` | `Function` | — | Called with the matched route string whenever a new view is rendered. |
+| `mode` | `'hash' \| 'history'` | `'hash'` | `'hash'` uses URL fragments (`#/path`). `'history'` uses `pushState` and real pathnames (`/path`). History mode requires the server to serve `index.html` for all routes. |
+
+## Properties
+
+```js
+router.path; // string — current URL hash, stripped of '#/', '/', and query strings
+router.path = '/users/42'; // navigate; sets window.location.hash and re-renders
+
+router.route; // string — the matched route pattern for the current path (e.g. '/users/:id')
+router.currentRoute; // string — the last successfully rendered route pattern
+```
+
+## Methods
+
+```js
+router.parseRouteParameters(path?: string): object
+// Extracts named :param segments from a path.
+// Defaults to the current path if none is provided.
+// '/users/42' against '/users/:id' → { id: '42' }
+
+router.pathToRoute(path: string): string
+// Returns the matching route pattern for a path, or the path itself if no pattern matches.
+```
+
+## Route patterns
+
+Routes are matched using exact string equality first, then by replacing `:param` segments with a capture regex. When multiple parameterized patterns could match, routes with fewer `:param` segments are tested first, more specific patterns win without relying on object key order.
+
+```js
+views: {
+  '/users/new':    NewUserView,   // exact match — always wins
+  '/users/:id':    UserView,      // one param — tested before /:section/:id
+  '/:section/:id': SectionView,   // two params — tested last
+}
+```
+
+Query strings are stripped before matching: `#/users/42?sort=name` resolves to `/users/42`.
+
+## Route parameters
+
+Segments prefixed with `:` in the pattern are extracted and passed as options to the rendered view class:
+
+```js
+views: { '/users/:id': UserView }
+
+// Navigating to #/users/42 renders: new UserView({ id: '42', appendTo: this.elem })
+class UserView extends View {
+  build() {
+    console.log(this.options.id); // '42'
+  }
+}
+```
+
+## Navigation behavior
+
+- **Same-route navigation is a no-op.** Navigating to the already-active route does not destroy and rebuild the view. View state is preserved.
+- **Empty hash** uses `defaultPath`. The hash is set and a re-render is triggered.
+- **Unmatched routes** fall back to `defaultPath` first, then `notFound` if `defaultPath` also fails.
+- The Router listens to both `popstate` and `hashchange`, and the browser back/forward buttons work without any extra setup.
+
+## View base class
+
+`View` is a styled `Component` exported alongside `Router`. It fills its container (`width: 100%; height: 100%; display: flex; flex-direction: column; flex: 1`) and is intended as the base class for route views, but is not required. Any `Component` subclass works as a view.
+
+```js
+import { Router, View } from '@vanilla-bean/components';
+
+class SettingsView extends View {
+	build() {
+		/* ... */
+	}
+}
+```
+
+## Example — full SPA shell
+
+```js
+import { Router, View, Nav, NavItem, Page } from '@vanilla-bean/components';
+
+class HomeView extends View {
+	build() {
+		new Component({ textContent: 'Home content', appendTo: this });
+	}
+}
+
+class ArticleView extends View {
+	build() {
+		new Component({ textContent: `Article: ${this.options.slug}`, appendTo: this });
+	}
+}
+
+// Page is the app shell — Router and Nav live inside it, not inside each view
+const page = new Page({ title: 'My App', appendTo: document.body });
+
+const router = new Router({
+	views: {
+		'/': HomeView,
+		'/articles/:slug': ArticleView,
+	},
+	defaultPath: '/',
+	appendTo: page,
+});
+
+new Nav({
+	appendTo: page,
+	append: [
+		new NavItem({ textContent: 'Home', onPointerPress: () => (router.path = '/') }),
+		new NavItem({ textContent: 'Latest', onPointerPress: () => (router.path = '/articles/latest') }),
+	],
+});
+```

package/components/Router/Router.js

@@ -0,0 +1,150 @@
+import { Component } from '../../Component';
+import { routeToRegex } from './utils';
+
+/**
+ * Client-side router component with hash-based or history API routing and dynamic view rendering.
+ *
+ * Provides single-page application routing with support for route parameters,
+ * dynamic view rendering, and browser history integration.
+ * @param {object} [options={}] - Router configuration options
+ * @param {object} options.views - Object mapping route patterns to component classes
+ * @param {string} [options.defaultPath] - Default route path, uses first view key if not specified
+ * @param {Component} [options.notFound] - Component class for 404/not found routes
+ * @param {Function} [options.onRenderView] - Callback fired when rendering a new view
+ * @param {'hash'|'history'} [options.mode='hash'] - Routing mode: 'hash' uses URL fragments, 'history' uses pushState
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Router} Router component instance
+ */
+class Router extends Component {
+	constructor(options = {}, ...children) {
+		super(
+			{
+				defaultPath: Object.keys(options.views)[0],
+				...options,
+				style: {
+					display: 'flex',
+					flex: 1,
+					overflow: 'hidden',
+					...options.style,
+				},
+			},
+			...children,
+		);
+	}
+
+	/**
+	 * Gets the current path from the URL.
+	 * @returns {string} Current route path
+	 */
+	get path() {
+		if (this.options.mode === 'history') return window.location.pathname;
+
+		return window.location.hash.replace(/^#\/?/, '/').replace(/\?.*$/, '');
+	}
+
+	/**
+	 * Sets the current path and triggers view rendering.
+	 * @param {string} path - New route path to navigate to
+	 */
+	set path(path) {
+		if (this.options.mode === 'history') {
+			window.history.pushState(null, '', path);
+		} else {
+			window.location.hash = path;
+		}
+
+		this.renderView();
+	}
+
+	/**
+	 * Gets the matched route for the current path.
+	 * @returns {string} Matched route pattern
+	 */
+	get route() {
+		return this.pathToRoute(this.path);
+	}
+
+	pathToRoute(path) {
+		if (this.options.views[path]) return path;
+
+		const sorted = Object.keys(this.options.views).sort((a, b) => {
+			const aParams = (a.match(/:/g) || []).length;
+			const bParams = (b.match(/:/g) || []).length;
+			return aParams !== bParams ? aParams - bParams : b.length - a.length;
+		});
+
+		return sorted.find(route => routeToRegex(route).test(path)) || path;
+	}
+
+	/**
+	 * Extracts route parameters from a path.
+	 * @param {string} [path] - Path to parse, defaults to current path
+	 * @returns {object} Object containing route parameters
+	 */
+	parseRouteParameters(path = this.path) {
+		const route = this.pathToRoute(path);
+		const routeRegex = routeToRegex(route);
+		let routeParameterValues = path.match(routeRegex);
+		let routeParameterKeys = route.match(routeRegex);
+		const parameters = {};
+
+		if (!routeParameterValues || !routeParameterKeys) return parameters;
+
+		routeParameterValues = routeParameterValues.slice(1);
+		routeParameterKeys = routeParameterKeys.slice(1);
+
+		routeParameterValues.forEach((parameter, index) => {
+			const name = routeParameterKeys[index].slice(1);
+
+			parameters[name] = parameter;
+		});
+
+		return parameters;
+	}
+
+	build() {
+		const reRenderView = () => this.renderView();
+
+		window.addEventListener('popstate', reRenderView);
+		if (this.options.mode !== 'history') window.addEventListener('hashchange', reRenderView);
+		this.replaceCleanup('popstate', () => {
+			window.removeEventListener('popstate', reRenderView);
+			if (this.options.mode !== 'history') window.removeEventListener('hashchange', reRenderView);
+		});
+
+		this.renderView();
+	}
+
+	renderView(route = this.route || this.options.defaultPath) {
+		if (this.currentRoute === route) return;
+
+		this.options.onRenderView?.(route);
+
+		this.view?.destroy?.();
+		this.empty();
+
+		if (!this.path) return (this.path = route);
+
+		this.currentRoute = route;
+
+		if (this.options.views[route]) {
+			this.view = new this.options.views[route]({ appendTo: this.elem, ...this.parseRouteParameters() });
+		} else if (this.options.notFound) this.view = new this.options.notFound({ appendTo: this.elem, route });
+		else if (this.options.defaultPath && this.path !== this.options.defaultPath) this.path = this.options.defaultPath;
+	}
+}
+
+export default Router;
+
+// Zero-arg scenarios for LLD verification
+export const hashStripsQueryString = () => {
+	const r = new Router({ views: { '/path': Component }, autoRender: false });
+	window.location.hash = '#/path?query=1&sort=name';
+	return r.path;
+};
+
+export const paramExtractedFromRoute = () => {
+	const r = new Router({ views: { '/users/:id': Component }, autoRender: false });
+	window.location.hash = '#/users/42';
+	return r.parseRouteParameters('/users/42')?.id;
+};

package/components/Router/Router.lld.md

@@ -0,0 +1,31 @@
+# Router
+
+> ./Router.js
+
+Hash-based router that maps URL fragments to component classes. The design decision: navigating to the current route is a no-op; the active view is not destroyed and rebuilt when the URL doesn't change.
+
+## Query strings are stripped before route matching
+
+**method:** `hashStripsQueryString`
+
+- `#/path?foo=bar` matches the `/path` route; query strings are stripped before matching so callers write route patterns without accounting for query parameters
+  - hashStripsQueryString() → "/path"
+
+## Route parameters are extracted and passed to the rendered view
+
+**method:** `paramExtractedFromRoute`
+
+- patterns like `/users/:id` match `/users/42` and produce `{ id: '42' }` for the view without any URL parsing at the view level
+  - paramExtractedFromRoute() → "42"
+
+## Same-route navigation does not rebuild the view
+
+- if the new hash resolves to the same route as what's currently rendered, the component skips re-render
+- this preserves view state across same-route navigations without the caller guarding against them
+  - does navigating to the currently active route leave the rendered view unchanged?
+
+## Unmatched routes fall back rather than rendering nothing
+
+- an unmatched hash tries `defaultPath` before showing the notFound component
+- the notFound component is only shown when no fallback matches either
+  - does navigating to an unknown route eventually show the notFound component?

package/components/Router/View.js

@@ -0,0 +1,15 @@
+import { Component } from '../../Component';
+import { styled } from '../../styled';
+
+const View = styled(
+	Component,
+	() => `
+		height: 100%;
+		width: 100%;
+		display: flex;
+		flex-direction: column;
+		flex: 1;
+	`,
+);
+
+export default View;

package/components/Router/index.js

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

package/components/Router/utils.js

@@ -0,0 +1,17 @@
+export const routeToPath = (route, parameters) => {
+	let path = route;
+
+	if (parameters) {
+		Object.keys(parameters).forEach(key => {
+			path = path.replace(new RegExp(`:${key}`), parameters[key]);
+		});
+	} else {
+		path = path.replaceAll(/\/?:[^/]+/g, '');
+	}
+
+	return path;
+};
+
+export const routeToRegex = route => {
+	return new RegExp(`^${route.replaceAll(/:[^/]+/g, '([^/]+)')}$`);
+};

package/components/Select/README.md

@@ -0,0 +1,88 @@
+# Select
+
+Select dropdown component extending Input, with dynamic option rendering and enhanced value access for both string and object-based option lists.
+
+## Usage
+
+```js
+import { Select } from '@vanilla-bean/components';
+
+const select = new Select({
+	options: ['one', 'two', 'three'],
+	value: 'two',
+	onChange: ({ value }) => console.log('selected:', value),
+});
+```
+
+## Options
+
+Select inherits all options from `Input`. Key additions:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options` | `Array<string\|object>` | — | List of selectable options. See shape below. Reactive: reassigning `options.options` rebuilds the `<option>` elements |
+| `value` | `any` | — | Currently selected value. Matched against option `value` attributes |
+| `onChange` | `Function` | — | Called with an enhanced event containing `.value` (the selected value string) on change |
+
+All other `Input` options (`placeholder`, `validations`, `onInput`, etc.) are available but less commonly used with Select.
+
+### `options` entry shape
+
+Each entry in the `options` array is either:
+
+- A **string**: used as both the `label` and `value` of the `<option>` element
+- An **object**: spread directly onto the `<option>` element. Common fields:
+
+| Field      | Type      | Description                               |
+| ---------- | --------- | ----------------------------------------- |
+| `value`    | `any`     | The value submitted/returned on selection |
+| `label`    | `string`  | Display text shown in the dropdown        |
+| `disabled` | `boolean` | Disables this specific option             |
+
+```js
+options: ['plain string', { label: 'Display Text', value: 42 }, { label: 'Unavailable', value: 'x', disabled: true }];
+```
+
+## Methods
+
+```js
+select.value          // getter — returns value, label, or textContent of the selected <option>
+select.value = newVal // setter — sets elem.value directly
+
+// Inherited from Input:
+select.validate({ validations?, value? }): Array | undefined
+select.isDirty: boolean
+```
+
+### Relationship to Input
+
+`Select` extends `Input` and overrides `_setOption` only for the `options` key (to rebuild `<option>` children). All other option processing delegates to `Input`, which delegates to `Component`. The `tag` defaults to `'select'` rather than `'input'`. Type auto-detection from value type does not apply.
+
+## Events
+
+Select emits standard enhanced DOM events via inherited `Input` behavior. The `onChange` handler receives an event with `.value` set to the currently selected option's value.
+
+## Example
+
+Mixed string and object options with a numeric value, used inside a Form:
+
+```js
+import { Select } from '@vanilla-bean/components';
+
+const select = new Select({
+	options: [
+		{ label: 'Low', value: 1 },
+		{ label: 'Medium', value: 2 },
+		{ label: 'High', value: 3 },
+	],
+	value: 2,
+	onChange: ({ value }) => {
+		select.options.value = value;
+		console.log('Priority level:', select.value); // uses getter
+	},
+	appendTo: document.body,
+});
+
+// Swap the option list reactively at any time
+select.options.options = ['alpha', 'beta', 'gamma'];
+```

package/components/Select/Select.js

@@ -0,0 +1,74 @@
+import { Elem } from '../../Elem';
+import { Input } from '../Input';
+
+const defaultOptions = {
+	tag: 'select',
+	get priorityOptions() {
+		return new Set(['textContent', 'content', 'appendTo', 'prependTo', 'options']);
+	},
+};
+
+/**
+ * Select dropdown component extending Input with dynamic option management.
+ *
+ * Provides enhanced HTML select functionality with dynamic option rendering
+ * and improved value handling for both string and object-based options.
+ * @param {object} [options={}] - Select configuration options
+ * @param {string} [options.tag='select'] - HTML tag, uses select element
+ * @param {Array<string|object>} [options.options] - Array of select options
+ * @param {*} [options.value] - Currently selected value
+ * @param {...(Component|HTMLElement|string)} children - Child elements to append
+ * @returns {Select} Select component instance
+ */
+class Select extends Input {
+	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
+
+	constructor(options = {}, ...children) {
+		super({ ...defaultOptions, ...options }, ...children);
+	}
+
+	static handlers = {
+		options(value) {
+			this.empty();
+
+			if (!value) return;
+
+			for (const option of value) {
+				// Optgroup: { label: 'Group', options: [...] }
+				if (typeof option === 'object' && Array.isArray(option.options)) {
+					const group = document.createElement('optgroup');
+					if (option.label) group.label = option.label;
+					for (const o of option.options) {
+						group.append(new Elem({ tag: 'option', ...(typeof o === 'object' ? o : { label: o, value: o }) }).elem);
+					}
+					this.elem.append(group);
+				} else {
+					this.append(
+						new Elem({ tag: 'option', ...(typeof option === 'object' ? option : { label: option, value: option }) }),
+					);
+				}
+			}
+		},
+	};
+
+	/**
+	 * Gets the currently selected value with enhanced option handling.
+	 * @returns {*} Selected option value, label, or text content
+	 */
+	get value() {
+		// Use elem.options (HTMLOptionsCollection) — works across optgroups
+		const selected = Array.from(this.elem.options).find(({ selected }) => selected);
+
+		return selected?.value ?? selected?.label ?? selected?.textContent ?? this.elem.value;
+	}
+
+	/**
+	 * Sets the selected value.
+	 * @param {*} newValue - Value to select
+	 */
+	set value(newValue) {
+		this.elem.value = newValue;
+	}
+}
+
+export default Select;

package/components/Select/Select.lld.md

@@ -0,0 +1,20 @@
+# Select
+
+> ./Select.js
+
+Dropdown select that extends Input. The design decision: Select inherits Input's value lifecycle; `isDirty`, validations, and onChange work the same way for a Select as they do for a text Input. Callers don't learn a separate API.
+
+## Select inherits the full Input value contract
+
+- `isDirty`, validations, and onChange all work the same way as Input without any Select-specific API
+  - does a Select have isDirty?
+  - does a Select value change trigger onChange the same way as an Input?
+
+## Options map in order, preserving sequence
+
+- items in the `options` array become select options in the same order; no automatic sorting or reindexing
+  - does the options array order match the dropdown order?
+
+## The value getter returns the selected option's value, with label as fallback
+
+- `select.value` returns the option's `value` attribute; if absent it falls back to `label`, then `textContent`

package/components/Select/index.js

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

package/components/Table/README.md

@@ -0,0 +1,94 @@
+# Table
+
+Data table component with configurable columns, client-side sorting, optional footer rows, and custom cell rendering.
+
+## Usage
+
+```js
+import { Table } from '@vanilla-bean/components';
+
+const table = new Table({
+	data: [
+		{ name: 'Alice', score: 42 },
+		{ name: 'Bob', score: 17 },
+	],
+	columns: ['name', 'score'],
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `Array<object>` | — | Array of row data objects. Reactive: reassigning `options.data` rebuilds the tbody |
+| `columns` | `Array<string\|object>` | `[]` | Column definitions; see shape below |
+| `footer` | `Array<string\|object>` | — | Footer row cells, same shape as columns. Strings are capitalized automatically |
+| `sortProperty` | `string` | — | Key of the currently sorted column |
+| `sortDirection` | `string` | — | `'asc'` or `'desc'` |
+| `onSort` | `Function` | built-in | Called with `(property, direction)` when a sortable column header is clicked. Default sorts `options.data` in place using `orderBy` |
+
+### `columns` entry shape
+
+A column can be a plain string (key name, auto-capitalized as header label) or an object:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `key` | `string` | Property name on each row data object |
+| `content` | `string\|Component` | Header cell content. Defaults to `capitalize(key)` |
+| `sort` | `boolean` | Enables click-to-sort on this column's header with an animated sort icon |
+| `dataColumn` | `object\|Function` | Options forwarded to each `<td>` component, or a `Function({ column, rowData, table })` returning those options |
+| `...thOptions` | `any` | Any additional options forwarded to the `<th>` component (e.g., `style`, `className`) |
+
+### `footer` entry shape
+
+Same as columns: a string (rendered as capitalized text content) or an object with any `<td>` component options (e.g., `content`, `colspan`).
+
+## Methods
+
+Table does not expose imperative public methods. All mutations go through reactive options:
+
+```js
+// Replace data (rebuilds tbody)
+table.options.data = newDataArray;
+
+// Trigger a sort programmatically
+table.options.sortProperty = 'score';
+table.options.sortDirection = 'asc';
+```
+
+Internal references after build:
+
+```js
+table.thead; // Elem wrapping <thead>
+table.tbody; // Elem wrapping <tbody>
+table.tfoot; // Elem wrapping <tfoot>
+```
+
+## Events
+
+Table does not emit custom events. Supply `onSort` to intercept sort interactions.
+
+## Example
+
+Sortable table with a custom column label, styled header, and footer totals:
+
+```js
+import { Table } from '@vanilla-bean/components';
+import theme from '@vanilla-bean/components/theme';
+
+const table = new Table({
+	data: [
+		{ item: 'Widget A', qty: 5, price: 9.99 },
+		{ item: 'Widget B', qty: 12, price: 4.49 },
+	],
+	columns: [
+		{ key: 'item', content: 'Product', sort: true },
+		{ key: 'qty', content: 'Quantity', sort: true, style: { textAlign: 'right' } },
+		{ key: 'price', content: 'Unit Price', style: { color: theme.colors.green } },
+	],
+	footer: [{ content: 'Totals:', colspan: 2 }, { content: '$59.83' }],
+	appendTo: document.body,
+});
+```
+
+Clicking a sortable column header toggles direction between `'desc'` and `'asc'`. The `onSort` default mutates `options.data` in place, triggering a reactive tbody rebuild.