@vanilla-bean/components 1.1.0 → 2.0.0

package/Elem/README.md

@@ -0,0 +1,373 @@
+# Elem
+
+Enhanced DOM element wrapper providing fluent API methods while maintaining direct access to the underlying HTMLElement.
+
+## Basic Usage
+
+### Simple Element Creation
+
+Create DOM elements with enhanced manipulation capabilities:
+
+```js
+import { Elem } from '@vanilla-bean/components';
+
+const button = new Elem({
+	tag: 'button',
+	textContent: 'Click me',
+	className: 'btn btn-primary',
+	onclick: () => alert('Clicked!'),
+	appendTo: document.body,
+});
+```
+
+### Complex Nested Structures
+
+Build complex DOM hierarchies with nested elements:
+
+```js
+const card = new Elem(
+	{
+		tag: 'div',
+		className: 'card',
+		style: { padding: '20px', margin: '10px' },
+	},
+	new Elem({ tag: 'h3', textContent: 'Card Title' }),
+	new Elem({ tag: 'p', textContent: 'Card content goes here.' }),
+);
+```
+
+### Method Chaining
+
+Chain methods for fluent DOM construction:
+
+```js
+const navigation = new Elem({ tag: 'nav' })
+	.addClass('menu', 'horizontal')
+	.setStyle({ display: 'flex', gap: '16px' })
+	.append(
+		new Elem({ tag: 'a', textContent: 'Home', href: '/' }),
+		new Elem({ tag: 'a', textContent: 'About', href: '/about' }),
+		new Elem({ tag: 'a', textContent: 'Contact', href: '/contact' }),
+	)
+	.appendTo(document.body);
+```
+
+### Direct DOM Access
+
+Access the full HTMLElement API when needed:
+
+```js
+const input = new Elem({ tag: 'input', type: 'text' });
+
+// Enhanced methods
+input.addClass('form-control').setStyle({ width: '100%' });
+
+// Direct DOM access
+input.elem.focus();
+input.elem.select();
+input.elem.scrollIntoView({ behavior: 'smooth' });
+```
+
+## Configuration Options
+
+### Constructor Syntax
+
+```js
+new Elem(options?, ...children)
+```
+
+**Parameters:**
+
+- `options` (Object) - Configuration options and HTML properties
+- `children` (...Elem|HTMLElement|string) - Child elements or text content
+
+### Core Options
+
+| Option       | Type                        | Description                        |
+| ------------ | --------------------------- | ---------------------------------- |
+| `tag`        | `string`                    | HTML tag name (default: 'div')     |
+| `style`      | `object`                    | CSS properties as key-value pairs  |
+| `attributes` | `object`                    | HTML attributes as key-value pairs |
+| `content`    | `string\|Elem\|HTMLElement` | Element content                    |
+| `appendTo`   | `Elem\|HTMLElement`         | Parent element to append to        |
+| `prependTo`  | `Elem\|HTMLElement`         | Parent element to prepend to       |
+| `append`     | `Array`                     | Child elements to append           |
+| `prepend`    | `Array`                     | Child elements to prepend          |
+
+### HTML Properties
+
+All standard HTMLElement properties work as options:
+
+```js
+new Elem({
+	// Content properties
+	textContent: 'Button text',
+	innerHTML: '<span>HTML content</span>',
+
+	// Form properties
+	value: 'input value',
+	checked: true,
+	disabled: false,
+
+	// Element properties
+	id: 'unique-id',
+	className: 'btn primary',
+	title: 'Tooltip text',
+
+	// Link properties
+	href: 'https://example.com',
+	target: '_blank',
+
+	// Image properties
+	src: 'image.jpg',
+	alt: 'Image description',
+});
+```
+
+### Event Handler Properties
+
+Event handlers can be assigned directly:
+
+```js
+new Elem({
+	tag: 'button',
+	onclick: event => console.log('clicked'),
+	onmouseover: event => console.log('hover'),
+	onchange: event => console.log('changed'),
+	onfocus: event => console.log('focused'),
+});
+```
+
+## DOM Manipulation
+
+### Content Management
+
+```js
+// Set content (replaces existing)
+elem.content('New text content');
+elem.content(new Elem({ tag: 'span', textContent: 'HTML element' }));
+
+// Clear all content
+elem.empty();
+```
+
+### Child Element Management
+
+```js
+// Add children
+elem.append(child1, child2, 'text content');
+elem.prepend(child1, child2);
+
+// Access children
+const childElements = elem.children; // Array of Elem instances
+const nativeChildren = elem.elem.children; // HTMLCollection
+```
+
+### Hierarchy Management
+
+```js
+// Add to DOM
+elem.appendTo(document.body);
+elem.prependTo(document.querySelector('.container'));
+
+// Navigate hierarchy
+const parentElem = elem.parent; // Parent Elem instance (if exists)
+const nativeParent = elem.parentElem; // Parent HTMLElement
+```
+
+### Style and Attribute Management
+
+```js
+// Set multiple styles
+elem.setStyle({
+	color: 'red',
+	fontSize: '16px',
+	backgroundColor: '#f0f0f0',
+});
+
+// Set multiple attributes
+elem.setAttributes({
+	'data-id': '123',
+	'aria-label': 'Close button',
+	role: 'button',
+});
+```
+
+## Class Management
+
+### Enhanced Class Operations
+
+Elem provides enhanced class manipulation with regular expression support:
+
+```js
+// Check for classes
+elem.hasClass('active'); // Check single class
+elem.hasClass('btn', 'primary'); // Check multiple classes
+elem.hasClass(/^btn-/); // Check with regex pattern
+
+// Add classes
+elem.addClass('new-class');
+elem.addClass('class1', 'class2', 'class3');
+
+// Remove classes
+elem.removeClass('old-class');
+elem.removeClass(/^temp-/); // Remove all classes starting with 'temp-'
+elem.removeClass(/\bmobile-\w+/g); // Remove classes matching pattern
+
+// Toggle class based on a condition (add when true, remove when false)
+elem.toggleClass('active', isActive);
+```
+
+### Class Manipulation Examples
+
+```js
+const button = new Elem({ tag: 'button', className: 'btn btn-primary temp-123' });
+
+// Remove all temporary classes
+button.removeClass(/^temp-/);
+
+// Add state classes
+button.addClass('btn-large', 'btn-rounded');
+
+// Conditional classes
+if (isActive) {
+	button.addClass('active', 'selected');
+}
+
+// Check for button variants
+if (button.hasClass(/^btn-(primary|secondary|danger)$/)) {
+	console.log('Has button variant class');
+}
+```
+
+## Event Handling
+
+### EventTarget Integration
+
+Elem extends EventTarget, providing full event capabilities:
+
+```js
+const button = new Elem({ tag: 'button', textContent: 'Click me' });
+
+// Option-based event handlers
+new Elem({
+	tag: 'input',
+	onchange: event => console.log('Value changed:', event.target.value),
+	onfocus: event => event.target.select(),
+});
+
+// addEventListener method
+button.addEventListener('click', event => {
+	console.log('Button clicked');
+});
+
+// Custom events
+button.addEventListener('customEvent', event => {
+	console.log('Custom event data:', event.detail);
+});
+
+// Dispatch events
+button.dispatchEvent(
+	new CustomEvent('customEvent', {
+		detail: { message: 'Hello' },
+	}),
+);
+```
+
+### Event Handler Options vs Methods
+
+```js
+// Via constructor options (preferred for initial setup)
+const elem = new Elem({
+	tag: 'button',
+	onclick: handleClick,
+	onmouseover: handleHover,
+});
+
+// Via addEventListener (preferred for dynamic binding)
+elem.addEventListener('click', handleClick);
+elem.addEventListener('mouseover', handleHover);
+
+// Via native element
+elem.elem.addEventListener('click', handleClick);
+```
+
+## API Reference
+
+### Constructor
+
+```js
+new Elem(options?, ...children)
+```
+
+### Core Methods
+
+#### Content Methods
+
+```js
+elem.content(content); // Set element content
+elem.empty(); // Remove all child elements
+```
+
+#### Child Management Methods
+
+```js
+elem.append(...children); // Append child elements
+elem.prepend(...children); // Prepend child elements
+elem.appendTo(parent); // Append to parent element
+elem.prependTo(parent); // Prepend to parent element
+```
+
+#### Style and Attribute Methods
+
+```js
+elem.setStyle(styles); // Set CSS properties
+elem.setAttributes(attributes); // Set HTML attributes
+elem.setOptions(options); // Set multiple options at once
+```
+
+#### Class Methods
+
+```js
+elem.hasClass(...classes); // Check for classes (supports regex)
+elem.addClass(...classes); // Add CSS classes
+elem.removeClass(...classes); // Remove CSS classes (supports regex)
+elem.toggleClass(className, condition); // Add when condition is true, remove when false
+```
+
+### Properties
+
+```js
+elem.elem; // Underlying HTMLElement
+elem.parent; // Parent Elem instance (if created by Elem)
+elem.parentElem; // Parent HTMLElement
+elem.children; // Array of child Elem instances
+elem.options; // Configuration options object
+```
+
+### Utility Methods
+
+```js
+elem.toString(); // Returns '[object Elem]'
+```
+
+## Integration with Component
+
+Elem serves as the foundation for the Component class:
+
+```js
+import { Component } from '@vanilla-bean/components';
+
+// Component extends Elem with reactive options
+const component = new Component({
+	tag: 'div',
+	textContent: 'I am reactive!',
+});
+
+// All Elem methods available
+component.addClass('component-class');
+component.setStyle({ padding: '16px' });
+
+// Plus Component-specific features
+component.options.textContent = 'Updated reactively!';
+```

