@vanilla-bean/components 1.1.1 → 2.0.1

package/Component/README.md

@@ -0,0 +1,480 @@
+# Component
+
+Reactive component class extending Elem with Oxject-backed reactive options, lifecycle management, and automatic cleanup.
+
+## Key Features
+
+- **Reactive options system** - Property changes backed by Oxject emit events and update DOM automatically
+- **Automatic memory management** - Element-level listeners persist through DOM moves, cleaned up on destroy. External resources (timers, subscriptions) cleaned up on disconnect
+- **Flexible render timing** - Immediate, onload, or animationFrame rendering modes
+- **Enhanced event handling** - Input events include `.value` property, DOM connection detection
+- **Integrated styling** - Inline objects or scoped CSS with theme system integration
+- **Lifecycle hooks** - Built-in hover and press handlers with automatic cleanup
+
+```js
+import { Component } from '@vanilla-bean/components';
+```
+
+## Basic Usage
+
+### Simple Components
+
+Every Component extends EventTarget and wraps an HTMLElement with reactive options:
+
+```js
+import { Component } from '@vanilla-bean/components';
+
+const button = new Component({
+	tag: 'button',
+	textContent: 'Click me',
+	className: 'primary-btn',
+	onPointerPress: () => alert('Hello!'),
+	appendTo: document.body,
+});
+```
+
+### Reactive Property Updates
+
+Options are backed by Oxject. Property changes trigger DOM updates automatically:
+
+```js
+const input = new Component({
+	tag: 'input',
+	value: 'Initial text',
+	onChange: ({ value }) => {
+		input.options.value = value; // Updates DOM reactively
+	},
+	appendTo: document.body,
+});
+
+// Display that updates automatically
+new Component({
+	tag: 'p',
+	textContent: input.options.subscriber('value', value => `Current: ${value}`),
+	appendTo: document.body,
+});
+```
+
+### Extended Component Classes
+
+Create reusable component classes with custom behavior:
+
+```js
+class Button extends Component {
+	static schema = {
+		tag: { default: 'button' },
+		mode: {
+			default: 'primary',
+			enum: ['primary', 'secondary'],
+			set(value) {
+				this.removeClass(/\bmode-\S+/g).addClass(`mode-${value}`);
+			},
+		},
+	};
+}
+```
+
+### With Styled Components
+
+Components integrate seamlessly with the styled system:
+
+```js
+import { styled } from '@vanilla-bean/components';
+
+const StyledComponent = styled(
+	Component,
+	({ colors }) => `
+	background: ${colors.blue};
+	color: ${colors.white};
+	padding: 16px;
+	border-radius: 8px;
+`,
+);
+```
+
+## Reactive Options System
+
+Component options are stored in an Oxject instance (not a plain object like Elem), enabling automatic reactivity:
+
+```js
+const button = new Component({ textContent: 'Click me' });
+
+// Property changes trigger DOM updates
+button.options.textContent = 'Updated'; // Updates DOM reactively
+button.options.addClass = 'active'; // Adds CSS class reactively
+
+// Full Oxject features available
+const subscription = button.options.subscribe({
+	key: 'textContent',
+	callback: value => console.log('Text changed:', value),
+});
+```
+
+### Option Processing Pipeline
+
+Options are routed through `_setOption` based on key and value type:
+
+| Condition                      | Routing                    | Example                   |
+| ------------------------------ | -------------------------- | ------------------------- |
+| Schema `set` / `data` / `enum` | Schema chain (see below)   | `variant: 'button'`       |
+| Key starts with 'on'           | Event handler registration | `onPointerPress: handler` |
+| Schema `attribute: true`       | `elem.setAttribute()`      | `colspan: '2'`            |
+| Component has method           | Method call with value     | `addClass: 'active'`      |
+| HTMLElement has property       | Direct elem property       | `textContent: 'hello'`    |
+| Value is function              | Component property         | `customMethod: fn`        |
+| Default                        | Elem property assignment   | `customProp: value`       |
+
+## Event Handling
+
+### Automatic Event Registration
+
+Event handlers are registered automatically when option keys start with 'on':
+
+```js
+new Component({
+	onPointerPress: event => console.log('pressed'),
+	onChange: ({ value }) => console.log('value:', value), // Input events include .value
+	onConnected: () => console.log('added to DOM'),
+	onDisconnected: () => console.log('removed from DOM'),
+});
+```
+
+> **Note:** `click` is not in the supported event set. Use `onPointerPress` for press interactions.
+
+### Enhanced Input Events
+
+Input-related events (`keydown`, `keyup`, `change`, `blur`, `input`, `search`) receive enhanced event objects:
+
+```js
+new Component({
+	tag: 'input',
+	type: 'text',
+	onChange: ({ value, event }) => {
+		console.log('New value:', value); // Extracted from input
+		console.log('Original event:', event);
+	},
+});
+```
+
+### Connection Events
+
+DOM connection/disconnection detected via MutationObserver:
+
+```js
+new Component({
+	onConnected: () => console.log('Component added to DOM'),
+	onDisconnected: () => {
+		console.log('Component removed - cleanup triggered');
+	},
+});
+```
+
+### Specialized Event Handlers
+
+#### Hover with Movement Tracking
+
+```js
+component.onHover(event => {
+	console.log('Mouse position:', event.clientX, event.clientY);
+});
+```
+
+#### Press Detection
+
+Fires on `pointerdown` for immediate, reliable response in all contexts including scroll containers and modal dialogs:
+
+```js
+component.onPointerPress(event => {
+	console.log('Pressed');
+});
+```
+
+## Styling
+
+### Inline Style Objects
+
+Apply styles as JavaScript objects:
+
+```js
+component.styles({
+	color: 'red',
+	padding: '10px',
+	backgroundColor: '#f0f0f0',
+});
+
+// Or as option
+new Component({
+	styles: { color: 'red', padding: '10px' },
+});
+```
+
+### Scoped CSS with Theme Integration
+
+Use theme functions for scoped, processed CSS:
+
+```js
+// Theme function with automatic scoping
+component.styles(
+	({ colors, fonts }) => `
+	background: ${colors.blue};
+	${fonts.kodeMono}
+	padding: 16px;
+	border-radius: 8px;
+
+	&:hover {
+		background: ${colors.darker(colors.blue)};
+	}
+
+	@media (max-width: 768px) {
+		padding: 8px;
+	}
+`,
+);
+```
+
+CSS is scope-wrapped and injected as a scoped <style> tag. No preprocessing.
+
+## Lifecycle Management
+
+### Render Lifecycle
+
+`render()` orchestrates a fixed sequence every time it is called:
+
+```
+render()
+  ├─ if (this.rendered)   ← re-render only: clears children, runs descendant cleanup
+  │     empty()
+  │     this.rendered = false
+  ├─ build()              ← subclass structural hook, runs before options are applied
+  ├─ _processOptions()    ← routes every option through _setOption()
+  │     priority keys first (onConnected, textContent, content, appendTo, prependTo, value)
+  │     then all remaining keys
+  └─ this.rendered = true
+```
+
+**`build()` is the subclass structural hook.** Override `build()`, never `render()`, to create child elements and internal structure. Because `build()` runs before `_processOptions()`, all structure exists by the time `_setOption` receives values.
+
+The preferred way to declare options is `static schema` - a per-class schema defining each key once: what can exist, its default, and how it routes. Schemas compose across the constructor chain, with child classes overriding parents per-key:
+
+```js
+class Card extends Component {
+	build() {
+		this.header = new Component({ tag: 'header', appendTo: this });
+		this.body = new Component({ tag: 'section', appendTo: this });
+	}
+
+	static schema = {
+		title: {
+			default: 'Untitled',
+			set(value) {
+				this.header.options.textContent = value;
+			},
+		},
+		variant: {
+			set(value) {
+				this.removeClass(/variant-\S+/).addClass(`variant-${value}`);
+			},
+		},
+		// Component data only - stored in this.options, never routed to the elem
+		records: {},
+	};
+}
+```
+
+Descriptor fields:
+
+- `default` - initial value, merged automatically at construction (no manual `{ ...defaultOptions, ...options }` spread needed). Use a getter (`get default() { return document.body; }`) for values that must evaluate fresh per instance.
+- `set(value, next)` - change handler, called on initial render and every reactive update. Not calling `next(value)` fully owns the key; calling it continues down the chain to parent handlers, then standard routing.
+- A bare `{}` declares a data-only key: declared keys never fall through to fallback guessing, so with no DOM match they live in `this.options` - stored, subscribable, silent. Keys with a real DOM match (Input's `type`, an `onChange` default) still route to it. Reserve bare `{}` for keys whose initial state is genuinely dynamic (computed from other state at use time), optional callbacks where absence is meaningful, and required inputs - everything else declares its `default`, so the read contract lives in the schema instead of scattered `||` fallbacks at consumers. Use a getter default (`get default() { return []; }`) for mutable containers so instances never share one.
+- `data: true` - force store-only routing. Only needed when a data key's name collides with a real DOM property or method that standard routing would otherwise hit (e.g. a data key named `title`).
+- `enum: ['small', 'large']` - the closed set of valid values. Assigning anything else (other than null/undefined) throws, listing the valid values. Readable via `component.optionEnum(key)` - the demo's options editor uses this to render value pickers.
+
+Inheritance semantics: `set` functions chain across the class hierarchy (deepest first), while scalar fields (`default`, `enum`, `data`, `attribute`, `priority`) are decided by the nearest class whose descriptor declares them - so a subclass can override a parent default, opt out of a flag with `data: false`, or lift a constraint with `enum: null`, and a subclass that only adds a `set` leaves the parent's scalars intact.
+
+Two keys are construction-only: `tag` and `autoRender` accept schema defaults but are consumed before the reactive store is created, so they never appear in `this.options` and cannot change after construction.
+
+Unhandled keys fall through to standard routing automatically - no `super._setOption` required.
+
+Two more statics complete the declaration surface, and together they eliminate the need for component constructors in almost every case:
+
+- `static events = ['select']` - custom event names usable with `on()`/`emit()`. Unioned up the class chain, so a subclass adds to its parent's events instead of replacing them.
+- `static prepareOptions(options, children)` - a pure transform run on the merged (schema defaults + user) options before processing, leaf-first up the class chain. This is the home for computed defaults: Input derives `type` from the value's type here, Code decides its tag from `multiline`, Table normalizes string columns. Because the hook sees merged options, ancestor hooks see subclass schema defaults (Input's hook sees Select's `tag: 'select'`).
+
+A fully declared component needs no constructor at all: `static schema` + `static events` + `prepareOptions` + `build()` cover declaration, wiring, and structure. Constructors remain only for genuine construction-time work (Page's eager stylesheet loading, Label's string-shorthand normalization).
+
+`_setOption` override still exists for cases that must intercept before the routing chain.
+
+### Derived option patterns
+
+There is deliberately no `derive` descriptor. When one option's value depends on another, pick the pattern that matches when the derivation must hold:
+
+- **Construction-time** - compute in `prepareOptions`. Right when the result feeds construction itself and never changes after (Code decides its `tag` from `multiline`; Notify picks `icon` and `role` from `type`).
+- **Read-time** - normalize where the value is consumed. Right when the option accepts shorthand and can change reactively; construction and reactive assignment then share one path (Table normalizes string columns inside `_renderTable`).
+- **Change-time** - recompute inside the source key's `set`. Right when a change to one option must immediately update dependent state (Table's `sortDirection` re-sorts `data`).
+
+**`empty()` only runs on re-render.** On the initial render it is skipped. On subsequent `render()` calls it removes all child elements and runs cleanup on all descendant components before the DOM is cleared.
+
+**`async build()` is not supported.** `render()` does not await `build()`'s return value. Asynchronous initialization belongs in `onConnected`.
+
+**Deep hierarchies must chain `super.build()` manually.** If both a parent class and its subclass define `build()`, the subclass must call `super.build()` explicitly. It is not called automatically.
+
+### Rendering Process (summary)
+
+```js
+component.render(); // Re-render: empty → build → _processOptions → rendered = true
+```
+
+Rendering behavior:
+
+1. **Content clearing** - `empty()` removes existing children on re-render only (skipped on first render)
+2. **Structure creation** - `build()` creates sub-elements before options are applied
+3. **Priority processing** - `_processOptions()` applies `priority: true` schema keys (and framework priority keys) first
+4. **Option routing** - Each option processed via `_setOption`
+5. **Completion flag** - Sets `rendered = true`
+
+### Automatic Cleanup System
+
+Components automatically clean up resources when removed from DOM:
+
+```js
+// Manual cleanup registration
+component.addCleanup('unique-id', () => {
+	console.log('Custom cleanup executed');
+});
+
+// Manual cleanup execution (automatic on disconnect)
+component.processCleanup();
+```
+
+**Automatic cleanup includes:**
+
+- Event listener removal
+- Oxject subscription cleanup
+- Style element removal from DOM
+- Recursive child component cleanup
+
+### Render Timing Control
+
+Control when components render with `autoRender` option:
+
+```js
+// Immediate rendering (default)
+new Component({ autoRender: true });
+
+// Render on window load event
+new Component({ autoRender: 'onload' });
+
+// Render on next animation frame
+new Component({ autoRender: 'animationFrame' });
+
+// Manual rendering only
+new Component({ autoRender: false });
+```
+
+## API Reference
+
+### Constructor
+
+```js
+new Component(options?, ...children)
+```
+
+**Parameters:**
+
+- `options` (Object) - Configuration options
+- `children` (...Component|Elem) - Child elements appended to `append` option
+
+### Configuration Options
+
+#### Component-Specific Options
+
+| Option       | Type                                  | Description                                 |
+| ------------ | ------------------------------------- | ------------------------------------------- |
+| `tag`        | `string`                              | HTML tag name (default: 'div')              |
+| `autoRender` | `boolean\|'onload'\|'animationFrame'` | Render timing control                       |
+| `styles`     | `string\|object\|Function`            | CSS string, style object, or theme function |
+| `uniqueId`   | `string`                              | Override auto-generated unique ID           |
+
+Custom events (`static events`), attribute routing (`attribute: true`), and processing priority (`priority: true`) are declared in the class, not passed as options.
+
+#### Event Handler Options
+
+| Option           | Type       | Description                                  |
+| ---------------- | ---------- | -------------------------------------------- |
+| `onHover`        | `Function` | Hover handler with move tracking             |
+| `onPointerPress` | `Function` | Fires on `pointerdown`                       |
+| ~~`onClick`~~    | -          | Not supported. Use `onPointerPress` instead. |
+| `onChange`       | `Function` | Change event handler (input .value included) |
+| `onConnected`    | `Function` | DOM connection detection                     |
+| `onDisconnected` | `Function` | DOM disconnection detection                  |
+
+All standard Elem options work as reactive Component options.
+
+### Methods
+
+#### Options-Compatible Methods
+
+Can be called directly or used as reactive options:
+
+```js
+component.styles(styleFunction); // Direct call
+component.onHover(callback); // Direct call
+component.addClass('active'); // Direct call
+component.append(child); // Direct call
+
+// Or as reactive options:
+new Component({
+	styles: styleFunction,
+	onHover: callback,
+	addClass: 'active',
+	append: [child],
+});
+```
+
+#### Lifecycle Methods
+
+```js
+component.build(); // Subclass structural hook - override to create child elements
+component.render(); // Re-render: empty → build → _processOptions → rendered = true
+component.addCleanup(id, fn); // Register cleanup function (chains with existing for same id)
+component.replaceCleanup(id, fn); // Replace cleanup, running the previous one immediately
+component.replaceDestroyCleanup(id, fn); // Destroy-only cleanup: survives disconnect, runs on destroy()
+component.processCleanup(); // Execute all cleanup functions
+component.destroy(); // Disconnect observer, run all cleanup, remove from DOM
+```
+
+#### Event Methods
+
+```js
+component.on({ targetEvent, callback, id? }); // Event registration
+component.emit(eventType, detail);             // Event dispatch
+```
+
+#### Utility Methods
+
+```js
+component.ancestry(); // Prototype chain inspection
+```
+
+### Properties
+
+```js
+component.parent; // Parent Component/Elem instance
+component.children; // Child Component/Elem instances
+component.uniqueId; // Frozen unique identifier
+component.options; // Reactive Oxject instance
+component.elem; // Underlying HTMLElement
+component.rendered; // Boolean render status flag
+```
+
+## Memory Management
+
+Components provide comprehensive automatic memory management:
+
+- **Event listeners** - Automatically removed on DOM disconnect
+- **Oxject subscriptions** - Cleaned up when component destroyed
+- **Style elements** - Removed from DOM head on cleanup
+- **Child components** - Recursive cleanup propagation
+- **Custom cleanup** - Manual cleanup function registration
+
+No manual cleanup required for typical usage - components handle resource management automatically.