@vanilla-bean/components 1.1.0 → 2.0.0

package/components/Keyboard/Keyboard.js

@@ -24,54 +24,46 @@ const KeyRow = styled(
  * @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,
+	static schema = {
+		layout: {
+			default: 'simple',
+			set(value) {
+				this.setLayout(value);
+			},
+		},
+		// Read directly from this.options in setLayout() and key press handling
+		layouts: {
+			default: {
+				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'],
+				],
+			},
+		},
+		keyDefinitions: {
+			default: {
+				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' },
 			},
-			...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);
 		},
+		tactileResponse: { default: true },
 	};
 
 	// todo native keyboard events https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/KeyboardEvent

package/components/Keyboard/Keyboard.lld.md

@@ -4,7 +4,7 @@
 
 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
+## 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?

package/components/Label/Label.js

@@ -120,10 +120,6 @@ const StyledLabel = styled(
 	`,
 );
 
-const variant_enum = Object.freeze(['overlay', 'collapsible', 'inline', 'inline-after', 'simple']);
-
-const defaultOptions = { variant: 'simple' };
-
 /**
  * Label component with multiple display variants and input association.
  *
@@ -139,20 +135,61 @@ const defaultOptions = { variant: 'simple' };
  * @returns {Label} Label component instance
  */
 class Label extends StyledLabel {
-	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
-	variant_enum = variant_enum;
+	static schema = {
+		variant: {
+			default: 'simple',
+			enum: ['overlay', 'collapsible', 'inline', 'inline-after', 'simple'],
+			set(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');
+					}
+				}
+			},
+		},
+		label: {
+			set(value) {
+				if (typeof value === 'object') this._labelText?.setOptions(value);
+				else if (this._labelText) this._labelText.options.content = value;
+			},
+		},
+		collapsed: {
+			set(value) {
+				this[value ? 'addClass' : 'removeClass']('collapsed');
+				if (this.options.variant === 'collapsible' && this._labelText) {
+					this._labelText.elem.setAttribute('aria-expanded', value ? 'false' : 'true');
+				}
+			},
+		},
+		for: {
+			set(value) {
+				let forId = typeof value === 'string' ? value : value?.id || value?.elem?.id;
 
-	constructor(options = {}, ...children) {
-		if (typeof options === 'string') options = { label: options };
+				if (!forId && value?._component) {
+					forId = value.elem.id = value.uniqueId;
+				}
 
-		super(
-			{
-				...(children.length > 0 && { for: children[0] }),
-				...defaultOptions,
-				...options,
+				if (this._labelText) this._labelText.elem.htmlFor = forId ?? '';
 			},
-			...children,
-		);
+		},
+	};
+
+	static prepareOptions(options, children) {
+		return {
+			...(children.length > 0 && { for: children[0] }),
+			...options,
+		};
+	}
+
+	constructor(options = {}, ...children) {
+		// String shorthand must resolve before Component spreads options
+		super(typeof options === 'string' ? { label: options } : options, ...children);
 	}
 
 	build() {
@@ -174,41 +211,6 @@ class Label extends StyledLabel {
 
 		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/Link/Link.js

@@ -1,14 +1,5 @@
 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.
  *
@@ -25,17 +16,20 @@ const variant_enum = Object.freeze(['link', 'button']);
  * @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}`);
+	static schema = {
+		tag: { default: 'a' },
+		variant: {
+			default: 'link',
+			enum: ['link', 'button'],
+			set(value) {
+				this.removeClass(/\bvariant-\S+\b/g);
+				this.addClass(`variant-${value}`);
+			},
+		},
+		tooltip: {
+			get default() {
+				return { icon: 'link', style: { fontSize: '12px' } };
+			},
 		},
 	};
 }

package/components/List/List.js

@@ -42,41 +42,39 @@ const ListItem = styled(
  * @returns {List} List component instance
  */
 export default class List extends StyledComponent {
-	constructor(options = {}, ...children) {
-		super(
-			{
-				...options,
-				tag: 'ul',
+	static schema = {
+		tag: { default: 'ul' },
+		noStyle: {
+			set(value) {
+				this.toggleClass('no-style', !!value);
 			},
-			...children,
-		);
-	}
-
-	static handlers = {
-		noStyle(value) {
-			this.toggleClass('no-style', !!value);
 		},
-		items(value) {
-			if (!value) {
-				this.empty();
-				return;
-			}
+		items: {
+			set(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 });
+				this.content(
+					value.map(item => {
+						const isContent = typeof item === 'string' || item?.elem || Array.isArray(item);
+						const listItem = new ListItem({ tag: 'li', ...item?.listItemOptions });
+						// listItemOptions belongs to the li wrapper - strip it before passing item options along.
+						const itemOptions = isContent ? item : { ...item };
+						if (!isContent) delete itemOptions.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);
+						if (this.options.ListItemComponent) {
+							listItem.content(new this.options.ListItemComponent(isContent ? { content: item } : itemOptions));
+						} else if (item.ListItemComponent) {
+							listItem.content(new item.ListItemComponent(itemOptions));
+						} else if (isContent) listItem.content(item);
+						else listItem.setOptions(itemOptions);
 
-					return listItem;
-				}),
-			);
+						return listItem;
+					}),
+				);
+			},
 		},
 	};
 }

package/components/Menu/Menu.js

