+236

app/components/README.md

reviewed

··· 342 342 343 343 --- 344 344 345 345 + ## Reactive System 346 346 + 347 347 + ### Signals 348 348 + 349 349 + Reactive primitives for state management. Native JavaScript implementation following the TC39 Signals proposal pattern. 350 350 + 351 351 + ```javascript 352 352 + import { signal, computed, effect, batch, watch } from 'peek://app/components/signals.js'; 353 353 + 354 354 + // Create reactive value 355 355 + const count = signal(0); 356 356 + console.log(count.value); // 0 357 357 + 358 358 + // Computed values auto-update 359 359 + const doubled = computed(() => count.value * 2); 360 360 + 361 361 + // Effects run when dependencies change 362 362 + const dispose = effect(() => { 363 363 + console.log(`Count: ${count.value}, Doubled: ${doubled.value}`); 364 364 + }); 365 365 + 366 366 + // Update triggers effect 367 367 + count.value = 5; // Logs: "Count: 5, Doubled: 10" 368 368 + 369 369 + // Batch multiple updates 370 370 + batch(() => { 371 371 + count.value = 10; 372 372 + // other updates... 373 373 + }); // Effects run once at end 374 374 + 375 375 + // Watch specific signal 376 376 + const stop = watch(count, (newVal, oldVal) => { 377 377 + console.log(`Changed from ${oldVal} to ${newVal}`); 378 378 + }); 379 379 + 380 380 + // Cleanup 381 381 + dispose(); 382 382 + stop(); 383 383 + ``` 384 384 + 385 385 + #### Signal API 386 386 + 387 387 + | Function | Description | 388 388 + |----------|-------------| 389 389 + | `signal(value)` | Create reactive value with `.value` getter/setter | 390 390 + | `computed(fn)` | Create derived value that auto-updates | 391 391 + | `effect(fn)` | Run side effects when dependencies change | 392 392 + | `batch(fn)` | Batch updates, run effects once at end | 393 393 + | `watch(signal, handler)` | Watch specific signal for changes | 394 394 + | `fromExternal(get, set, subscribe)` | Bridge external state to signals | 395 395 + 396 396 + --- 397 397 + 398 398 + ### Schema Validation 399 399 + 400 400 + Lightweight JSON Schema validation for component data. 401 401 + 402 402 + ```javascript 403 403 + import { validate, createValidator, Schema } from 'peek://app/components/schema.js'; 404 404 + 405 405 + // Define schema 406 406 + const userSchema = { 407 407 + type: 'object', 408 408 + required: ['name', 'email'], 409 409 + properties: { 410 410 + name: { type: 'string', minLength: 1 }, 411 411 + email: { type: 'string', format: 'email' }, 412 412 + age: { type: 'integer', minimum: 0, default: 0 } 413 413 + } 414 414 + }; 415 415 + 416 416 + // Validate data 417 417 + const result = validate({ name: 'Alice', email: 'alice@example.com' }, userSchema); 418 418 + // { valid: true, errors: [], data: { name: 'Alice', email: 'alice@example.com', age: 0 } } 419 419 + 420 420 + // Create reusable validator 421 421 + const validateUser = createValidator(userSchema); 422 422 + validateUser({ name: '', email: 'invalid' }); 423 423 + // { valid: false, errors: [...] } 424 424 + 425 425 + // Schema builders 426 426 + const schema = Schema.object({ 427 427 + title: Schema.string({ minLength: 1 }), 428 428 + count: Schema.integer({ minimum: 0 }), 429 429 + tags: Schema.array(Schema.string()) 430 430 + }, { required: ['title'] }); 431 431 + ``` 432 432 + 433 433 + #### Supported Keywords 434 434 + 435 435 + | Keyword | Types | Description | 436 436 + |---------|-------|-------------| 437 437 + | `type` | all | `string`, `number`, `integer`, `boolean`, `array`, `object`, `null` | 438 438 + | `required` | object | Array of required property names | 439 439 + | `properties` | object | Property schemas | 440 440 + | `items` | array | Schema for array items | 441 441 + | `enum` | all | Allowed values | 442 442 + | `minimum`, `maximum` | number | Number bounds | 443 443 + | `minLength`, `maxLength` | string | String length | 444 444 + | `minItems`, `maxItems` | array | Array length | 445 445 + | `pattern` | string | Regex pattern | 446 446 + | `format` | string | `email`, `uri`, `date`, `date-time`, `uuid` | 447 447 + | `default` | all | Default value | 448 448 + 449 449 + --- 450 450 + 451 451 + ### Data Binding 452 452 + 453 453 + Bind components to reactive data sources with automatic updates. 454 454 + 455 455 + ```javascript 456 456 + import { DataBoundElement, createDataComponent } from 'peek://app/components/data-binding.js'; 457 457 + import { signal } from 'peek://app/components/signals.js'; 458 458 + import { html, css } from 'lit'; 459 459 + 460 460 + // Extend DataBoundElement 461 461 + class UserCard extends DataBoundElement { 462 462 + static dataSchema = { 463 463 + type: 'object', 464 464 + properties: { 465 465 + name: { type: 'string' }, 466 466 + avatar: { type: 'string', format: 'uri' } 467 467 + } 468 468 + }; 469 469 + 470 470 + render() { 471 471 + return html` 472 472 + <img src=${this.data.avatar}> 473 473 + <span>${this.data.name}</span> 474 474 + `; 475 475 + } 476 476 + } 477 477 + customElements.define('user-card', UserCard); 478 478 + 479 479 + // Bind to signal 480 480 + const userData = signal({ name: 'Alice', avatar: 'https://...' }); 481 481 + const card = document.querySelector('user-card'); 482 482 + card.bindTo(userData); 483 483 + 484 484 + // Updates automatically when signal changes 485 485 + userData.value = { name: 'Bob', avatar: 'https://...' }; 486 486 + 487 487 + // Or create data component dynamically 488 488 + const StatusBadge = createDataComponent('status-badge', { 489 489 + schema: { type: 'object', properties: { status: { type: 'string' } } }, 490 490 + render: (data) => html`<span class=${data.status}>${data.status}</span>` 491 491 + }); 492 492 + ``` 493 493 + 494 494 + #### DataBoundElement API 495 495 + 496 496 + | Method | Description | 497 497 + |--------|-------------| 498 498 + | `bindTo(source, options)` | Bind to signal, observable, or data source | 499 499 + | `unbind()` | Disconnect from data source | 500 500 + | `updateData(key, value)` | Update single property | 501 501 + | `mergeData(partial)` | Merge partial data into current | 502 502 + | `data` | Get/set the data object | 503 503 + | `isBound` | Check if bound to a source | 504 504 + 505 505 + --- 506 506 + 507 507 + ### Event Bus 508 508 + 509 509 + Cross-component communication that works across Shadow DOM. 510 510 + 511 511 + ```javascript 512 512 + import { on, emit, channel, waitFor, EventBusMixin } from 'peek://app/components/events.js'; 513 513 + 514 514 + // Subscribe to events 515 515 + const unsubscribe = on('user:login', (user) => { 516 516 + console.log('User logged in:', user.name); 517 517 + }); 518 518 + 519 519 + // Emit events 520 520 + emit('user:login', { name: 'Alice', id: 123 }); 521 521 + 522 522 + // Wildcard subscriptions 523 523 + on('user:*', (data, eventName) => { 524 524 + console.log(`User event: ${eventName}`, data); 525 525 + }); 526 526 + 527 527 + // Namespaced channels 528 528 + const userChannel = channel('user'); 529 529 + userChannel.on('login', handler); 530 530 + userChannel.emit('login', userData); 531 531 + userChannel.onAny(handler); // All 'user:*' events 532 532 + 533 533 + // Promise-based waiting 534 534 + const user = await waitFor('user:login', { timeout: 5000 }); 535 535 + 536 536 + // Replay last value 537 537 + emit('config:loaded', config, { retain: true }); 538 538 + on('config:loaded', handler, { replay: true }); // Gets config immediately 539 539 + 540 540 + // Unsubscribe 541 541 + unsubscribe.unsubscribe(); 542 542 + ``` 543 543 + 544 544 + #### Component Integration 545 545 + 546 546 + ```javascript 547 547 + import { EventBusMixin } from 'peek://app/components/events.js'; 548 548 + import { PeekElement } from 'peek://app/components/base.js'; 549 549 + 550 550 + class MyComponent extends EventBusMixin(PeekElement) { 551 551 + connectedCallback() { 552 552 + super.connectedCallback(); 553 553 + // Auto-cleanup on disconnect 554 554 + this.subscribe('data:update', this.handleUpdate); 555 555 + } 556 556 + 557 557 + handleUpdate = (data) => { 558 558 + this.data = data; 559 559 + } 560 560 + 561 561 + save() { 562 562 + this.publish('data:saved', this.data); 563 563 + } 564 564 + } 565 565 + ``` 566 566 + 567 567 + #### Event Bus API 568 568 + 569 569 + | Function | Description | 570 570 + |----------|-------------| 571 571 + | `on(event, handler, options)` | Subscribe to event | 572 572 + | `once(event, handler)` | Subscribe once | 573 573 + | `emit(event, data, options)` | Emit event | 574 574 + | `channel(namespace)` | Create namespaced channel | 575 575 + | `waitFor(event, options)` | Promise-based event waiting | 576 576 + | `typedEvent(name)` | Create typed event emitter | 577 577 + | `EventBusMixin(Base)` | Mixin for auto-cleanup subscriptions | 578 578 + 579 579 + --- 580 580 + 345 581 ## Browser Support 346 582 347 583 Components use modern CSS features:

