@portel/photon-core 2.4.0 → 2.5.0

package/src/collections/ReactiveArray.ts

@@ -0,0 +1,179 @@
+/**
+ * ReactiveArray - A managed array that auto-emits events on mutations
+ *
+ * When used as a class property, automatically emits events when items are
+ * added, removed, or updated.
+ *
+ * @example
+ * ```typescript
+ * import { ReactiveArray } from '@portel/photon-core';
+ *
+ * export default class TodoList {
+ *   items = ReactiveArray.create<Task>('items', (event, data) => this.emit(event, data));
+ *
+ *   add(text: string) {
+ *     this.items.push({ id: crypto.randomUUID(), text });
+ *     // Auto-emits 'items:added' with the new item
+ *   }
+ * }
+ * ```
+ *
+ * Event naming convention (inspired by Firebase):
+ * - `{prop}:added` - Item pushed/inserted
+ * - `{prop}:removed` - Item popped/spliced out
+ * - `{prop}:updated` - Item at index changed
+ * - `{prop}:changed` - Full array replaced
+ */
+
+export type Emitter = (event: string, data: unknown) => void;
+
+export class ReactiveArray<T> extends Array<T> {
+  private _propertyName: string = '';
+  private _emitter: Emitter = () => {};
+
+  /**
+   * Create a new ReactiveArray bound to a property name and emitter function.
+   * The emitter is called with event names like 'items:added', 'items:removed', etc.
+   */
+  static create<T>(
+    propertyName: string,
+    emitter: Emitter,
+    initialItems?: T[]
+  ): ReactiveArray<T> {
+    const arr = new ReactiveArray<T>();
+    arr._propertyName = propertyName;
+    arr._emitter = emitter;
+    if (initialItems) {
+      // Use super.push to avoid triggering events during init
+      globalThis.Array.prototype.push.apply(arr, initialItems);
+    }
+    return arr;
+  }
+
+  /**
+   * Add one or more elements to the end of the array.
+   * Emits `{prop}:added` for each item.
+   */
+  push(...items: T[]): number {
+    const result = super.push(...items);
+    items.forEach((item) => this._emitter(`${this._propertyName}:added`, item));
+    return result;
+  }
+
+  /**
+   * Remove the last element from the array.
+   * Emits `{prop}:removed` with the removed item.
+   */
+  pop(): T | undefined {
+    const item = super.pop();
+    if (item !== undefined) {
+      this._emitter(`${this._propertyName}:removed`, item);
+    }
+    return item;
+  }
+
+  /**
+   * Remove the first element from the array.
+   * Emits `{prop}:removed` with the removed item.
+   */
+  shift(): T | undefined {
+    const item = super.shift();
+    if (item !== undefined) {
+      this._emitter(`${this._propertyName}:removed`, item);
+    }
+    return item;
+  }
+
+  /**
+   * Add one or more elements to the beginning of the array.
+   * Emits `{prop}:added` for each item.
+   */
+  unshift(...items: T[]): number {
+    const result = super.unshift(...items);
+    items.forEach((item) => this._emitter(`${this._propertyName}:added`, item));
+    return result;
+  }
+
+  /**
+   * Remove/replace elements from the array.
+   * Emits `{prop}:removed` for deleted items and `{prop}:added` for inserted items.
+   */
+  splice(start: number, deleteCount?: number, ...items: T[]): T[] {
+    const removed = super.splice(start, deleteCount ?? 0, ...items);
+    removed.forEach((item) =>
+      this._emitter(`${this._propertyName}:removed`, item)
+    );
+    items.forEach((item) => this._emitter(`${this._propertyName}:added`, item));
+    return removed;
+  }
+
+  /**
+   * Set an element at a specific index.
+   * Emits `{prop}:updated` with `{ index, value, previous }`.
+   */
+  set(index: number, value: T): void {
+    const previous = this[index];
+    this[index] = value;
+    this._emitter(`${this._propertyName}:updated`, { index, value, previous });
+  }
+
+  /**
+   * Replace all items in the array.
+   * Emits `{prop}:changed` with the full new array.
+   */
+  replaceAll(items: T[]): void {
+    // Clear and replace
+    this.length = 0;
+    globalThis.Array.prototype.push.apply(this, items);
+    this._emitter(`${this._propertyName}:changed`, [...items]);
+  }
+
+  /**
+   * Clear all items from the array.
+   * Emits `{prop}:changed` with an empty array.
+   */
+  clear(): void {
+    this.length = 0;
+    this._emitter(`${this._propertyName}:changed`, []);
+  }
+
+  /**
+   * Sort the array in place.
+   * Emits `{prop}:changed` with the sorted array.
+   */
+  sort(compareFn?: (a: T, b: T) => number): this {
+    super.sort(compareFn);
+    this._emitter(`${this._propertyName}:changed`, [...this]);
+    return this;
+  }
+
+  /**
+   * Reverse the array in place.
+   * Emits `{prop}:changed` with the reversed array.
+   */
+  reverse(): this {
+    super.reverse();
+    this._emitter(`${this._propertyName}:changed`, [...this]);
+    return this;
+  }
+
+  /**
+   * Fill the array with a value.
+   * Emits `{prop}:changed` with the filled array.
+   */
+  fill(value: T, start?: number, end?: number): this {
+    super.fill(value, start, end);
+    this._emitter(`${this._propertyName}:changed`, [...this]);
+    return this;
+  }
+
+  /**
+   * Copy items within the array.
+   * Emits `{prop}:changed` with the modified array.
+   */
+  copyWithin(target: number, start: number, end?: number): this {
+    super.copyWithin(target, start, end);
+    this._emitter(`${this._propertyName}:changed`, [...this]);
+    return this;
+  }
+}

