@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/contexts/snapshotContext.d.ts

@@ -1,19 +1,112 @@
 import { Context, ContextManager } from '../context';
 import { Observable } from '../observable';
-/** @zcontext */
+/**
+ * Context containing snapshot information.
+ * @zcontext
+ *  */
 export declare class SnapshotContext extends Context {
-    /** @zui */
+    /**
+     * Observable holding the current canvas image data URL.
+     * @zui
+     */
     readonly canvasImage: Observable<string, never>;
-    /**@zui */
+    /**
+     * Observable indicating whether the Share API is supported in the current environment.
+     * @zui
+     */
     readonly shareAPISupported: Observable<boolean, never>;
-    /** @zui */
+    /**
+     * Observable determining if the current canvas content can be shared.
+     * @zui
+     */
     readonly canShare: Observable<boolean, never>;
+    /**
+     * Observable containing the canvas image as a File object.
+     */
     readonly canvasFile: Observable<File | null, never>;
+    /**
+     * Observable storing the file name for the snapshot.
+     * Updates the file upon change.
+     */
     readonly fileName: Observable<string, never>;
+    /**
+     * Observable holding the text content to be shared with the snapshot.
+     */
     readonly text: Observable<string, never>;
+    /**
+     * Observable containing the title for the snapshot.
+     */
     readonly title: Observable<string, never>;
+    /**
+     * Observable storing the file type for the snapshot (e.g., 'image/png').
+     * Updates the file upon change.
+     */
     readonly fileType: Observable<string, never>;
+    /**
+     * Observable representing the quality setting of the snapshot image.
+     */
     readonly quality: Observable<number, never>;
+    /**
+     * Creates an instance of SnapshotContext.
+     * @param contextManager - The current ContextManager
+     */
     constructor(contextManager: ContextManager);
+    /**
+     * Converts the canvas image to a file.
+     */
     updateFile: () => Promise<void>;
 }
+/**
+ * Retrieves the current canvas image as a data URL.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the canvas image data URL.
+ */
+export declare function useCanvasImage(ctx: ContextManager): Observable<string, never>;
+/**
+ * Checks if the Share API is supported in the current environment.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable indicating whether the Share API is supported.
+ */
+export declare function useShareAPISupported(ctx: ContextManager): Observable<boolean, never>;
+/**
+ * Determines if the current canvas content can be shared via the Share API.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable indicating whether the canvas can be shared.
+ */
+export declare function useCanShare(ctx: ContextManager): Observable<boolean, never>;
+/**
+ * Retrieves the file representation of the canvas image.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the canvas image as a File object.
+ */
+export declare function useCanvasFile(ctx: ContextManager): Observable<File | null, never>;
+/**
+ * Retrieves the file name for the snapshot to be shared.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the file name.
+ */
+export declare function useFileName(ctx: ContextManager): Observable<string, never>;
+/**
+ * Retrieves the text content to be shared along with the snapshot.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the share text.
+ */
+export declare function useText(ctx: ContextManager): Observable<string, never>;
+/**
+ * Retrieves the title for the snapshot to be shared.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the share title.
+ */
+export declare function useTitle(ctx: ContextManager): Observable<string, never>;
+/**
+ * Retrieves the file type for the snapshot to be shared.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the file type (e.g., 'image/png').
+ */
+export declare function useFileType(ctx: ContextManager): Observable<string, never>;
+/**
+ * Retrieves the quality setting for the snapshot image.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the image quality value.
+ */
+export declare function useQuality(ctx: ContextManager): Observable<number, never>;

package/lib/contexts/snapshotContext.js

@@ -1,21 +1,60 @@
 import { Context } from '../context';
 import { Observable } from '../observable';