+302

app/components/data-binding.js

reviewed

··· 1 1 + /** 2 2 + * Data Binding Utilities for Components 3 3 + * 4 4 + * Provides reactive data binding capabilities for Peek components. 5 5 + * Integrates with signals, schema validation, and external data sources. 6 6 + * 7 7 + * @example 8 8 + * import { DataBoundElement } from './data-binding.js'; 9 9 + * import { signal } from './signals.js'; 10 10 + * 11 11 + * class MyComponent extends DataBoundElement { 12 12 + * static dataSchema = { 13 13 + * type: 'object', 14 14 + * properties: { 15 15 + * title: { type: 'string' }, 16 16 + * count: { type: 'integer', default: 0 } 17 17 + * } 18 18 + * }; 19 19 + * 20 20 + * render() { 21 21 + * return html`<div>${this.data.title}: ${this.data.count}</div>`; 22 22 + * } 23 23 + * } 24 24 + * 25 25 + * // Bind to a signal 26 26 + * const dataSignal = signal({ title: 'Hello', count: 5 }); 27 27 + * const el = document.createElement('my-component'); 28 28 + * el.bindTo(dataSignal); 29 29 + */ 30 30 + 31 31 + import { PeekElement, sharedStyles } from './base.js'; 32 32 + import { effect } from './signals.js'; 33 33 + import { validate, applyDefaults } from './schema.js'; 34 34 + 35 35 + /** 36 36 + * Mixin that adds data binding capabilities to a component 37 37 + * 38 38 + * @param {typeof LitElement} Base - Base class to extend 39 39 + * @returns {typeof DataBoundElement} 40 40 + */ 41 41 + export function DataBindingMixin(Base) { 42 42 + return class extends Base { 43 43 + static properties = { 44 44 + ...Base.properties, 45 45 + data: { type: Object } 46 46 + }; 47 47 + 48 48 + /** 49 49 + * Optional JSON Schema for data validation. 50 50 + * Override in subclass to enable validation. 51 51 + * @type {Object|null} 52 52 + */ 53 53 + static dataSchema = null; 54 54 + 55 55 + constructor() { 56 56 + super(); 57 57 + this._data = {}; 58 58 + this._boundSource = null; 59 59 + this._effectDispose = null; 60 60 + this._subscriptions = []; 61 61 + } 62 62 + 63 63 + /** 64 64 + * Get the current data object 65 65 + */ 66 66 + get data() { 67 67 + return this._data; 68 68 + } 69 69 + 70 70 + /** 71 71 + * Set data directly (validates if schema defined) 72 72 + */ 73 73 + set data(value) { 74 74 + const schema = this.constructor.dataSchema; 75 75 + if (schema) { 76 76 + const result = validate(value, schema); 77 77 + if (!result.valid) { 78 78 + console.warn(`[${this.tagName}] Data validation failed:`, result.errors); 79 79 + } 80 80 + this._data = result.data; 81 81 + } else { 82 82 + this._data = value; 83 83 + } 84 84 + this.requestUpdate(); 85 85 + } 86 86 + 87 87 + /** 88 88 + * Bind component to a reactive data source (signal, observable, etc.) 89 89 + * 90 90 + * @param {Object} source - Data source with .value property or subscribe method 91 91 + * @param {Object} [options] 92 92 + * @param {Function} [options.transform] - Transform data before setting 93 93 + * @param {string} [options.path] - Dot-notation path to extract from source 94 94 + * @returns {() => void} - Unbind function 95 95 + * 96 96 + * @example 97 97 + * // Bind to signal 98 98 + * const data = signal({ title: 'Hello' }); 99 99 + * element.bindTo(data); 100 100 + * 101 101 + * // Bind with transform 102 102 + * element.bindTo(rawData, { 103 103 + * transform: (d) => ({ title: d.name, count: d.items.length }) 104 104 + * }); 105 105 + * 106 106 + * // Bind to nested path 107 107 + * element.bindTo(store, { path: 'user.profile' }); 108 108 + */ 109 109 + bindTo(source, options = {}) { 110 110 + // Unbind previous source 111 111 + this.unbind(); 112 112 + 113 113 + this._boundSource = source; 114 114 + const { transform, path } = options; 115 115 + 116 116 + const updateData = () => { 117 117 + let value; 118 118 + 119 119 + // Get value from source 120 120 + if ('value' in source) { 121 121 + value = source.value; 122 122 + } else if (typeof source.get === 'function') { 123 123 + value = source.get(); 124 124 + } else { 125 125 + value = source; 126 126 + } 127 127 + 128 128 + // Extract nested path if specified 129 129 + if (path) { 130 130 + value = getPath(value, path); 131 131 + } 132 132 + 133 133 + // Apply transform if specified 134 134 + if (transform) { 135 135 + value = transform(value); 136 136 + } 137 137 + 138 138 + this.data = value; 139 139 + }; 140 140 + 141 141 + // Set up reactive subscription 142 142 + if ('value' in source) { 143 143 + // Signal-like source - use effect for automatic tracking 144 144 + this._effectDispose = effect(() => { 145 145 + // Access .value to track dependency 146 146 + const _ = source.value; 147 147 + updateData(); 148 148 + }); 149 149 + } else if (typeof source.subscribe === 'function') { 150 150 + // Observable-like source 151 151 + const unsubscribe = source.subscribe(updateData); 152 152 + this._subscriptions.push(unsubscribe); 153 153 + updateData(); // Initial value 154 154 + } else { 155 155 + // Static data - just set once 156 156 + updateData(); 157 157 + } 158 158 + 159 159 + return () => this.unbind(); 160 160 + } 161 161 + 162 162 + /** 163 163 + * Unbind from current data source 164 164 + */ 165 165 + unbind() { 166 166 + if (this._effectDispose) { 167 167 + this._effectDispose(); 168 168 + this._effectDispose = null; 169 169 + } 170 170 + for (const unsub of this._subscriptions) { 171 171 + unsub(); 172 172 + } 173 173 + this._subscriptions = []; 174 174 + this._boundSource = null; 175 175 + } 176 176 + 177 177 + /** 178 178 + * Check if component is bound to a data source 179 179 + */ 180 180 + get isBound() { 181 181 + return this._boundSource !== null; 182 182 + } 183 183 + 184 184 + /** 185 185 + * Update a single property in data (triggers re-render) 186 186 + * @param {string} key - Property name 187 187 + * @param {*} value - New value 188 188 + */ 189 189 + updateData(key, value) { 190 190 + this.data = { ...this._data, [key]: value }; 191 191 + } 192 192 + 193 193 + /** 194 194 + * Merge partial data into current data 195 195 + * @param {Object} partial - Partial data to merge 196 196 + */ 197 197 + mergeData(partial) { 198 198 + this.data = { ...this._data, ...partial }; 199 199 + } 200 200 + 201 201 + disconnectedCallback() { 202 202 + super.disconnectedCallback(); 203 203 + this.unbind(); 204 204 + } 205 205 + }; 206 206 + } 207 207 + 208 208 + /** 209 209 + * Data-bound element base class 210 210 + * Extends PeekElement with data binding capabilities 211 211 + */ 212 212 + export class DataBoundElement extends DataBindingMixin(PeekElement) { 213 213 + static styles = [sharedStyles]; 214 214 + } 215 215 + 216 216 + /** 217 217 + * Get nested value from object using dot notation 218 218 + * @param {Object} obj 219 219 + * @param {string} path - e.g., "user.profile.name" 220 220 + * @returns {*} 221 221 + */ 222 222 + function getPath(obj, path) { 223 223 + return path.split('.').reduce((current, key) => { 224 224 + return current && current[key] !== undefined ? current[key] : undefined; 225 225 + }, obj); 226 226 + } 227 227 + 228 228 + /** 229 229 + * Create a data-bound component dynamically 230 230 + * 231 231 + * @param {string} tagName - Custom element tag name 232 232 + * @param {Object} options 233 233 + * @param {Function} options.render - Render function (data) => TemplateResult 234 234 + * @param {Object} [options.schema] - Data schema 235 235 + * @param {CSSResult[]} [options.styles] - Additional styles 236 236 + * @returns {typeof DataBoundElement} 237 237 + * 238 238 + * @example 239 239 + * const UserCard = createDataComponent('user-card', { 240 240 + * schema: { 241 241 + * type: 'object', 242 242 + * properties: { 243 243 + * name: { type: 'string' }, 244 244 + * avatar: { type: 'string', format: 'uri' } 245 245 + * } 246 246 + * }, 247 247 + * render: (data) => html` 248 248 + * <img src=${data.avatar}> 249 249 + * <span>${data.name}</span> 250 250 + * ` 251 251 + * }); 252 252 + */ 253 253 + export function createDataComponent(tagName, options) { 254 254 + const { render: renderFn, schema, styles = [] } = options; 255 255 + 256 256 + class DynamicComponent extends DataBoundElement { 257 257 + static dataSchema = schema; 258 258 + static styles = [sharedStyles, ...styles]; 259 259 + 260 260 + render() { 261 261 + return renderFn(this.data, this); 262 262 + } 263 263 + } 264 264 + 265 265 + customElements.define(tagName, DynamicComponent); 266 266 + return DynamicComponent; 267 267 + } 268 268 + 269 269 + /** 270 270 + * Decorator for data-bound properties 271 271 + * Automatically validates against schema when property changes 272 272 + * 273 273 + * @param {Object} schema - Property schema 274 274 + */ 275 275 + export function validatedProperty(schema) { 276 276 + return function(target, propertyKey) { 277 277 + const privateKey = `_${propertyKey}`; 278 278 + 279 279 + Object.defineProperty(target, propertyKey, { 280 280 + get() { 281 281 + return this[privateKey]; 282 282 + }, 283 283 + set(value) { 284 284 + const result = validate(value, schema); 285 285 + if (!result.valid) { 286 286 + console.warn(`[${this.tagName}] Property '${propertyKey}' validation failed:`, result.errors); 287 287 + } 288 288 + this[privateKey] = result.data; 289 289 + this.requestUpdate(); 290 290 + }, 291 291 + configurable: true, 292 292 + enumerable: true 293 293 + }); 294 294 + }; 295 295 + } 296 296 + 297 297 + export default { 298 298 + DataBindingMixin, 299 299 + DataBoundElement, 300 300 + createDataComponent, 301 301 + validatedProperty 302 302 + };

+390

app/components/events.js

reviewed

··· 1 1 + /** 2 2 + * Component Communication Bus 3 3 + * 4 4 + * A lightweight pubsub system for cross-component communication. 5 5 + * Works across Shadow DOM boundaries and supports typed events. 6 6 + * 7 7 + * @example 8 8 + * import { bus, on, emit, channel } from './events.js'; 9 9 + * 10 10 + * // Subscribe to events 11 11 + * const unsubscribe = on('user:login', (user) => { 12 12 + * console.log('User logged in:', user); 13 13 + * }); 14 14 + * 15 15 + * // Publish events 16 16 + * emit('user:login', { name: 'Alice', id: 123 }); 17 17 + * 18 18 + * // Create typed channels 19 19 + * const userChannel = channel('user'); 20 20 + * userChannel.on('login', handler); 21 21 + * userChannel.emit('login', userData); 22 22 + */ 23 23 + 24 24 + /** 25 25 + * @typedef {Object} Subscription 26 26 + * @property {() => void} unsubscribe - Stop receiving events 27 27 + * @property {boolean} active - Whether subscription is active 28 28 + */ 29 29 + 30 30 + /** 31 31 + * Event bus instance 32 32 + */ 33 33 + class EventBus { 34 34 + constructor() { 35 35 + /** @type {Map<string, Set<Function>>} */ 36 36 + this._handlers = new Map(); 37 37 + /** @type {Map<string, *>} */ 38 38 + this._lastValues = new Map(); 39 39 + } 40 40 + 41 41 + /** 42 42 + * Subscribe to an event 43 43 + * @param {string} event - Event name (supports wildcards: 'user:*') 44 44 + * @param {Function} handler - Event handler 45 45 + * @param {Object} [options] 46 46 + * @param {boolean} [options.once=false] - Only handle once then unsubscribe 47 47 + * @param {boolean} [options.replay=false] - Replay last value immediately if available 48 48 + * @returns {Subscription} 49 49 + */ 50 50 + on(event, handler, options = {}) { 51 51 + const { once = false, replay = false } = options; 52 52 + 53 53 + let wrappedHandler = handler; 54 54 + let active = true; 55 55 + 56 56 + if (once) { 57 57 + wrappedHandler = (...args) => { 58 58 + if (active) { 59 59 + active = false; 60 60 + this._removeHandler(event, wrappedHandler); 61 61 + handler(...args); 62 62 + } 63 63 + }; 64 64 + } 65 65 + 66 66 + if (!this._handlers.has(event)) { 67 67 + this._handlers.set(event, new Set()); 68 68 + } 69 69 + this._handlers.get(event).add(wrappedHandler); 70 70 + 71 71 + // Replay last value if requested and available 72 72 + if (replay && this._lastValues.has(event)) { 73 73 + queueMicrotask(() => { 74 74 + if (active) { 75 75 + wrappedHandler(this._lastValues.get(event)); 76 76 + } 77 77 + }); 78 78 + } 79 79 + 80 80 + return { 81 81 + unsubscribe: () => { 82 82 + active = false; 83 83 + this._removeHandler(event, wrappedHandler); 84 84 + }, 85 85 + get active() { 86 86 + return active; 87 87 + } 88 88 + }; 89 89 + } 90 90 + 91 91 + /** 92 92 + * Subscribe to event, receiving only the next occurrence 93 93 + * @param {string} event 94 94 + * @param {Function} handler 95 95 + * @returns {Subscription} 96 96 + */ 97 97 + once(event, handler) { 98 98 + return this.on(event, handler, { once: true }); 99 99 + } 100 100 + 101 101 + /** 102 102 + * Emit an event to all subscribers 103 103 + * @param {string} event - Event name 104 104 + * @param {*} [data] - Event data 105 105 + * @param {Object} [options] 106 106 + * @param {boolean} [options.retain=false] - Store value for replay 107 107 + */ 108 108 + emit(event, data, options = {}) { 109 109 + const { retain = false } = options; 110 110 + 111 111 + if (retain) { 112 112 + this._lastValues.set(event, data); 113 113 + } 114 114 + 115 115 + // Exact match handlers 116 116 + const handlers = this._handlers.get(event); 117 117 + if (handlers) { 118 118 + for (const handler of [...handlers]) { 119 119 + try { 120 120 + handler(data); 121 121 + } catch (error) { 122 122 + console.error(`[EventBus] Error in handler for '${event}':`, error); 123 123 + } 124 124 + } 125 125 + } 126 126 + 127 127 + // Wildcard handlers (e.g., 'user:*' matches 'user:login') 128 128 + for (const [pattern, patternHandlers] of this._handlers) { 129 129 + if (pattern.endsWith(':*')) { 130 130 + const prefix = pattern.slice(0, -1); 131 131 + if (event.startsWith(prefix) && pattern !== event) { 132 132 + for (const handler of [...patternHandlers]) { 133 133 + try { 134 134 + handler(data, event); 135 135 + } catch (error) { 136 136 + console.error(`[EventBus] Error in wildcard handler for '${event}':`, error); 137 137 + } 138 138 + } 139 139 + } 140 140 + } 141 141 + } 142 142 + } 143 143 + 144 144 + /** 145 145 + * Remove all handlers for an event 146 146 + * @param {string} event 147 147 + */ 148 148 + off(event) { 149 149 + this._handlers.delete(event); 150 150 + this._lastValues.delete(event); 151 151 + } 152 152 + 153 153 + /** 154 154 + * Remove all handlers and clear state 155 155 + */ 156 156 + clear() { 157 157 + this._handlers.clear(); 158 158 + this._lastValues.clear(); 159 159 + } 160 160 + 161 161 + /** 162 162 + * Get count of handlers for an event 163 163 + * @param {string} event 164 164 + * @returns {number} 165 165 + */ 166 166 + listenerCount(event) { 167 167 + return this._handlers.get(event)?.size ?? 0; 168 168 + } 169 169 + 170 170 + _removeHandler(event, handler) { 171 171 + const handlers = this._handlers.get(event); 172 172 + if (handlers) { 173 173 + handlers.delete(handler); 174 174 + if (handlers.size === 0) { 175 175 + this._handlers.delete(event); 176 176 + } 177 177 + } 178 178 + } 179 179 + } 180 180 + 181 181 + /** 182 182 + * Global event bus instance 183 183 + */ 184 184 + export const bus = new EventBus(); 185 185 + 186 186 + /** 187 187 + * Subscribe to an event on the global bus 188 188 + * @param {string} event 189 189 + * @param {Function} handler 190 190 + * @param {Object} [options] 191 191 + * @returns {Subscription} 192 192 + */ 193 193 + export function on(event, handler, options) { 194 194 + return bus.on(event, handler, options); 195 195 + } 196 196 + 197 197 + /** 198 198 + * Subscribe once to an event 199 199 + * @param {string} event 200 200 + * @param {Function} handler 201 201 + * @returns {Subscription} 202 202 + */ 203 203 + export function once(event, handler) { 204 204 + return bus.once(event, handler); 205 205 + } 206 206 + 207 207 + /** 208 208 + * Emit an event on the global bus 209 209 + * @param {string} event 210 210 + * @param {*} [data] 211 211 + * @param {Object} [options] 212 212 + */ 213 213 + export function emit(event, data, options) { 214 214 + bus.emit(event, data, options); 215 215 + } 216 216 + 217 217 + /** 218 218 + * Create a namespaced channel 219 219 + * 220 220 + * @param {string} namespace - Channel namespace (e.g., 'user', 'editor') 221 221 + * @returns {Channel} 222 222 + * 223 223 + * @example 224 224 + * const userChannel = channel('user'); 225 225 + * userChannel.on('login', (user) => console.log(user)); 226 226 + * userChannel.emit('login', { name: 'Alice' }); 227 227 + * // Equivalent to: bus.emit('user:login', { name: 'Alice' }) 228 228 + */ 229 229 + export function channel(namespace) { 230 230 + return { 231 231 + on(event, handler, options) { 232 232 + return bus.on(`${namespace}:${event}`, handler, options); 233 233 + }, 234 234 + once(event, handler) { 235 235 + return bus.once(`${namespace}:${event}`, handler); 236 236 + }, 237 237 + emit(event, data, options) { 238 238 + bus.emit(`${namespace}:${event}`, data, options); 239 239 + }, 240 240 + off(event) { 241 241 + bus.off(`${namespace}:${event}`); 242 242 + }, 243 243 + /** 244 244 + * Subscribe to all events in this channel 245 245 + */ 246 246 + onAny(handler, options) { 247 247 + return bus.on(`${namespace}:*`, handler, options); 248 248 + } 249 249 + }; 250 250 + } 251 251 + 252 252 + /** 253 253 + * Create a typed event emitter for a specific event 254 254 + * 255 255 + * @template T 256 256 + * @param {string} event - Event name 257 257 + * @returns {{ emit: (data: T) => void, on: (handler: (data: T) => void) => Subscription }} 258 258 + * 259 259 + * @example 260 260 + * const userLogin = typedEvent('user:login'); 261 261 + * userLogin.on((user) => console.log(user.name)); 262 262 + * userLogin.emit({ name: 'Alice', id: 123 }); 263 263 + */ 264 264 + export function typedEvent(event) { 265 265 + return { 266 266 + emit(data, options) { 267 267 + bus.emit(event, data, options); 268 268 + }, 269 269 + on(handler, options) { 270 270 + return bus.on(event, handler, options); 271 271 + }, 272 272 + once(handler) { 273 273 + return bus.once(event, handler); 274 274 + } 275 275 + }; 276 276 + } 277 277 + 278 278 + /** 279 279 + * Wait for an event (Promise-based) 280 280 + * 281 281 + * @param {string} event - Event to wait for 282 282 + * @param {Object} [options] 283 283 + * @param {number} [options.timeout] - Timeout in ms (rejects if exceeded) 284 284 + * @param {Function} [options.filter] - Only resolve if filter returns true 285 285 + * @returns {Promise<*>} 286 286 + * 287 287 + * @example 288 288 + * const userData = await waitFor('user:login', { timeout: 5000 }); 289 289 + */ 290 290 + export function waitFor(event, options = {}) { 291 291 + const { timeout, filter } = options; 292 292 + 293 293 + return new Promise((resolve, reject) => { 294 294 + let timeoutId; 295 295 + let subscription; 296 296 + 297 297 + const cleanup = () => { 298 298 + if (timeoutId) clearTimeout(timeoutId); 299 299 + if (subscription) subscription.unsubscribe(); 300 300 + }; 301 301 + 302 302 + subscription = bus.on(event, (data) => { 303 303 + if (!filter || filter(data)) { 304 304 + cleanup(); 305 305 + resolve(data); 306 306 + } 307 307 + }); 308 308 + 309 309 + if (timeout) { 310 310 + timeoutId = setTimeout(() => { 311 311 + cleanup(); 312 312 + reject(new Error(`Timeout waiting for event: ${event}`)); 313 313 + }, timeout); 314 314 + } 315 315 + }); 316 316 + } 317 317 + 318 318 + /** 319 319 + * Mixin that adds event bus methods to a component 320 320 + * 321 321 + * @param {typeof LitElement} Base 322 322 + * @returns {typeof LitElement} 323 323 + * 324 324 + * @example 325 325 + * class MyComponent extends EventBusMixin(LitElement) { 326 326 + * connectedCallback() { 327 327 + * super.connectedCallback(); 328 328 + * this.subscribe('data:update', this.handleUpdate); 329 329 + * } 330 330 + * 331 331 + * handleUpdate = (data) => { 332 332 + * this.data = data; 333 333 + * } 334 334 + * } 335 335 + */ 336 336 + export function EventBusMixin(Base) { 337 337 + return class extends Base { 338 338 + constructor() { 339 339 + super(); 340 340 + this._busSubscriptions = []; 341 341 + } 342 342 + 343 343 + /** 344 344 + * Subscribe to an event (auto-cleanup on disconnect) 345 345 + */ 346 346 + subscribe(event, handler, options) { 347 347 + const sub = bus.on(event, handler, options); 348 348 + this._busSubscriptions.push(sub); 349 349 + return sub; 350 350 + } 351 351 + 352 352 + /** 353 353 + * Emit an event 354 354 + */ 355 355 + publish(event, data, options) { 356 356 + bus.emit(event, data, options); 357 357 + } 358 358 + 359 359 + disconnectedCallback() { 360 360 + super.disconnectedCallback(); 361 361 + // Clean up all subscriptions 362 362 + for (const sub of this._busSubscriptions) { 363 363 + sub.unsubscribe(); 364 364 + } 365 365 + this._busSubscriptions = []; 366 366 + } 367 367 + }; 368 368 + } 369 369 + 370 370 + /** 371 371 + * Create a new isolated event bus instance 372 372 + * Useful for testing or isolated component trees 373 373 + * 374 374 + * @returns {EventBus} 375 375 + */ 376 376 + export function createBus() { 377 377 + return new EventBus(); 378 378 + } 379 379 + 380 380 + export default { 381 381 + bus, 382 382 + on, 383 383 + once, 384 384 + emit, 385 385 + channel, 386 386 + typedEvent, 387 387 + waitFor, 388 388 + EventBusMixin, 389 389 + createBus 390 390 + };

+16 -4

app/components/index.js

reviewed

··· 8 8 * Usage: 9 9 * import 'peek://app/components/index.js'; 10 10 * 11 11 - * Or import individual components: 12 12 - * import 'peek://app/components/peek-button.js'; 13 13 - * import 'peek://app/components/peek-card.js'; 14 14 - * import 'peek://app/components/peek-list.js'; 11 11 + * Or import individual modules: 12 12 + * import { signal, effect } from 'peek://app/components/signals.js'; 13 13 + * import { on, emit } from 'peek://app/components/events.js'; 14 14 + * import { DataBoundElement } from 'peek://app/components/data-binding.js'; 15 15 * 16 16 * Components automatically register with the custom elements registry. 17 17 * ··· 22 22 23 23 // Base utilities 24 24 export { PeekElement, sharedStyles } from './base.js'; 25 25 + 26 26 + // Reactive system 27 27 + export { signal, computed, effect, batch, watch, fromExternal } from './signals.js'; 28 28 + 29 29 + // Schema validation 30 30 + export { validate, createValidator, assertValid, isValid, Schema } from './schema.js'; 31 31 + 32 32 + // Data binding 33 33 + export { DataBoundElement, DataBindingMixin, createDataComponent } from './data-binding.js'; 34 34 + 35 35 + // Event bus 36 36 + export { bus, on, once, emit, channel, typedEvent, waitFor, EventBusMixin } from './events.js'; 25 37 26 38 // Components 27 39 export { PeekButton } from './peek-button.js';

+390

app/components/schema.js

reviewed

··· 1 1 + /** 2 2 + * Lightweight Schema Validation 3 3 + * 4 4 + * A native JSON Schema validator supporting common validation patterns. 5 5 + * No external dependencies - covers typical component data validation needs. 6 6 + * 7 7 + * Supported JSON Schema keywords: 8 8 + * - type: string, number, integer, boolean, array, object, null 9 9 + * - required: array of required property names 10 10 + * - properties: object property schemas 11 11 + * - items: array item schema 12 12 + * - enum: allowed values 13 13 + * - minimum, maximum: number bounds 14 14 + * - minLength, maxLength: string length 15 15 + * - minItems, maxItems: array length 16 16 + * - pattern: regex pattern for strings 17 17 + * - format: common formats (email, uri, date, date-time) 18 18 + * - default: default value 19 19 + * 20 20 + * @example 21 21 + * import { createValidator, validate } from './schema.js'; 22 22 + * 23 23 + * const schema = { 24 24 + * type: 'object', 25 25 + * required: ['title'], 26 26 + * properties: { 27 27 + * title: { type: 'string', minLength: 1 }, 28 28 + * count: { type: 'integer', minimum: 0 } 29 29 + * } 30 30 + * }; 31 31 + * 32 32 + * const validator = createValidator(schema); 33 33 + * const result = validator({ title: 'Test', count: 5 }); 34 34 + * // { valid: true, errors: [], data: { title: 'Test', count: 5 } } 35 35 + */ 36 36 + 37 37 + /** 38 38 + * Validation result 39 39 + * @typedef {Object} ValidationResult 40 40 + * @property {boolean} valid - Whether data is valid 41 41 + * @property {ValidationError[]} errors - Array of validation errors 42 42 + * @property {*} data - The validated data (with defaults applied) 43 43 + */ 44 44 + 45 45 + /** 46 46 + * Validation error 47 47 + * @typedef {Object} ValidationError 48 48 + * @property {string} path - JSON path to the error (e.g., ".items[0].name") 49 49 + * @property {string} message - Human-readable error message 50 50 + * @property {string} keyword - Schema keyword that failed 51 51 + */ 52 52 + 53 53 + // Common format validators 54 54 + const FORMATS = { 55 55 + email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, 56 56 + uri: /^https?:\/\/.+/, 57 57 + 'date-time': /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/, 58 58 + date: /^\d{4}-\d{2}-\d{2}$/, 59 59 + time: /^\d{2}:\d{2}:\d{2}(\.\d+)?$/, 60 60 + uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i 61 61 + }; 62 62 + 63 63 + /** 64 64 + * Get the type of a value 65 65 + * @param {*} value 66 66 + * @returns {string} 67 67 + */ 68 68 + function getType(value) { 69 69 + if (value === null) return 'null'; 70 70 + if (Array.isArray(value)) return 'array'; 71 71 + return typeof value; 72 72 + } 73 73 + 74 74 + /** 75 75 + * Check if value matches expected type 76 76 + * @param {*} value 77 77 + * @param {string|string[]} type 78 78 + * @returns {boolean} 79 79 + */ 80 80 + function checkType(value, type) { 81 81 + const types = Array.isArray(type) ? type : [type]; 82 82 + const actualType = getType(value); 83 83 + 84 84 + return types.some(t => { 85 85 + if (t === 'integer') { 86 86 + return actualType === 'number' && Number.isInteger(value); 87 87 + } 88 88 + return actualType === t; 89 89 + }); 90 90 + } 91 91 + 92 92 + /** 93 93 + * Validate a value against a schema 94 94 + * @param {*} value - Value to validate 95 95 + * @param {Object} schema - JSON Schema 96 96 + * @param {string} [path=''] - Current path for error messages 97 97 + * @returns {ValidationResult} 98 98 + */ 99 99 + export function validate(value, schema, path = '') { 100 100 + const errors = []; 101 101 + let data = value; 102 102 + 103 103 + // Handle default value 104 104 + if (value === undefined && schema.default !== undefined) { 105 105 + data = structuredClone(schema.default); 106 106 + value = data; 107 107 + } 108 108 + 109 109 + // Null check 110 110 + if (value === undefined || value === null) { 111 111 + if (schema.type && !checkType(value, schema.type)) { 112 112 + errors.push({ 113 113 + path, 114 114 + message: `Expected ${schema.type}, got ${getType(value)}`, 115 115 + keyword: 'type' 116 116 + }); 117 117 + } 118 118 + return { valid: errors.length === 0, errors, data }; 119 119 + } 120 120 + 121 121 + // Type validation 122 122 + if (schema.type && !checkType(value, schema.type)) { 123 123 + errors.push({ 124 124 + path, 125 125 + message: `Expected ${Array.isArray(schema.type) ? schema.type.join(' | ') : schema.type}, got ${getType(value)}`, 126 126 + keyword: 'type' 127 127 + }); 128 128 + return { valid: false, errors, data }; 129 129 + } 130 130 + 131 131 + // Enum validation 132 132 + if (schema.enum && !schema.enum.includes(value)) { 133 133 + errors.push({ 134 134 + path, 135 135 + message: `Value must be one of: ${schema.enum.join(', ')}`, 136 136 + keyword: 'enum' 137 137 + }); 138 138 + } 139 139 + 140 140 + // String validations 141 141 + if (typeof value === 'string') { 142 142 + if (schema.minLength !== undefined && value.length < schema.minLength) { 143 143 + errors.push({ 144 144 + path, 145 145 + message: `String must be at least ${schema.minLength} characters`, 146 146 + keyword: 'minLength' 147 147 + }); 148 148 + } 149 149 + if (schema.maxLength !== undefined && value.length > schema.maxLength) { 150 150 + errors.push({ 151 151 + path, 152 152 + message: `String must be at most ${schema.maxLength} characters`, 153 153 + keyword: 'maxLength' 154 154 + }); 155 155 + } 156 156 + if (schema.pattern) { 157 157 + const regex = new RegExp(schema.pattern); 158 158 + if (!regex.test(value)) { 159 159 + errors.push({ 160 160 + path, 161 161 + message: `String must match pattern: ${schema.pattern}`, 162 162 + keyword: 'pattern' 163 163 + }); 164 164 + } 165 165 + } 166 166 + if (schema.format && FORMATS[schema.format]) { 167 167 + if (!FORMATS[schema.format].test(value)) { 168 168 + errors.push({ 169 169 + path, 170 170 + message: `Invalid ${schema.format} format`, 171 171 + keyword: 'format' 172 172 + }); 173 173 + } 174 174 + } 175 175 + } 176 176 + 177 177 + // Number validations 178 178 + if (typeof value === 'number') { 179 179 + if (schema.minimum !== undefined && value < schema.minimum) { 180 180 + errors.push({ 181 181 + path, 182 182 + message: `Value must be >= ${schema.minimum}`, 183 183 + keyword: 'minimum' 184 184 + }); 185 185 + } 186 186 + if (schema.maximum !== undefined && value > schema.maximum) { 187 187 + errors.push({ 188 188 + path, 189 189 + message: `Value must be <= ${schema.maximum}`, 190 190 + keyword: 'maximum' 191 191 + }); 192 192 + } 193 193 + if (schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) { 194 194 + errors.push({ 195 195 + path, 196 196 + message: `Value must be > ${schema.exclusiveMinimum}`, 197 197 + keyword: 'exclusiveMinimum' 198 198 + }); 199 199 + } 200 200 + if (schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) { 201 201 + errors.push({ 202 202 + path, 203 203 + message: `Value must be < ${schema.exclusiveMaximum}`, 204 204 + keyword: 'exclusiveMaximum' 205 205 + }); 206 206 + } 207 207 + } 208 208 + 209 209 + // Array validations 210 210 + if (Array.isArray(value)) { 211 211 + if (schema.minItems !== undefined && value.length < schema.minItems) { 212 212 + errors.push({ 213 213 + path, 214 214 + message: `Array must have at least ${schema.minItems} items`, 215 215 + keyword: 'minItems' 216 216 + }); 217 217 + } 218 218 + if (schema.maxItems !== undefined && value.length > schema.maxItems) { 219 219 + errors.push({ 220 220 + path, 221 221 + message: `Array must have at most ${schema.maxItems} items`, 222 222 + keyword: 'maxItems' 223 223 + }); 224 224 + } 225 225 + if (schema.uniqueItems && new Set(value.map(JSON.stringify)).size !== value.length) { 226 226 + errors.push({ 227 227 + path, 228 228 + message: 'Array items must be unique', 229 229 + keyword: 'uniqueItems' 230 230 + }); 231 231 + } 232 232 + if (schema.items) { 233 233 + data = value.map((item, index) => { 234 234 + const result = validate(item, schema.items, `${path}[${index}]`); 235 235 + errors.push(...result.errors); 236 236 + return result.data; 237 237 + }); 238 238 + } 239 239 + } 240 240 + 241 241 + // Object validations 242 242 + if (getType(value) === 'object') { 243 243 + // Clone to apply defaults 244 244 + data = { ...value }; 245 245 + 246 246 + // Required properties 247 247 + if (schema.required) { 248 248 + for (const key of schema.required) { 249 249 + if (!(key in value)) { 250 250 + errors.push({ 251 251 + path: path ? `${path}.${key}` : key, 252 252 + message: `Missing required property: ${key}`, 253 253 + keyword: 'required' 254 254 + }); 255 255 + } 256 256 + } 257 257 + } 258 258 + 259 259 + // Property validation 260 260 + if (schema.properties) { 261 261 + for (const [key, propSchema] of Object.entries(schema.properties)) { 262 262 + const propPath = path ? `${path}.${key}` : key; 263 263 + const result = validate(value[key], propSchema, propPath); 264 264 + errors.push(...result.errors); 265 265 + if (result.data !== undefined) { 266 266 + data[key] = result.data; 267 267 + } 268 268 + } 269 269 + } 270 270 + 271 271 + // Additional properties check 272 272 + if (schema.additionalProperties === false && schema.properties) { 273 273 + const allowed = new Set(Object.keys(schema.properties)); 274 274 + for (const key of Object.keys(value)) { 275 275 + if (!allowed.has(key)) { 276 276 + errors.push({ 277 277 + path: path ? `${path}.${key}` : key, 278 278 + message: `Unknown property: ${key}`, 279 279 + keyword: 'additionalProperties' 280 280 + }); 281 281 + } 282 282 + } 283 283 + } 284 284 + } 285 285 + 286 286 + return { valid: errors.length === 0, errors, data }; 287 287 + } 288 288 + 289 289 + /** 290 290 + * Create a reusable validator function from a schema 291 291 + * @param {Object} schema - JSON Schema 292 292 + * @returns {(value: *) => ValidationResult} 293 293 + * 294 294 + * @example 295 295 + * const validateUser = createValidator({ 296 296 + * type: 'object', 297 297 + * required: ['name', 'email'], 298 298 + * properties: { 299 299 + * name: { type: 'string', minLength: 1 }, 300 300 + * email: { type: 'string', format: 'email' } 301 301 + * } 302 302 + * }); 303 303 + * 304 304 + * const result = validateUser({ name: 'Alice', email: 'alice@example.com' }); 305 305 + */ 306 306 + export function createValidator(schema) { 307 307 + return (value) => validate(value, schema); 308 308 + } 309 309 + 310 310 + /** 311 311 + * Assert that data is valid, throwing if not 312 312 + * @param {*} value - Value to validate 313 313 + * @param {Object} schema - JSON Schema 314 314 + * @throws {ValidationError} If validation fails 315 315 + * 316 316 + * @example 317 317 + * assertValid({ name: '' }, { type: 'object', properties: { name: { minLength: 1 } } }); 318 318 + * // Throws: ValidationError: name: String must be at least 1 characters 319 319 + */ 320 320 + export function assertValid(value, schema) { 321 321 + const result = validate(value, schema); 322 322 + if (!result.valid) { 323 323 + const error = new Error( 324 324 + result.errors.map(e => `${e.path || 'root'}: ${e.message}`).join('; ') 325 325 + ); 326 326 + error.name = 'ValidationError'; 327 327 + error.errors = result.errors; 328 328 + throw error; 329 329 + } 330 330 + return result.data; 331 331 + } 332 332 + 333 333 + /** 334 334 + * Check if value is valid (boolean result only) 335 335 + * @param {*} value 336 336 + * @param {Object} schema 337 337 + * @returns {boolean} 338 338 + */ 339 339 + export function isValid(value, schema) { 340 340 + return validate(value, schema).valid; 341 341 + } 342 342 + 343 343 + /** 344 344 + * Apply defaults from schema to value 345 345 + * @param {*} value 346 346 + * @param {Object} schema 347 347 + * @returns {*} Value with defaults applied 348 348 + */ 349 349 + export function applyDefaults(value, schema) { 350 350 + return validate(value, schema).data; 351 351 + } 352 352 + 353 353 + /** 354 354 + * Common schema builders for convenience 355 355 + */ 356 356 + export const Schema = { 357 357 + string(options = {}) { 358 358 + return { type: 'string', ...options }; 359 359 + }, 360 360 + 361 361 + number(options = {}) { 362 362 + return { type: 'number', ...options }; 363 363 + }, 364 364 + 365 365 + integer(options = {}) { 366 366 + return { type: 'integer', ...options }; 367 367 + }, 368 368 + 369 369 + boolean(options = {}) { 370 370 + return { type: 'boolean', ...options }; 371 371 + }, 372 372 + 373 373 + array(items, options = {}) { 374 374 + return { type: 'array', items, ...options }; 375 375 + }, 376 376 + 377 377 + object(properties, options = {}) { 378 378 + return { type: 'object', properties, ...options }; 379 379 + }, 380 380 + 381 381 + enum(values, options = {}) { 382 382 + return { enum: values, ...options }; 383 383 + }, 384 384 + 385 385 + nullable(schema) { 386 386 + return { ...schema, type: [schema.type, 'null'] }; 387 387 + } 388 388 + }; 389 389 + 390 390 + export default { validate, createValidator, assertValid, isValid, applyDefaults, Schema };

+344

app/components/signals.js

reviewed

··· 1 1 + /** 2 2 + * Native Signals Implementation 3 3 + * 4 4 + * A lightweight reactive primitives library following the TC39 Signals proposal pattern. 5 5 + * No external dependencies - pure JavaScript implementation. 6 6 + * 7 7 + * @example 8 8 + * import { signal, computed, effect } from './signals.js'; 9 9 + * 10 10 + * const count = signal(0); 11 11 + * const doubled = computed(() => count.value * 2); 12 12 + * 13 13 + * effect(() => { 14 14 + * console.log('Count:', count.value, 'Doubled:', doubled.value); 15 15 + * }); 16 16 + * 17 17 + * count.value = 5; // Logs: "Count: 5 Doubled: 10" 18 18 + */ 19 19 + 20 20 + // Track the currently running effect for automatic dependency collection 21 21 + let currentEffect = null; 22 22 + const effectStack = []; 23 23 + 24 24 + /** 25 25 + * Signal - A reactive value container 26 26 + * 27 27 + * @template T 28 28 + * @param {T} initialValue - Initial value 29 29 + * @returns {Signal<T>} - Signal object with .value property 30 30 + * 31 31 + * @example 32 32 + * const name = signal('Alice'); 33 33 + * console.log(name.value); // 'Alice' 34 34 + * name.value = 'Bob'; // Notifies all subscribers 35 35 + */ 36 36 + export function signal(initialValue) { 37 37 + let value = initialValue; 38 38 + const subscribers = new Set(); 39 39 + 40 40 + return { 41 41 + /** 42 42 + * Get or set the signal value. 43 43 + * Getting tracks the current effect as a dependency. 44 44 + * Setting notifies all subscribers. 45 45 + */ 46 46 + get value() { 47 47 + // Track dependency 48 48 + if (currentEffect) { 49 49 + subscribers.add(currentEffect); 50 50 + } 51 51 + return value; 52 52 + }, 53 53 + 54 54 + set value(newValue) { 55 55 + if (!Object.is(value, newValue)) { 56 56 + value = newValue; 57 57 + // Notify subscribers (copy to avoid mutation during iteration) 58 58 + for (const subscriber of [...subscribers]) { 59 59 + subscriber(); 60 60 + } 61 61 + } 62 62 + }, 63 63 + 64 64 + /** 65 65 + * Get value without tracking (peek at value) 66 66 + * @returns {T} 67 67 + */ 68 68 + peek() { 69 69 + return value; 70 70 + }, 71 71 + 72 72 + /** 73 73 + * Subscribe to changes manually (for non-effect use cases) 74 74 + * @param {Function} callback - Called when value changes 75 75 + * @returns {Function} - Unsubscribe function 76 76 + */ 77 77 + subscribe(callback) { 78 78 + subscribers.add(callback); 79 79 + return () => subscribers.delete(callback); 80 80 + }, 81 81 + 82 82 + /** 83 83 + * Number of active subscribers 84 84 + */ 85 85 + get subscriberCount() { 86 86 + return subscribers.size; 87 87 + } 88 88 + }; 89 89 + } 90 90 + 91 91 + /** 92 92 + * Computed - A derived reactive value 93 93 + * 94 94 + * Automatically tracks dependencies and recomputes when they change. 95 95 + * Lazy evaluation - only computes when .value is accessed. 96 96 + * 97 97 + * @template T 98 98 + * @param {() => T} fn - Computation function 99 99 + * @returns {ComputedSignal<T>} - Read-only signal 100 100 + * 101 101 + * @example 102 102 + * const firstName = signal('John'); 103 103 + * const lastName = signal('Doe'); 104 104 + * const fullName = computed(() => `${firstName.value} ${lastName.value}`); 105 105 + * 106 106 + * console.log(fullName.value); // 'John Doe' 107 107 + * firstName.value = 'Jane'; 108 108 + * console.log(fullName.value); // 'Jane Doe' 109 109 + */ 110 110 + export function computed(fn) { 111 111 + let cachedValue; 112 112 + let dirty = true; 113 113 + const subscribers = new Set(); 114 114 + 115 115 + // Internal effect to track dependencies and mark dirty 116 116 + const recompute = () => { 117 117 + dirty = true; 118 118 + // Notify our subscribers that we changed 119 119 + for (const subscriber of [...subscribers]) { 120 120 + subscriber(); 121 121 + } 122 122 + }; 123 123 + 124 124 + return { 125 125 + get value() { 126 126 + // Track this computed as a dependency 127 127 + if (currentEffect) { 128 128 + subscribers.add(currentEffect); 129 129 + } 130 130 + 131 131 + if (dirty) { 132 132 + // Run computation with dependency tracking 133 133 + const previousEffect = currentEffect; 134 134 + currentEffect = recompute; 135 135 + effectStack.push(recompute); 136 136 + 137 137 + try { 138 138 + cachedValue = fn(); 139 139 + dirty = false; 140 140 + } finally { 141 141 + effectStack.pop(); 142 142 + currentEffect = previousEffect; 143 143 + } 144 144 + } 145 145 + 146 146 + return cachedValue; 147 147 + }, 148 148 + 149 149 + /** 150 150 + * Get value without tracking 151 151 + */ 152 152 + peek() { 153 153 + if (dirty) { 154 154 + // Compute without tracking 155 155 + const previousEffect = currentEffect; 156 156 + currentEffect = null; 157 157 + try { 158 158 + cachedValue = fn(); 159 159 + dirty = false; 160 160 + } finally { 161 161 + currentEffect = previousEffect; 162 162 + } 163 163 + } 164 164 + return cachedValue; 165 165 + }, 166 166 + 167 167 + /** 168 168 + * Subscribe to changes manually 169 169 + */ 170 170 + subscribe(callback) { 171 171 + subscribers.add(callback); 172 172 + return () => subscribers.delete(callback); 173 173 + } 174 174 + }; 175 175 + } 176 176 + 177 177 + /** 178 178 + * Effect - Run side effects when dependencies change 179 179 + * 180 180 + * Automatically tracks signal/computed dependencies accessed during execution. 181 181 + * Re-runs whenever any dependency changes. 182 182 + * 183 183 + * @param {() => void | (() => void)} fn - Effect function. May return cleanup function. 184 184 + * @returns {() => void} - Dispose function to stop the effect 185 185 + * 186 186 + * @example 187 187 + * const count = signal(0); 188 188 + * 189 189 + * const dispose = effect(() => { 190 190 + * console.log('Count is:', count.value); 191 191 + * return () => console.log('Cleanup'); 192 192 + * }); 193 193 + * 194 194 + * count.value = 1; // Logs: "Cleanup" then "Count is: 1" 195 195 + * dispose(); // Stops the effect 196 196 + */ 197 197 + export function effect(fn) { 198 198 + let cleanup = null; 199 199 + let disposed = false; 200 200 + 201 201 + const execute = () => { 202 202 + if (disposed) return; 203 203 + 204 204 + // Run cleanup from previous execution 205 205 + if (cleanup && typeof cleanup === 'function') { 206 206 + cleanup(); 207 207 + cleanup = null; 208 208 + } 209 209 + 210 210 + // Run effect with dependency tracking 211 211 + const previousEffect = currentEffect; 212 212 + currentEffect = execute; 213 213 + effectStack.push(execute); 214 214 + 215 215 + try { 216 216 + cleanup = fn(); 217 217 + } finally { 218 218 + effectStack.pop(); 219 219 + currentEffect = previousEffect; 220 220 + } 221 221 + }; 222 222 + 223 223 + // Initial execution 224 224 + execute(); 225 225 + 226 226 + // Return dispose function 227 227 + return () => { 228 228 + disposed = true; 229 229 + if (cleanup && typeof cleanup === 'function') { 230 230 + cleanup(); 231 231 + } 232 232 + }; 233 233 + } 234 234 + 235 235 + /** 236 236 + * Batch multiple signal updates into a single notification 237 237 + * 238 238 + * @param {() => void} fn - Function containing signal updates 239 239 + * 240 240 + * @example 241 241 + * const a = signal(1); 242 242 + * const b = signal(2); 243 243 + * 244 244 + * batch(() => { 245 245 + * a.value = 10; 246 246 + * b.value = 20; 247 247 + * }); // Effects run once, not twice 248 248 + */ 249 249 + let batchDepth = 0; 250 250 + let batchedEffects = new Set(); 251 251 + 252 252 + export function batch(fn) { 253 253 + batchDepth++; 254 254 + try { 255 255 + fn(); 256 256 + } finally { 257 257 + batchDepth--; 258 258 + if (batchDepth === 0) { 259 259 + const effects = [...batchedEffects]; 260 260 + batchedEffects.clear(); 261 261 + for (const effect of effects) { 262 262 + effect(); 263 263 + } 264 264 + } 265 265 + } 266 266 + } 267 267 + 268 268 + /** 269 269 + * Create a signal from an external data source 270 270 + * 271 271 + * Useful for bridging external state (localStorage, APIs, etc.) with signals. 272 272 + * 273 273 + * @template T 274 274 + * @param {() => T} get - Getter function 275 275 + * @param {(value: T) => void} set - Setter function 276 276 + * @param {(callback: () => void) => () => void} subscribe - Subscribe to external changes 277 277 + * @returns {Signal<T>} 278 278 + * 279 279 + * @example 280 280 + * const storedValue = fromExternal( 281 281 + * () => localStorage.getItem('key'), 282 282 + * (v) => localStorage.setItem('key', v), 283 283 + * (cb) => { window.addEventListener('storage', cb); return () => window.removeEventListener('storage', cb); } 284 284 + * ); 285 285 + */ 286 286 + export function fromExternal(get, set, subscribe) { 287 287 + const s = signal(get()); 288 288 + 289 289 + // Sync from external source 290 290 + const unsubscribe = subscribe(() => { 291 291 + s.value = get(); 292 292 + }); 293 293 + 294 294 + // Return a proxy that syncs back to external 295 295 + return { 296 296 + get value() { 297 297 + return s.value; 298 298 + }, 299 299 + set value(newValue) { 300 300 + set(newValue); 301 301 + s.value = newValue; 302 302 + }, 303 303 + peek: s.peek, 304 304 + subscribe: s.subscribe, 305 305 + dispose: unsubscribe 306 306 + }; 307 307 + } 308 308 + 309 309 + /** 310 310 + * Watch a signal and call handler when it changes 311 311 + * 312 312 + * Similar to effect but more explicit - only watches specified signals. 313 313 + * 314 314 + * @template T 315 315 + * @param {Signal<T> | ComputedSignal<T>} source - Signal to watch 316 316 + * @param {(value: T, oldValue: T) => void} handler - Called on change 317 317 + * @param {Object} [options] 318 318 + * @param {boolean} [options.immediate=false] - Call handler immediately with current value 319 319 + * @returns {() => void} - Stop watching 320 320 + * 321 321 + * @example 322 322 + * const count = signal(0); 323 323 + * const stop = watch(count, (newVal, oldVal) => { 324 324 + * console.log(`Changed from ${oldVal} to ${newVal}`); 325 325 + * }); 326 326 + */ 327 327 + export function watch(source, handler, options = {}) { 328 328 + let oldValue = source.peek(); 329 329 + 330 330 + if (options.immediate) { 331 331 + handler(oldValue, undefined); 332 332 + } 333 333 + 334 334 + return source.subscribe(() => { 335 335 + const newValue = source.peek(); 336 336 + if (!Object.is(newValue, oldValue)) { 337 337 + const prev = oldValue; 338 338 + oldValue = newValue; 339 339 + handler(newValue, prev); 340 340 + } 341 341 + }); 342 342 + } 343 343 + 344 344 + export default { signal, computed, effect, batch, fromExternal, watch };