package/src/collections/ReactiveMap.ts

@@ -0,0 +1,81 @@
+/**
+ * ReactiveMap - A managed Map that auto-emits events on mutations
+ *
+ * When used as a class property, automatically emits events when entries are
+ * set, deleted, or the map is cleared.
+ *
+ * @example
+ * ```typescript
+ * import { ReactiveMap } from '@portel/photon-core';
+ *
+ * export default class Cache {
+ *   data = ReactiveMap.create<string, any>('data', (event, data) => this.emit(event, data));
+ *
+ *   set(key: string, value: any) {
+ *     this.data.set(key, value);
+ *     // Auto-emits 'data:set' with { key, value }
+ *   }
+ * }
+ * ```
+ *
+ * Event naming convention:
+ * - `{prop}:set` - Entry set (new or updated)
+ * - `{prop}:deleted` - Entry deleted
+ * - `{prop}:cleared` - All entries cleared
+ */
+
+import { Emitter } from './ReactiveArray.js';
+
+export class ReactiveMap<K, V> extends Map<K, V> {
+  private _propertyName: string = '';
+  private _emitter: Emitter = () => {};
+
+  /**
+   * Create a new ReactiveMap bound to a property name and emitter function.
+   */
+  static create<K, V>(
+    propertyName: string,
+    emitter: Emitter,
+    initialEntries?: Iterable<[K, V]>
+  ): ReactiveMap<K, V> {
+    const map = new ReactiveMap<K, V>(initialEntries);
+    map._propertyName = propertyName;
+    map._emitter = emitter;
+    return map;
+  }
+
+  /**
+   * Set a value for a key.
+   * Emits `{prop}:set` with `{ key, value, isNew }`.
+   */
+  set(key: K, value: V): this {
+    const isNew = !super.has(key);
+    const previous = super.get(key);
+    super.set(key, value);
+    this._emitter(`${this._propertyName}:set`, { key, value, isNew, previous });
+    return this;
+  }
+
+  /**
+   * Delete an entry by key.
+   * Emits `{prop}:deleted` with `{ key, value }` if the key existed.
+   */
+  delete(key: K): boolean {
+    const value = super.get(key);
+    const existed = super.delete(key);
+    if (existed) {
+      this._emitter(`${this._propertyName}:deleted`, { key, value });
+    }
+    return existed;
+  }
+
+  /**
+   * Clear all entries from the map.
+   * Emits `{prop}:cleared` with the count of removed entries.
+   */
+  clear(): void {
+    const count = super.size;
+    super.clear();
+    this._emitter(`${this._propertyName}:cleared`, { count });
+  }
+}

package/src/collections/ReactiveSet.ts

@@ -0,0 +1,81 @@
+/**
+ * ReactiveSet - A managed Set that auto-emits events on mutations
+ *
+ * When used as a class property, automatically emits events when values are
+ * added, deleted, or the set is cleared.
+ *
+ * @example
+ * ```typescript
+ * import { ReactiveSet } from '@portel/photon-core';
+ *
+ * export default class Tags {
+ *   tags = ReactiveSet.create<string>('tags', (event, data) => this.emit(event, data));
+ *
+ *   addTag(tag: string) {
+ *     this.tags.add(tag);
+ *     // Auto-emits 'tags:added' with the tag
+ *   }
+ * }
+ * ```
+ *
+ * Event naming convention:
+ * - `{prop}:added` - Value added (if not already present)
+ * - `{prop}:deleted` - Value deleted
+ * - `{prop}:cleared` - All values cleared
+ */
+
+import { Emitter } from './ReactiveArray.js';
+
+export class ReactiveSet<T> extends Set<T> {
+  private _propertyName: string = '';
+  private _emitter: Emitter = () => {};
+
+  /**
+   * Create a new ReactiveSet bound to a property name and emitter function.
+   */
+  static create<T>(
+    propertyName: string,
+    emitter: Emitter,
+    initialValues?: Iterable<T>
+  ): ReactiveSet<T> {
+    const set = new ReactiveSet<T>(initialValues);
+    set._propertyName = propertyName;
+    set._emitter = emitter;
+    return set;
+  }
+
+  /**
+   * Add a value to the set.
+   * Emits `{prop}:added` with the value if it wasn't already present.
+   */
+  add(value: T): this {
+    const isNew = !super.has(value);
+    super.add(value);
+    if (isNew) {
+      this._emitter(`${this._propertyName}:added`, value);
+    }
+    return this;
+  }
+
+  /**
+   * Delete a value from the set.
+   * Emits `{prop}:deleted` with the value if it existed.
+   */
+  delete(value: T): boolean {
+    const existed = super.delete(value);
+    if (existed) {
+      this._emitter(`${this._propertyName}:deleted`, value);
+    }
+    return existed;
+  }
+
+  /**
+   * Clear all values from the set.
+   * Emits `{prop}:cleared` with the count of removed values.
+   */
+  clear(): void {
+    const count = super.size;
+    super.clear();
+    this._emitter(`${this._propertyName}:cleared`, { count });
+  }
+}