package/README.md

@@ -124,7 +124,7 @@ const Card = styled(
 	({ colors }) => `
 	background: ${colors.white};
 	border-radius: 8px;
-	box-shadow: 0 2px 8px ${colors.black.setAlpha(0.1)};
+	box-shadow: 0 2px 8px ${colors.alpha(colors.black, 0.1)};
 	padding: 24px;
 
 	&:hover {
@@ -379,7 +379,7 @@ vanilla-bean-components/
 ├── Component/          # Core Component class
 ├── styled/             # Scoped styling system
 ├── theme/              # Design tokens and helpers
-├── demo/               # Component explorer — live option editor, API docs, example apps
+├── demo/               # Component explorer - live option editor, API docs, example apps
 └── docs/               # Additional documentation
 ```
 

package/components/BottomSheet/BottomSheet.js

@@ -2,12 +2,6 @@ import { styled } from '../../styled';
 import { Component } from '../../Component';
 import { Elem } from '../../Elem';
 
-const defaultOptions = {
-	get appendTo() {
-		return document.body;
-	},
-};
-
 /**
  * Mobile-friendly bottom sheet with drag-to-close gesture.
  *
@@ -65,18 +59,16 @@ class BottomSheet extends styled(
 		}
 	`,
 ) {
-	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
-
-	// Empty handler prevents _standardSetOption from routing onClose through the event system.
-	// The value is accessed directly as this.options.onClose in hide().
-	static handlers = {
-		onClose() {},
+	static schema = {
+		appendTo: {
+			get default() {
+				return document.body;
+			},
+		},
+		// Read directly as this.options.onClose in hide()
+		onClose: {},
 	};
 
-	constructor(options = {}, ...children) {
-		super({ ...defaultOptions, ...options }, ...children);
-	}
-
 	build() {
 		this._dragZone = new Elem({ tag: 'div', appendTo: this, addClass: 'sheet-drag-zone' });
 		new Elem({ tag: 'div', appendTo: this._dragZone, addClass: 'sheet-handle' });

package/components/BottomSheet/README.md

@@ -20,7 +20,7 @@ sheet.show();
 | Option     | Type       | Default         | Description                                                       |
 | ---------- | ---------- | --------------- | ----------------------------------------------------------------- |
 | `appendTo` | `Element`  | `document.body` | Where to mount the sheet in the DOM                               |
-| `onClose`  | `Function` | —               | Called when the sheet is dismissed — by drag or explicit `hide()` |
+| `onClose`  | `Function` | -               | Called when the sheet is dismissed - by drag or explicit `hide()` |
 
 All standard `Component` options are supported.
 

package/components/Button/Button.js

@@ -1,7 +1,5 @@
 import { TooltipWrapper } from '../TooltipWrapper';
 
-const defaultOptions = { tag: 'button' };
-
 /**
  * Interactive button component with keyboard accessibility and tooltip support.
  *
@@ -31,23 +29,19 @@ const defaultOptions = { tag: 'button' };
  * });
  */
 export default class Button extends TooltipWrapper {
-	defaultOptions = { ...super.defaultOptions, ...defaultOptions };
-
-	constructor(options = {}, ...children) {
-		const userOnKeyUp = options.onKeyUp;
+	static schema = {
+		tag: { default: 'button' },
+	};
 
-		super(
-			{
-				...defaultOptions,
-				...options,
-				onKeyUp: event => {
-					userOnKeyUp?.call(this, event);
-					if (event.code === 'Space' || event.code === 'Enter') {
-						this.options.onPointerPress?.(event);
-					}
-				},
+	build() {
+		this.on({
+			targetEvent: 'keyup',
+			id: 'buttonKeyboardActivate',
+			callback: event => {
+				if (event.code === 'Space' || event.code === 'Enter') {
+					this.options.onPointerPress?.(event);
+				}
 			},
-			...children,
-		);
+		});
 	}
 }

package/components/Button/Button.lld.md

@@ -15,7 +15,7 @@ Activatable element that unifies pointer and keyboard interaction under one hand
 - a caller-provided `onKeyUp` runs alongside the built-in keyboard activation; registering both handlers does not suppress either
   - does providing a custom onKeyUp still trigger onPointerPress on Space/Enter?
 
-## Tooltip is automatic — no setup beyond the tooltip option
+## Tooltip is automatic - no setup beyond the tooltip option
 
 - Button extends TooltipWrapper; a `tooltip` option produces tooltip behavior with no additional wiring
   - does a Button with a tooltip option show a tooltip on hover?