@vanilla-bean/components 1.0.0

package/Component/README.md

@@ -0,0 +1,455 @@
+# 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 {
+	constructor(options = {}, ...children) {
+		super(
+			{
+				tag: 'button',
+				...options,
+				styles: ({ button }) => `
+				${button}
+				${options.styles?.({ button }) || ''}
+			`,
+			},
+			...children,
+		);
+	}
+
+	_setOption(key, value) {
+		if (key === 'mode') {
+			this.removeClass(/\bmode-\S+/g).addClass(`mode-${value}`);
+		} else {
+			super._setOption(key, 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                   |
+| ------------------------ | -------------------------- | ------------------------- |
+| Key starts with 'on'     | Event handler registration | `onPointerPress: handler` |
+| Key in `knownAttributes` | `elem.setAttribute()`      | `id: 'my-id'`             |
+| 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 handle specific options is `static handlers` — a per-class dispatch map that composes across the constructor chain without requiring `super._setOption`:
+
+```js
+class Card extends Component {
+	build() {
+		this.header = new Component({ tag: 'header', appendTo: this });
+		this.body = new Component({ tag: 'section', appendTo: this });
+	}
+
+	static handlers = {
+		title(value) {
+			this.header.options.textContent = value;
+		},
+		variant(value) {
+			this.removeClass(/variant-\S+/).addClass(`variant-${value}`);
+		},
+	};
+}
+```
+
+Handlers that don't call `next(value)` fully own their key. Unhandled keys fall through to standard routing automatically — no `super._setOption` required. Use `_setOption` override only for enum validation or cases that need to intercept before the routing chain.
+
+**`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 `priorityOptions` 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                       |
+| `registeredEvents` | `Set<string>`                         | Custom event types for on() method          |
+| `knownAttributes`  | `Set<string>`                         | Attribute names for elem.setAttribute()     |
+| `priorityOptions`  | `Set<string>`                         | Option keys processed first during render   |
+| `styles`           | `string\|object\|Function`            | CSS string, style object, or theme function |
+| `uniqueId`         | `string`                              | Override auto-generated unique ID           |
+
+#### 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.

package/Component/index.js

@@ -0,0 +1,3 @@
+export { default as Component } from './Component';
+
+export * from './observeElementConnection';

package/Component/observeElementConnection.js

@@ -0,0 +1,52 @@
+const registry = new Map();
+let sharedObserver = null;
+
+/**
+ *
+ */
+function ensureObserver() {
+	if (sharedObserver) return;
+
+	sharedObserver = new MutationObserver(mutations => {
+		for (const mutation of mutations) {
+			for (const node of mutation.removedNodes) {
+				for (const [target, callbacks] of registry) {
+					if (node === target || node.contains?.(target)) callbacks.onDisconnected(mutation);
+				}
+			}
+			for (const node of mutation.addedNodes) {
+				for (const [target, callbacks] of registry) {
+					if (node === target || node.contains?.(target)) callbacks.onConnected(mutation);
+				}
+			}
+		}
+	});
+
+	sharedObserver.observe(document, { childList: true, subtree: true });
+}
+
+/**
+ * Observe DOM connection/disconnection of an element via a shared MutationObserver.
+ * All registrations share one observer; the observer is torn down when no targets remain.
+ * Fires correctly when the target itself or any ancestor is moved.
+ * @param {object} config - Observer registration options
+ * @param {Node} config.target - Target element to watch for add/remove
+ * @param {Function} config.onConnected - Called when target is added to the document
+ * @param {Function} config.onDisconnected - Called when target is removed from the document
+ * @returns {{ disconnect: Function }} Handle — call disconnect() to deregister
+ */
+export const observeElementConnection = ({ target, onConnected, onDisconnected }) => {
+	ensureObserver();
+	registry.set(target, { onConnected, onDisconnected });
+
+	return {
+		disconnect() {
+			registry.delete(target);
+
+			if (registry.size === 0) {
+				sharedObserver?.disconnect();
+				sharedObserver = null;
+			}
+		},
+	};
+};

package/Component/observeElementConnection.test.js

@@ -0,0 +1,121 @@
+import { observeElementConnection } from './observeElementConnection';
+
+const tick = () => new Promise(resolve => setTimeout(resolve, 0));
+
+describe('observeElementConnection', () => {
+	afterEach(() => {
+		document.body.replaceChildren();
+	});
+
+	test('fires onConnected when target is directly appended', async () => {
+		const target = document.createElement('div');
+		const onConnected = mock();
+		const handle = observeElementConnection({ target, onConnected, onDisconnected: mock() });
+
+		document.body.appendChild(target);
+		await tick();
+
+		expect(onConnected).toHaveBeenCalledTimes(1);
+		handle.disconnect();
+	});
+
+	test('fires onDisconnected when target is directly removed', async () => {
+		const target = document.createElement('div');
+		document.body.appendChild(target);
+		await tick();
+
+		const onDisconnected = mock();
+		const handle = observeElementConnection({ target, onConnected: mock(), onDisconnected });
+
+		document.body.removeChild(target);
+		await tick();
+
+		expect(onDisconnected).toHaveBeenCalledTimes(1);
+		handle.disconnect();
+	});
+
+	test('fires onConnected when an ancestor containing the target is appended', async () => {
+		const parent = document.createElement('div');
+		const target = document.createElement('span');
+		parent.appendChild(target);
+
+		const onConnected = mock();
+		const handle = observeElementConnection({ target, onConnected, onDisconnected: mock() });
+
+		document.body.appendChild(parent);
+		await tick();
+
+		expect(onConnected).toHaveBeenCalledTimes(1);
+		handle.disconnect();
+	});
+
+	test('fires onDisconnected when an ancestor containing the target is removed', async () => {
+		const parent = document.createElement('div');
+		const target = document.createElement('span');
+		parent.appendChild(target);
+		document.body.appendChild(parent);
+		await tick();
+
+		const onDisconnected = mock();
+		const handle = observeElementConnection({ target, onConnected: mock(), onDisconnected });
+
+		document.body.removeChild(parent);
+		await tick();
+
+		expect(onDisconnected).toHaveBeenCalledTimes(1);
+		handle.disconnect();
+	});
+
+	test('does not fire after disconnect', async () => {
+		const target = document.createElement('div');
+		const onConnected = mock();
+		const handle = observeElementConnection({ target, onConnected, onDisconnected: mock() });
+
+		handle.disconnect();
+		document.body.appendChild(target);
+		await tick();
+
+		expect(onConnected).not.toHaveBeenCalled();
+	});
+
+	test('multiple targets all receive their callbacks', async () => {
+		const target1 = document.createElement('div');
+		const target2 = document.createElement('div');
+		const cb1 = mock();
+		const cb2 = mock();
+
+		const h1 = observeElementConnection({ target: target1, onConnected: cb1, onDisconnected: mock() });
+		const h2 = observeElementConnection({ target: target2, onConnected: cb2, onDisconnected: mock() });
+
+		document.body.appendChild(target1);
+		document.body.appendChild(target2);
+		await tick();
+
+		expect(cb1).toHaveBeenCalled();
+		expect(cb2).toHaveBeenCalled();
+
+		h1.disconnect();
+		h2.disconnect();
+	});
+
+	test('deregistered target does not fire after its disconnect', async () => {
+		const target1 = document.createElement('div');
+		const target2 = document.createElement('div');
+		const cb1 = mock();
+		const cb2 = mock();
+
+		const h1 = observeElementConnection({ target: target1, onConnected: cb1, onDisconnected: mock() });
+		const h2 = observeElementConnection({ target: target2, onConnected: cb2, onDisconnected: mock() });
+
+		h1.disconnect();
+
+		document.body.appendChild(target1);
+		document.body.appendChild(target2);
+		await tick();
+
+		expect(cb1).not.toHaveBeenCalled();
+		expect(cb2).toHaveBeenCalled();
+
+		h2.disconnect();
+	});
+});