@zcomponent/core 0.0.25 → 0.0.27

package/lib/context.d.ts

@@ -38,6 +38,7 @@ export declare class ContextManager {
     fork<T extends new (contextManager: ContextManager, props: {}) => any>(ctx: ConstructorWithOnlyOptional<T>): [ContextManager, InstanceType<T>];
     fork<T extends new (contextManager: ContextManager, props: {}) => any>(ctx: T, props: ConstructorParameters<T>[1]): [ContextManager, InstanceType<T>];
     forkMultiple<T extends ConstructorWithProps[]>(...ctx: T): [ContextManager, InstancesOfConstructorsWithProps<T>];
+    emptyFork(): ContextManager;
     delete(ctx: ContextConstructor): void;
     private _keyForContext;
 }

package/lib/context.js

@@ -51,7 +51,7 @@ export class ContextManager {
         ret._byKey = Object.create(this._byKey);
         const key = this._keyForContext(ctx);
         const instance = new ctx(this, props ?? {});
-        this._byKey[key] = instance;
+        ret._byKey[key] = instance;
         return [ret, instance];
     }
     forkMultiple(...ctx) {
@@ -67,6 +67,11 @@ export class ContextManager {
         }
         return [ret, instances];
     }
+    emptyFork() {
+        const ret = new ContextManager();
+        ret._byKey = Object.create(this._byKey);
+        return ret;
+    }
     delete(ctx) {
         const key = this._keyForContext(ctx);
         const existing = this._byKey[key];

package/lib/contexts/loadcontext.d.ts

@@ -1,6 +1,32 @@
 import { ContextManager, Context } from '../context';
 import { Observable } from '../observable';
-/** @zcontext */
+/**
+ * LoadContext exposes to components and behaviors key moments during the initialization of the experience,
+ * and allows them to register long-running processes that should take place on any loading screen.
+ *
+ * There are several related, yet distinct, moments during initializatin that may be useful. In each case a `Promise`
+ * and an `Observable<boolean>` are exposed for use in components and behaviors.
+ *
+ * - `constructed` occurs when the root component's constructor (and thus any recursive children) has finished.
+ *   This often takes place very soon after page load - when the experience's `<script>` has initialized. It's unlikely
+ *   that the experience is ready to run as assets and other dependencies may still be being downloaded. If the
+ *   experience features a splash page, this moment will almost certainly occur before the user taps on the
+ *   launch button.
+ *
+ * - `launched` occurs when the user taps on a splash screen's 'launch' button or, in the case that there's no launch
+ *   button, after construction. It's unlikely that the experience is ready to run as assets and other dependencies may
+ *   still be being downloaded. This moment is useful for showing permission dialogs to the user since it occurs after
+ *   they have indicated that they wish to proceed with the experience and is concurrent with any asset loading.
+ *
+ * - `started` occurs once both the loading is complete, and the user has tapped on a 'launch' button (if it exists).
+ *   It's the moment where any loading screen will be hidden and the experience starts from the perspective of
+ *   the user. Use this moment to start any audio, video or animation.
+ *
+ * - `loaded` occurs once all 'loadable' processes have completed (e.g. the downloading of assets). Since asset loading
+ *   starts as soon as the root component is constructed, this moment may occur before (or after) the user has tapped
+ *   on any 'launch' button.
+ *
+ * @zcontext */
 export declare class LoadContext extends Context {
     /** @zui */
     isConstructed: Observable<boolean, never>;
@@ -9,17 +35,22 @@ export declare class LoadContext extends Context {
     /** @zui */
     isStarted: Observable<boolean, never>;
     /** @zui */
+    isLaunched: Observable<boolean, never>;
+    /** @zui */
     progressPercent: Observable<number, never>;
     private _startedResolved;
     started: Promise<void>;
     private _constructedResolved;
     constructed: Promise<void>;
+    private _launchedResolved;
+    launched: Promise<void>;
     private _loadables;
     private _startWhenLoaded;
     private _totalLoadables;
     private _loadedCount;
     start(): void;
     constructionComplete(): void;
+    launch(): void;
     private _update;
     startWhenLoaded(): void;
     registerLoadable(p: Promise<any>): void;
@@ -30,10 +61,14 @@ export declare function useIsStarted(mgr: ContextManager): Observable<boolean, n
 export declare function isStarted(mgr: ContextManager): boolean;
 export declare function useIsConstructed(mgr: ContextManager): Observable<boolean, never>;
 export declare function isConstructed(mgr: ContextManager): boolean;
+export declare function useIsLaunched(mgr: ContextManager): Observable<boolean, never>;
+export declare function isLaunched(mgr: ContextManager): boolean;
 export declare function useLoadPercent(mgr: ContextManager): Observable<number, never>;
 export declare function registerLoadable(mgr: ContextManager, p: Promise<any>): void;
 export declare function start(mgr: ContextManager): void;
+export declare function launch(mgr: ContextManager): void;
 export declare function startWhenLoaded(mgr: ContextManager): void;
 export declare function started(mgr: ContextManager): Promise<void>;
 export declare function constructed(mgr: ContextManager): Promise<void>;
+export declare function launched(mgr: ContextManager): Promise<void>;
 export declare function constructionComplete(mgr: ContextManager): void;

package/lib/contexts/loadcontext.js

@@ -1,6 +1,32 @@
 import { Context } from '../context';
 import { Observable } from '../observable';
-/** @zcontext */
+/**
+ * LoadContext exposes to components and behaviors key moments during the initialization of the experience,
+ * and allows them to register long-running processes that should take place on any loading screen.
+ *
+ * There are several related, yet distinct, moments during initializatin that may be useful. In each case a `Promise`
+ * and an `Observable<boolean>` are exposed for use in components and behaviors.
+ *
+ * - `constructed` occurs when the root component's constructor (and thus any recursive children) has finished.
+ *   This often takes place very soon after page load - when the experience's `<script>` has initialized. It's unlikely
+ *   that the experience is ready to run as assets and other dependencies may still be being downloaded. If the
+ *   experience features a splash page, this moment will almost certainly occur before the user taps on the
+ *   launch button.
+ *
+ * - `launched` occurs when the user taps on a splash screen's 'launch' button or, in the case that there's no launch
+ *   button, after construction. It's unlikely that the experience is ready to run as assets and other dependencies may
+ *   still be being downloaded. This moment is useful for showing permission dialogs to the user since it occurs after
+ *   they have indicated that they wish to proceed with the experience and is concurrent with any asset loading.
+ *
+ * - `started` occurs once both the loading is complete, and the user has tapped on a 'launch' button (if it exists).
+ *   It's the moment where any loading screen will be hidden and the experience starts from the perspective of
+ *   the user. Use this moment to start any audio, video or animation.
+ *
+ * - `loaded` occurs once all 'loadable' processes have completed (e.g. the downloading of assets). Since asset loading
+ *   starts as soon as the root component is constructed, this moment may occur before (or after) the user has tapped
+ *   on any 'launch' button.
+ *
+ * @zcontext */
 export class LoadContext extends Context {
     constructor() {
         super(...arguments);
@@ -11,9 +37,12 @@ export class LoadContext extends Context {
         /** @zui */
         this.isStarted = new Observable(false);
         /** @zui */
+        this.isLaunched = new Observable(false);
+        /** @zui */
         this.progressPercent = new Observable(0);
         this.started = new Promise(resolve => this._startedResolved = resolve);
         this.constructed = new Promise(resolve => this._constructedResolved = resolve);
+        this.launched = new Promise(resolve => this._launchedResolved = resolve);
         this._loadables = new Set();
         this._startWhenLoaded = false;
         this._totalLoadables = 0;
@@ -22,14 +51,24 @@ export class LoadContext extends Context {
     start() {
         if (this.isStarted.value)
             return;
-        this.isStarted.value = true;
-        this._startedResolved?.();
         if (document.body)
             document.body.classList.add('zcomponent-started');
+        this.isStarted.value = true;
+        this._startedResolved?.();
     }
     constructionComplete() {
-        this._constructedResolved();
+        if (this.isConstructed.value)
+            return;
         this.isConstructed.value = true;
+        this._constructedResolved();
+    }
+    launch() {
+        if (this.isLaunched.value)
+            return;
+        if (document.body)
+            document.body.classList.add("zcomponent-launched");
+        this.isLaunched.value = true;
+        this._launchedResolved();
     }
     _update() {
         if (this._loadables.size > 0 && this.isLoaded.value === true) {
@@ -84,6 +123,12 @@ export function useIsConstructed(mgr) {
 export function isConstructed(mgr) {
     return mgr.get(LoadContext).isConstructed.value;
 }
+export function useIsLaunched(mgr) {
+    return mgr.get(LoadContext).isLaunched;
+}
+export function isLaunched(mgr) {
+    return mgr.get(LoadContext).isLaunched.value;
+}
 export function useLoadPercent(mgr) {
     return mgr.get(LoadContext).progressPercent;
 }
@@ -93,6 +138,9 @@ export function registerLoadable(mgr, p) {
 export function start(mgr) {
     return mgr.get(LoadContext).start();
 }
+export function launch(mgr) {
+    return mgr.get(LoadContext).launch();
+}
 export function startWhenLoaded(mgr) {
     return mgr.get(LoadContext).startWhenLoaded();
 }
@@ -102,6 +150,9 @@ export function started(mgr) {
 export function constructed(mgr) {
     return mgr.get(LoadContext).constructed;
 }
+export function launched(mgr) {
+    return mgr.get(LoadContext).launched;
+}
 export function constructionComplete(mgr) {
     return mgr.get(LoadContext).constructionComplete();
 }

package/lib/observable.d.ts

@@ -44,8 +44,8 @@ export declare class Observable<Type = never, TypeInternal extends any[] | [] |
      * @param withHandler - A function that will be called when the value (or any of its recursive descendent keys or elements) is changed
      * @param deep - Set to false to only track changes to the top level `value` itself (and not any of its descendent keys or elements)
      */
-    constructor(def: TypeInternal, withHandler?: ((v: TypeInternal) => void), deep?: boolean);
-    constructor(def: Type, withHandler?: ((v: Type) => void), deep?: boolean);
+    constructor(def: TypeInternal, withHandler?: ((v: TypeInternal) => void), deep?: boolean, callWithImmediately?: boolean);
+    constructor(def: Type, withHandler?: ((v: Type) => void), deep?: boolean, callWithImmediately?: boolean);
     /**
      * Access the current value for this Observable. Changing this value (or, unless deep inspection is disabled, its recursive elements and keys) will trigger any registered handlers to be called with the new value.
      *
@@ -54,7 +54,7 @@ export declare class Observable<Type = never, TypeInternal extends any[] | [] |
     get value(): Resolved<Type, TypeInternal>;
     private _wrap;
     set value(v: Resolved<Type, TypeInternal> | undefined);
-    addListener(fn: (v: Resolved<Type, TypeInternal>) => void, priority?: number): void;
+    addListener(fn: (v: Resolved<Type, TypeInternal>) => void, priority?: number, callImmediately?: boolean): void;
     private _emitValue;
 }
 export {};

package/lib/observable.js

@@ -32,7 +32,7 @@ import { Emitter } from "./emitter";
  * @typeParam TypeInternal - An internal type used to improve automatic type detection
  */
 export class Observable extends Emitter {
-    constructor(_default, withHandler, _deep = true) {
+    constructor(_default, withHandler, _deep = true, callWithImmediately = false) {
         super();
         this._default = _default;
         this._deep = _deep;
@@ -48,7 +48,7 @@ export class Observable extends Emitter {
         }
         this._value = this._wrap(initial);
         if (withHandler)
-            this.addListener(withHandler);
+            this.addListener(withHandler, 0, callWithImmediately);
     }
     /**
      * Access the current value for this Observable. Changing this value (or, unless deep inspection is disabled, its recursive elements and keys) will trigger any registered handlers to be called with the new value.
@@ -116,8 +116,10 @@ export class Observable extends Emitter {
         this._value = this._wrap(v);
         this._emitValue();
     }
-    addListener(fn, priority = 0) {
+    addListener(fn, priority = 0, callImmediately = true) {
         super.addListener(fn);
+        if (!callImmediately)
+            return;
         try {
             fn(this._value.proxy);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zcomponent/core",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "",
   "main": "index.js",
   "types": "index.d.ts",