package/src/collections/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Managed Collections - Auto-emit events on mutations
+ *
+ * These collections extend the native JavaScript collection types and automatically
+ * emit events when their contents change. This enables seamless real-time sync
+ * between server and client.
+ *
+ * @example
+ * ```typescript
+ * import { ReactiveArray } from '@portel/photon-core';
+ *
+ * export default class TodoList {
+ *   items = ReactiveArray.create<Task>('items', (event, data) => this.emit(event, data));
+ *
+ *   add(text: string) {
+ *     this.items.push({ id: crypto.randomUUID(), text });
+ *     // Auto-emits 'items:added' - UI updates automatically!
+ *   }
+ * }
+ * ```
+ *
+ * On the client:
+ * ```javascript
+ * todoList.onItemsAdded((item) => {
+ *   // Auto UI handles this - item appears with animation
+ * });
+ * ```
+ *
+ * Event naming convention (inspired by Firebase):
+ * | Operation           | Event Name          | Data                    |
+ * |---------------------|---------------------|-------------------------|
+ * | Array.push(item)    | `{prop}:added`      | The item                |
+ * | Array.splice(i, 1)  | `{prop}:removed`    | The removed item        |
+ * | Array.set(i, x)     | `{prop}:updated`    | { index, value, prev }  |
+ * | Array.replaceAll()  | `{prop}:changed`    | All items               |
+ * | Map.set(k, v)       | `{prop}:set`        | { key, value, isNew }   |
+ * | Map.delete(k)       | `{prop}:deleted`    | { key, value }          |
+ * | Set.add(v)          | `{prop}:added`      | The value               |
+ * | Set.delete(v)       | `{prop}:deleted`    | The value               |
+ */
+
+export { ReactiveArray, type Emitter } from './ReactiveArray.js';
+export { ReactiveMap } from './ReactiveMap.js';
+export { ReactiveSet } from './ReactiveSet.js';

package/src/index.ts

@@ -440,3 +440,78 @@ export {
   discoverAssets,
   autoDiscoverAssets,
 } from './asset-discovery.js';
+
+// ===== MANAGED COLLECTIONS =====
+// Auto-emit events on mutations for seamless real-time sync
+export {
+  ReactiveArray,
+  ReactiveMap,
+  ReactiveSet,
+  type Emitter,
+} from './collections/index.js';
+
+// ===== PURPOSE-DRIVEN UI TYPES =====
+// Polymorphic return types that auto-render with appropriate UI
+export {
+  // Base
+  PhotonUIType,
+  isPhotonUIType,
+
+  // Field System (React Admin-style)
+  Field,
+  type FieldDefinition,
+  type FieldType,
+  type FieldAlignment,
+  type BaseFieldOptions,
+  type TextFieldOptions,
+  type NumberFieldOptions,
+  type CurrencyFieldOptions,
+  type DateFieldOptions,
+  type DateFormat,
+  type ImageFieldOptions,
+  type BadgeFieldOptions,
+  type RatingFieldOptions,
+  type PriceFieldOptions,
+  type StockFieldOptions,
+  type ActionItem,
+  type ActionsFieldOptions,
+  type RenderFunction,
+  getFieldValue,
+  formatFieldLabel,
+  interpolateTemplate,
+  renderFieldToText,
+  renderFieldToStructured,
+  type RenderedField,
+
+  // Data Display
+  Table,
+  type TableColumn,
+  type TableOptions,
+  type ColumnType,
+  Cards,
+  type CardFieldMapping,
+  type CardsOptions,
+
+  // Visualization
+  Chart,
+  type ChartType,
+  type ChartSeries,
+  type ChartDataPoint,
+  type ChartOptions,
+  Stats,
+  type StatItem,
+  type StatFormat,
+  type StatsOptions,
+  Progress,
+  type ProgressBar,
+  type ProgressStep,
+  type ProgressStyle,
+  type StepStatus,
+  type ProgressOptions,
+
+  // Interactive
+  Form,
+  type FormField,
+  type FieldType as FormFieldType,
+  type FormOptions,
+} from './ui-types/index.js';

package/src/types.ts

@@ -373,6 +373,8 @@ export interface PhotonMCPClassExtended extends PhotonMCPClass {
   statics: StaticInfo[];
   /** Assets from the Photon's asset folder (UI, prompts, resources) */
   assets?: PhotonAssets;
+  /** Names of injected @photon dependencies (for client-side event routing) */
+  injectedPhotons?: string[];
 }
 
 // ══════════════════════════════════════════════════════════════════════════════