@mintjamsinc/ichigojs 0.1.66 → 0.1.68

package/dist/types/ichigo/VApplicationOptions.d.ts

@@ -39,6 +39,13 @@ export interface VApplicationOptions {
      * and the value is either a callback function or an options object with handler, deep, and immediate properties.
      */
     watch?: WatcherDictionary;
+    /**
+     * Optional list of event names this application/component is expected to emit via `$emit`.
+     * When declared, emitting an event whose name is not in this list logs a development warning.
+     * When omitted, `$emit` accepts any event name without warning. This is documentation/validation
+     * only and never blocks dispatch.
+     */
+    emits?: string[];
     /**
      * The log level for the application.
      * This property determines the verbosity of logging output.

package/dist/types/ichigo/VBindings.d.ts

@@ -56,6 +56,13 @@ export declare class VBindings {
      * @param key The binding name.
      */
     remove(key: string): void;
+    /**
+     * Releases all external proxy subscriptions held by these bindings.
+     * Should be called when the owning application is unmounted so the parent
+     * application's reactive objects do not keep references to listener closures
+     * (and through them, this bindings instance) alive.
+     */
+    destroy(): void;
     /**
      * Sets a binding value without triggering onChange callback.
      * This is useful for internal updates that shouldn't trigger reactivity.

package/dist/types/ichigo/VEmitOptions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Options for `$emit`, controlling how the underlying CustomEvent is dispatched.
+ */
+export interface VEmitOptions {
+    /**
+     * Whether the event bubbles up through the DOM. Default is true.
+     * Bubbling lets a parent component listen with `v-on` / `@` on the component tag,
+     * because the application root is dispatched from inside the host custom element.
+     */
+    bubbles?: boolean;
+    /**
+     * Whether the event is cancelable (i.e. `preventDefault()` has an effect).
+     * Default is true. `$emit` returns false when a listener called `preventDefault()`.
+     */
+    cancelable?: boolean;
+    /**
+     * Whether the event propagates across shadow DOM boundaries. Default is false.
+     * ichigo.js components use Light DOM, so this is rarely needed.
+     */
+    composed?: boolean;
+    /**
+     * The target the event is dispatched on. Defaults to the application root element.
+     * Set this to `document` or `window` to use a global event bus, or to a specific
+     * element for element-scoped dispatch.
+     */
+    target?: EventTarget;
+}

package/dist/types/ichigo/directives/VOnDirective.d.ts

@@ -18,6 +18,15 @@ import { VDOMUpdater } from "../VDOMUpdater";
  * Mouse button modifiers (MouseEvent): `.left`, `.middle`, `.right`.
  * System modifiers (KeyboardEvent and MouseEvent): `.shift`, `.ctrl`, `.alt`, `.meta`, plus `.exact` to require that no other system modifiers are held.
  *
+ * Listen target and filter modifiers (two orthogonal axes):
+ *   - Listen target (where the listener is attached): `.window`, `.document`. When omitted the listener
+ *     is attached to the bound element. This is useful for global / cross-component events, e.g.
+ *     `@webtop-message.document="onMessage"`, and the listener is removed automatically on unmount.
+ *   - Filter (whether the handler runs): `.self` fires only when `event.target` is the bound element;
+ *     `.outside` fires only when `event.target` is outside the bound element (e.g. click-outside to
+ *     close a popup). `.outside` implies listening on `document` (capture phase) even without `.document`,
+ *     and `.self` / `.outside` are mutually exclusive.
+ *
  * Additionally, this directive supports lifecycle hooks:
  *     @mount="onMount"       - Called before the VNode is mounted to the DOM element
  *     @mounted="onMounted"   - Called after the VNode is mounted to the DOM element

package/dist/types/ichigo/util/ReactiveProxy.d.ts

@@ -1,3 +1,17 @@
+/**
+ * A listener notified when something changes inside a reactive subtree.
+ * Receives the full source path of the changed property (e.g. "items[0].name").
+ */
+type ReactiveListener = (changedPath?: string) => void;
+/**
+ * A dispatcher owns the set of listeners attached to a given proxy subtree.
+ * The same dispatcher instance is shared by every nested proxy reached
+ * through a single outermost create() call, so changes at any depth fan out
+ * to every subscriber once.
+ */
+type ReactiveDispatcher = {
+    listeners: Set<ReactiveListener>;
+};
 /**
  * Utility class for creating reactive proxies that automatically track changes.
  */
@@ -22,6 +36,13 @@ export declare class ReactiveProxy {
      * This allows retrieving the source path of an object for computed property mapping.
      */
     private static proxyPaths;
+    /**
+     * Dispatchers per (target, path). Every target reached while walking a proxy
+     * subtree registers an entry pointing at the same dispatcher as the outermost
+     * proxy of that subtree, so callers can look up the dispatcher from any
+     * intermediate proxy when subscribing.
+     */
+    private static dispatchers;
     /**
      * A Map to store path aliases.
      * Key: alias path (e.g., "editingNestedStep.steps")
@@ -36,9 +57,33 @@ export declare class ReactiveProxy {
      * @param target The object to make reactive.
      * @param onChange Callback function to call when the object changes. Receives the full path of the changed property.
      * @param path The current path in the object tree (used internally for nested objects).
+     * @param inheritedDispatcher Internal: the dispatcher inherited from an enclosing create() call when wrapping a nested target. External callers must omit this.
      * @returns A reactive proxy of the target object.
      */
-    static create<T extends object>(target: T, onChange: (changedPath?: string) => void, path?: string): T;
+    static create<T extends object>(target: T, onChange?: (changedPath?: string) => void, path?: string, inheritedDispatcher?: ReactiveDispatcher): T;
+    /**
+     * Looks up the dispatcher associated with (target, path), or installs a new one.
+     * When called for a nested target during proxy walking, the enclosing dispatcher
+     * is reused so a single subtree fans out changes through one notification path.
+     */
+    private static resolveDispatcher;
+    /**
+     * Invokes every listener attached to the dispatcher.
+     * Iterates a snapshot of the listener set so unsubscribing during dispatch is safe.
+     */
+    private static dispatch;
+    /**
+     * Subscribes a listener to changes inside the subtree of an existing reactive proxy.
+     *
+     * The listener is scoped by the proxy's source path: only changes at or below that
+     * path are delivered, which lets a child component receive notifications when the
+     * nested contents of a prop change even though the prop reference itself is unchanged.
+     *
+     * @param proxyOrTarget A proxy returned from create(), or the underlying target object.
+     * @param listener Called with the full source path of every relevant change.
+     * @returns A function that removes the subscription.
+     */
+    static subscribe(proxyOrTarget: object, listener: ReactiveListener): () => void;
     /**
      * Checks if the given object is a reactive proxy.
      *
@@ -118,3 +163,4 @@ export declare class ReactiveProxy {
      */
     static doesChangeMatchIdentifier(changePath: string, identifier: string): boolean;
 }
+export {};

package/dist/types/index.d.ts

@@ -6,3 +6,4 @@ export { ExpressionUtils } from './ichigo/util/ExpressionUtils';
 export { defineComponent } from './ichigo/components/defineComponent';
 export type { IchigoComponentOptions } from './ichigo/components/IchigoComponentOptions';
 export { IchigoElement } from './ichigo/components/IchigoElement';
+export type { VEmitOptions } from './ichigo/VEmitOptions';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintjamsinc/ichigojs",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "description": "ichigo.js - Simple and intuitive reactive framework. Lightweight, fast, and user-friendly virtual DOM library",
   "main": "./dist/ichigo.cjs",
   "module": "./dist/ichigo.esm.js",