@@ -37,23 +37,32 @@ const StyledList = styled(
  * 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 {Function} [options.onSelect] - Handler for the "select" CustomEvent fired when a menu item is activated; the activation event is in event.detail
  * @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'));
+	static schema = {
+		role: { default: 'menu' },
+		items: {
+			set(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);
+	static events = ['select'];
+
+	build() {
+		this.on({
+			targetEvent: 'pointerdown',
+			id: 'menuSelect',
+			callback: event => this.emit('select', event),
+		});
 
 		this.on({
 			targetEvent: 'keydown',
@@ -78,7 +87,7 @@ export default class Menu extends StyledList {
 					next = items[items.length - 1];
 				} else if ((e.key === 'Enter' || e.key === ' ') && currentIndex >= 0) {
 					e.preventDefault();
-					this.options.onSelect?.(e);
+					this.emit('select', e);
 					return;
 				}
 

package/components/Menu/Menu.lld.md

@@ -2,11 +2,11 @@
 
 > ./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.
+Styled list whose items emit a registered `select` CustomEvent, with the activation event in `detail`. 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. `onSelect` is the option-form listener for the event.
 
 ## 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
+- clicking, touching, Space/Enter, and screen reader activation all emit `select`; one handler, no separate keyboard path
   - does clicking a menu item invoke onSelect?
 
 ## Menu renders any item format that List supports

package/components/Notify/Notify.js

@@ -1,8 +1,6 @@
 import { styled } from '../../styled';
 import { Popover } from '../Popover';
 
-const type_enum = Object.freeze(['info', 'success', 'warning', 'error']);
-
 const StyledPopover = styled(
 	Popover,
 	({ colors, fonts }) => `
@@ -68,29 +66,41 @@ const StyledPopover = styled(
  * @returns {Notify} Notify component instance
  */
 export default class Notify extends StyledPopover {
-	type_enum = type_enum;
+	static schema = {
+		type: { default: 'success', enum: ['info', 'success', 'warning', 'error'] },
+		timeout: {
+			set(value) {
+				clearTimeout(this.timeout);
+				if (!value) return;
+				this.timeout = setTimeout(() => this.destroy(), value);
+				this.replaceCleanup('timeout', () => clearTimeout(this.timeout));
+			},
+		},
+	};
 
-	constructor(options = {}) {
-		const { timeout, type = 'success' } = options;
-		const icon =
-			options.icon ||
-			{ info: 'circle-info', success: 'check', warning: 'triangle-exclamation', error: 'skull-crossbones' }[type];
+	static prepareOptions(options) {
+		const { type } = options;
 
-		super({
+		return {
 			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,
-		});
+			icon:
+				options.icon ||
+				{ info: 'circle-info', success: 'check', warning: 'triangle-exclamation', error: 'skull-crossbones' }[type],
+		};
+	}
 
-		if (timeout) {
-			this.timeout = setTimeout(() => this.destroy(), timeout);
-			this.addCleanup('timeout', () => clearTimeout(this.timeout));
-		}
+	build() {
+		super.build();
+
+		this.on({
+			targetEvent: 'pointerdown',
+			id: 'notifyDismiss',
+			callback: e => {
+				if (!e.target.closest('button, [role="button"]')) this.destroy();
+			},
+		});
 	}
 }

package/components/Notify/Notify.lld.md

@@ -9,12 +9,12 @@ Transient notification that self-destructs. The design choice is that click-to-d
 - 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
+## 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
+## 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/Page/Page.lld.md

@@ -4,7 +4,7 @@
 
 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
+## 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?

package/components/Popover/Popover.js

@@ -18,19 +18,6 @@ const StyledIcon = styled(
 	`,
 );
 
-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.
  *
@@ -50,45 +37,63 @@ const state_enum = Object.freeze(['auto', 'manual']);
  * @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,
+	static schema = {
+		uniqueId: { default: true },
+		state: {
+			default: 'manual',
+			enum: ['auto', 'manual'],
+			set(value) {
+				this.elem.popover = value;
+			},
+		},
+		autoOpen: { default: true },
+		// Positioning and dismissal config read from this.options by show()/edgeAwarePlacement()
+		outsideClose: { default: false },
+		viewport: {
+			get default() {
+				return document.documentElement;
+			},
+		},
+		appendTo: {
+			get default() {
+				return document.body;
+			},
+		},
+		maxWidth: { default: 264 },
+		maxHeight: { default: 132 },
+		x: {
+			set() {
+				this._placeAtPoint();
+			},
+		},
+		y: {
+			set() {
+				this._placeAtPoint();
 			},
-			...children,
-		);
+		},
+	};
 
-		if (this.options.x !== undefined && this.options.y !== undefined) this.edgeAwarePlacement(this.options);
+	build() {
+		this.on({
+			targetEvent: 'connected',
+			id: 'popoverAutoOpen',
+			callback: () => {
+				if (!this.options.autoOpen) return;
+				const timeoutId = setTimeout(() => this.show(), 200);
+				this.replaceCleanup('autoOpen', () => clearTimeout(timeoutId));
+			},
+		});
 	}
 
-	static handlers = {
-		state(value) {
-			this.elem.popover = value;
-		},
-		outsideClose() {},
-		viewport() {},
-		maxWidth() {},
-		maxHeight() {},
-		x() {},
-		y() {},
-	};
+	_placeAtPoint() {
+		if (this.options.x !== undefined && this.options.y !== undefined) this.edgeAwarePlacement(this.options);
+	}
 
 	edgeAwarePlacement({
 		x,
 		y,
-		maxHeight = this.options.maxHeight ?? 132,
-		maxWidth = this.options.maxWidth ?? 264,
+		maxHeight = this.options.maxHeight,
+		maxWidth = this.options.maxWidth,
 		padding = 24,
 		viewport = this.options.viewport || this.options.appendTo,
 	}) {