-/** @zcontext */
+/**
+ * Context containing snapshot information.
+ * @zcontext
+ *  */
 export class SnapshotContext extends Context {
+    /**
+     * Creates an instance of SnapshotContext.
+     * @param contextManager - The current ContextManager
+     */
     constructor(contextManager) {
         super(contextManager, {});
-        /** @zui */
+        /**
+         * Observable holding the current canvas image data URL.
+         * @zui
+         */
         this.canvasImage = new Observable('');
-        /**@zui */
+        /**
+         * Observable indicating whether the Share API is supported in the current environment.
+         * @zui
+         */
         this.shareAPISupported = new Observable('share' in navigator);
-        /** @zui */
+        /**
+         * Observable determining if the current canvas content can be shared.
+         * @zui
+         */
         this.canShare = new Observable(false);
+        /**
+         * Observable containing the canvas image as a File object.
+         */
         this.canvasFile = new Observable(null);
+        /**
+         * Observable storing the file name for the snapshot.
+         * Updates the file upon change.
+         */
         this.fileName = new Observable('canvas', fileName => this.updateFile());
+        /**
+         * Observable holding the text content to be shared with the snapshot.
+         */
         this.text = new Observable('Check this out!');
+        /**
+         * Observable containing the title for the snapshot.
+         */
         this.title = new Observable('Canvas');
+        /**
+         * Observable storing the file type for the snapshot (e.g., 'image/png').
+         * Updates the file upon change.
+         */
         this.fileType = new Observable('image/png', fileType => this.updateFile());
+        /**
+         * Observable representing the quality setting of the snapshot image.
+         */
         this.quality = new Observable(0.92);
+        /**
+         * Converts the canvas image to a file.
+         */
         this.updateFile = async () => {
             const response = await fetch(this.canvasImage.value);
             const blob = await response.blob();
@@ -31,3 +70,75 @@ export class SnapshotContext extends Context {
         this.canvasImage.addListener(this.updateFile);
     }
 }
+/**
+ * Retrieves the current canvas image as a data URL.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the canvas image data URL.
+ */
+export function useCanvasImage(ctx) {
+    return ctx.get(SnapshotContext).canvasImage;
+}
+/**
+ * Checks if the Share API is supported in the current environment.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable indicating whether the Share API is supported.
+ */
+export function useShareAPISupported(ctx) {
+    return ctx.get(SnapshotContext).shareAPISupported;
+}
+/**
+ * Determines if the current canvas content can be shared via the Share API.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable indicating whether the canvas can be shared.
+ */
+export function useCanShare(ctx) {
+    return ctx.get(SnapshotContext).canShare;
+}
+/**
+ * Retrieves the file representation of the canvas image.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the canvas image as a File object.
+ */
+export function useCanvasFile(ctx) {
+    return ctx.get(SnapshotContext).canvasFile;
+}
+/**
+ * Retrieves the file name for the snapshot to be shared.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the file name.
+ */
+export function useFileName(ctx) {
+    return ctx.get(SnapshotContext).fileName;
+}
+/**
+ * Retrieves the text content to be shared along with the snapshot.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the share text.
+ */
+export function useText(ctx) {
+    return ctx.get(SnapshotContext).text;
+}
+/**
+ * Retrieves the title for the snapshot to be shared.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the share title.
+ */
+export function useTitle(ctx) {
+    return ctx.get(SnapshotContext).title;
+}
+/**
+ * Retrieves the file type for the snapshot to be shared.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the file type (e.g., 'image/png').
+ */
+export function useFileType(ctx) {
+    return ctx.get(SnapshotContext).fileType;
+}
+/**
+ * Retrieves the quality setting for the snapshot image.
+ * @param ctx The ContextManager instance to access the SnapshotContext.
+ * @returns An Observable containing the image quality value.
+ */
+export function useQuality(ctx) {
+    return ctx.get(SnapshotContext).quality;
+}

package/lib/contexts/tagcontext.d.ts

@@ -1,13 +1,67 @@
-import { Component } from "../component";
-import { ContextManager, Context } from "../context";
+import { Component } from '../component';
+import { ContextManager, Context } from '../context';
+import { Event } from '../event';
+/**
+ * Manages and tracks tags associated with components.
+ * @zcontext
+ */
 export declare class TagContext extends Context {
+    /**
+     * A map storing the relationship between components and their associated tags.
+     */
     readonly tagsByComponent: Map<Component<any, import("../component").ConstructorProps>, Set<string>>;
+    /**
+     * A map storing the relationship between local tags and their associated components.
+     */
     readonly componentsByLocalTag: Map<string, Set<Component<any, import("../component").ConstructorProps>>>;
+    /**
+     * An event that's emitted when the set of components that constitute a tag changes.
+     */
+    readonly onTagChange: Event<[string]>;
     private _global;
+    constructor(contextManager: ContextManager);
+    private _globalTagChange;
+    /**
+     * Registers a component with specified tags.
+     * Updates both local and global tag maps accordingly.
+     * @param component The component to register.
+     * @param tags The tags to associate with the component.
+     */
     registerComponent(component: Component, tags: string[]): void;
+    /**
+     * Registers a component with specified tags.
+     * Updates both local and global tag maps accordingly.
+     * @param component The component to register.
+     * @param tags The tags to associate with the component.
+     */
     unregisterComponent(component: Component): void;
+    /**
+     * Retrieves components associated with a specific tag.
+     * Searches both local and global tag maps.
+     * @param tag The tag to search for.
+     * @returns A set of components associated with the specified tag.
+     */
     getComponentsByTag(tag: string): Set<Component>;
+    /**
+     * Retrieves components associated with a list of tags.
+     * Consolidates results from both local and global tag maps.
+     * @param tags An array of tags to search for.
+     * @returns A set of components associated with the specified tags.
+     */
     getComponentsByTags(tags: string[]): Set<Component>;
+    dispose(): never;
 }
+/**
+ * Retrieves components associated with a specific tag.
+ * @param mgr The ContextManager instance to access the TagContext.
+ * @param tag The tag to search for.
+ * @returns A set of components associated with the specified tag.
+ */
 export declare function getComponentsByTag(mgr: ContextManager, tag: string): Set<Component<any, import("../component").ConstructorProps>>;
+/**
+ * Retrieves components associated with a list of tags.
+ * @param mgr The ContextManager instance to access the TagContext.
+ * @param tags An array of tags to search for.
+ * @returns A set of components associated with the specified tags.
+ */
 export declare function getComponentsByTags(mgr: ContextManager, tags: string[]): Set<Component<any, import("../component").ConstructorProps>>;

package/lib/contexts/tagcontext.js

@@ -1,12 +1,37 @@
-import { Context } from "../context";
-import { GlobalTagContext } from "./globaltagcontext";
+import { Context } from '../context';
+import { Event } from '../event';
+import { GlobalTagContext } from './globaltagcontext';
+/**
+ * Manages and tracks tags associated with components.
+ * @zcontext
+ */
 export class TagContext extends Context {
-    constructor() {
-        super(...arguments);
+    constructor(contextManager) {
+        super(contextManager, {});
+        /**
+         * A map storing the relationship between components and their associated tags.
+         */
         this.tagsByComponent = new Map();
+        /**
+         * A map storing the relationship between local tags and their associated components.
+         */
         this.componentsByLocalTag = new Map();
+        /**
+         * An event that's emitted when the set of components that constitute a tag changes.
+         */
+        this.onTagChange = new Event();
         this._global = this.contextManager.get(GlobalTagContext);
+        this._globalTagChange = (tag) => {
+            this.onTagChange.emit(tag);
+        };
+        this._global.onTagChange.addListener(this._globalTagChange);
     }
+    /**
+     * Registers a component with specified tags.
+     * Updates both local and global tag maps accordingly.
+     * @param component The component to register.
+     * @param tags The tags to associate with the component.
+     */
     registerComponent(component, tags) {
         this.unregisterComponent(component);
         for (const tag of tags) {
@@ -16,10 +41,21 @@ export class TagContext extends Context {
             map.set(tag, set);
         }
         this.tagsByComponent.set(component, new Set(tags));
+        for (const tag of tags) {
+            if (tag.startsWith('local:'))
+                this.onTagChange.emit(tag);
+            else
+                this._global.onTagChange.emit(tag);
+        }
     }
-    ;
+    /**
+     * Registers a component with specified tags.
+     * Updates both local and global tag maps accordingly.
+     * @param component The component to register.
+     * @param tags The tags to associate with the component.
+     */
     unregisterComponent(component) {
-        let tags = this.tagsByComponent.get(component);
+        const tags = this.tagsByComponent.get(component);
         if (!tags)
             return;
         for (const tag of tags.values()) {
@@ -30,10 +66,28 @@ export class TagContext extends Context {
             entry.delete(component);
         }
         this.tagsByComponent.delete(component);
+        for (const tag of tags) {
+            if (tag.startsWith('local:'))
+                this.onTagChange.emit(tag);
+            else
+                this._global.onTagChange.emit(tag);
+        }
     }
+    /**
+     * Retrieves components associated with a specific tag.
+     * Searches both local and global tag maps.
+     * @param tag The tag to search for.
+     * @returns A set of components associated with the specified tag.
+     */
     getComponentsByTag(tag) {
-        return ((!tag.startsWith('local:') ? this._global.componentsByGlobalTag : this.componentsByLocalTag).get(tag)) ?? new Set();
+        return (!tag.startsWith('local:') ? this._global.componentsByGlobalTag : this.componentsByLocalTag).get(tag) ?? new Set();
     }
+    /**
+     * Retrieves components associated with a list of tags.
+     * Consolidates results from both local and global tag maps.
+     * @param tags An array of tags to search for.
+     * @returns A set of components associated with the specified tags.
+     */
     getComponentsByTags(tags) {
         if (tags.length === 0)
             return new Set();
@@ -49,10 +103,26 @@ export class TagContext extends Context {
         }
         return ret;
     }
+    dispose() {
+        this._global.onTagChange.removeListener(this._globalTagChange);
+        return super.dispose();
+    }
 }
+/**
+ * Retrieves components associated with a specific tag.
+ * @param mgr The ContextManager instance to access the TagContext.
+ * @param tag The tag to search for.
+ * @returns A set of components associated with the specified tag.
+ */
 export function getComponentsByTag(mgr, tag) {
     return mgr.get(TagContext).getComponentsByTag(tag);
 }
+/**
+ * Retrieves components associated with a list of tags.
+ * @param mgr The ContextManager instance to access the TagContext.
+ * @param tags An array of tags to search for.
+ * @returns A set of components associated with the specified tags.
+ */
 export function getComponentsByTags(mgr, tags) {
     return mgr.get(TagContext).getComponentsByTags(tags);
 }

package/lib/contexts/textalertcontext.d.ts

@@ -1,15 +1,48 @@
 import { ContextManager, Context } from '../context';
-/** @zcontext */
+/**
+ * Manages the display of text alerts.
+ * @zcontext
+ */
 export declare class TextAlertContext extends Context {
     private _container;
+    /**
+     * Creates an instance of TextAlertContext.
+     * @param contextManager - The current ContextManager
+     */
     constructor(contextManager: ContextManager);
-    /** @zprop */
+    /**
+     * Displays a text alert with specified options.
+     * @zprop
+     * @param txt The text content for the alert.
+     * @param options Optional configuration for the text alert appearance and behavior.
+     */
     showTextAlert(txt: string, options?: TextAlertOptions): void;
 }
+/**
+ * Configuration options for displaying a text alert.
+ */
 export interface TextAlertOptions {
+    /**
+     * Custom class names to apply to the text alert.
+     */
     classNames?: string[];
+    /**
+     * Duration in milliseconds before the text alert automatically disappears. Defaults to 3000 (3 seconds).
+     */
     timeout?: number;
+    /**
+     * Background color of the text alert.
+     */
     backgroundColor?: string;
+    /**
+     * Text color of the text alert.
+     */
     textColor?: string;
 }
+/**
+ * Triggers the display of a text alert.
+ * @param mgr The ContextManager instance to access the TextAlertContext.
+ * @param txt The text content for the alert.
+ * @param options Optional configuration for the text alert appearance and behavior.
+ */
 export declare function showTextAlert(mgr: ContextManager, txt: string, options?: TextAlertOptions): void;

package/lib/contexts/textalertcontext.js

@@ -1,7 +1,14 @@
 import { Context } from '../context';
 import { useOverlay } from './canvascontext';
-/** @zcontext */
+/**
+ * Manages the display of text alerts.
+ * @zcontext
+ */
 export class TextAlertContext extends Context {
+    /**
+     * Creates an instance of TextAlertContext.
+     * @param contextManager - The current ContextManager
+     */
     constructor(contextManager) {
         super(contextManager, {});
         this._container = document.createElement('div');
@@ -10,7 +17,12 @@ export class TextAlertContext extends Context {
             val.appendChild(this._container);
         });
     }
-    /** @zprop */
+    /**
+     * Displays a text alert with specified options.
+     * @zprop
+     * @param txt The text content for the alert.
+     * @param options Optional configuration for the text alert appearance and behavior.
+     */
     showTextAlert(txt, options) {
         const entry = document.createElement('div');
         entry.classList.add('zcomponent-textalert');
@@ -33,6 +45,12 @@ export class TextAlertContext extends Context {
         }, timeout);
     }
 }
+/**
+ * Triggers the display of a text alert.
+ * @param mgr The ContextManager instance to access the TextAlertContext.
+ * @param txt The text content for the alert.
+ * @param options Optional configuration for the text alert appearance and behavior.
+ */
 export function showTextAlert(mgr, txt, options) {
     return mgr.get(TextAlertContext).showTextAlert(txt, options);
 }

package/lib/contexts/usereventcontext.d.ts

@@ -1,12 +1,41 @@
 import { ContextManager, Context } from '../context';
 import { Event as EventClass } from '../event';
 import { Observable } from '../observable';
+/**
+ * Manages and tracks user events within the application context.
+ */
 export declare class UserEventContext extends Context {
+    /**
+     * Event triggered when a user event occurs.
+     */
     readonly onUserEvent: EventClass<[Event]>;
     private _resolveNextUserEvent;
+    /**
+     * An observable that emits the next user event as a promise.
+     * It gets resolved with the event object when a user event occurs.
+     */
     readonly nextUserEvent: Observable<Promise<Event>, never>;
+    /**
+     * Registers and emits a user event.
+     * @param evt The user event to register.
+     */
     registerUserEvent(evt: Event): void;
 }
+/**
+ * Provides access to the event that gets triggered on a user event.
+ * @param mgr The ContextManager instance to access the UserEventContext.
+ * @returns The EventClass instance representing user events.
+ */
 export declare function useOnUserEvent(mgr: ContextManager): EventClass<[Event]>;
+/**
+ * Retrieves the next user event as a promise.
+ * @param mgr The ContextManager instance to access the UserEventContext.
+ * @returns A promise that resolves with the next user event.
+ */
 export declare function nextUserEvent(mgr: ContextManager): Promise<Event>;
+/**
+ * Registers a user event in the UserEventContext.
+ * @param mgr The ContextManager instance to access the UserEventContext.
+ * @param evt The user event to register.
+ */
 export declare function registerUserEvent(mgr: ContextManager, evt: Event): void;

package/lib/contexts/usereventcontext.js

@@ -1,12 +1,26 @@
 import { Context } from '../context';
 import { Event as EventClass } from '../event';
 import { Observable } from '../observable';
+/**
+ * Manages and tracks user events within the application context.
+ */
 export class UserEventContext extends Context {
     constructor() {
         super(...arguments);
+        /**
+         * Event triggered when a user event occurs.
+         */
         this.onUserEvent = new EventClass();
-        this.nextUserEvent = new Observable(new Promise(resolve => this._resolveNextUserEvent = resolve), undefined, false);
+        /**
+         * An observable that emits the next user event as a promise.
+         * It gets resolved with the event object when a user event occurs.
+         */
+        this.nextUserEvent = new Observable(new Promise(resolve => (this._resolveNextUserEvent = resolve)), undefined, false);
     }
+    /**
+     * Registers and emits a user event.
+     * @param evt The user event to register.
+     */
     registerUserEvent(evt) {
         const currentResolve = this._resolveNextUserEvent;
         this.nextUserEvent.value = new Promise(resolve => {
@@ -16,12 +30,27 @@ export class UserEventContext extends Context {
         this.onUserEvent.emit(evt);
     }
 }
+/**
+ * Provides access to the event that gets triggered on a user event.
+ * @param mgr The ContextManager instance to access the UserEventContext.
+ * @returns The EventClass instance representing user events.
+ */
 export function useOnUserEvent(mgr) {
     return mgr.get(UserEventContext).onUserEvent;
 }
+/**
+ * Retrieves the next user event as a promise.
+ * @param mgr The ContextManager instance to access the UserEventContext.
+ * @returns A promise that resolves with the next user event.
+ */
 export function nextUserEvent(mgr) {
     return mgr.get(UserEventContext).nextUserEvent.value;
 }
+/**
+ * Registers a user event in the UserEventContext.
+ * @param mgr The ContextManager instance to access the UserEventContext.
+ * @param evt The user event to register.
+ */
 export function registerUserEvent(mgr, evt) {
     return mgr.get(UserEventContext).registerUserEvent(evt);
 }