ngx-json-render 0.8.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",

package/types/ngx-json-render.d.ts

@@ -319,6 +319,14 @@ interface RegistryEntry {
     component: Type<unknown>;
     /** Slot names this component supports (from the catalog definition). */
     slots?: string[];
+    /**
+     * Shown instead of `component` while the spec streams and this element's
+     * props do not yet pass its component's schema in the renderer's
+     * `catalog`. It gets the same render context, so it can read the props
+     * that have arrived and place `<jr-children />`. Without one, the element
+     * renders nothing until it is ready.
+     */
+    fallback?: Type<unknown>;
 }
 /**
  * Registry of component renderers: catalog type name → Angular component
@@ -327,10 +335,11 @@ interface RegistryEntry {
 type ComponentRegistry = Record<string, Type<unknown> | RegistryEntry>;
 /**
  * Registry of all Angular components for a catalog. Keys are checked against
- * the catalog's component names.
+ * the catalog's component names. A value is the component, or the component
+ * with a {@link RegistryEntry.fallback} to show while its props stream in.
  */
 type Components<C extends Catalog> = {
-    [K in keyof InferCatalogComponents<C>]: Type<unknown>;
+    [K in keyof InferCatalogComponents<C>]: Type<unknown> | Pick<RegistryEntry, 'component' | 'fallback'>;
 };
 /**
  * The repeat scope available to elements rendered inside a `repeat` block.
@@ -509,8 +518,14 @@ declare class JsonRenderer {
      * `$bindState`, `$template`, a directive — has no value until render time,
      * so it is not checked.
      *
-     * Only read when `validate` is on, and — like the rest of the check —
-     * skipped while `loading`.
+     * The check is read only when `validate` is on, and — like the rest of
+     * it — skipped while `loading`.
+     *
+     * While `loading`, the catalog also gates mounting, whatever `validate` is:
+     * an element whose props do not yet pass its component's schema shows its
+     * registry entry's `fallback`, or nothing, instead of a component with half
+     * its props. Once an element has mounted it stays mounted, and when
+     * `loading` ends every element mounts.
      */
     readonly catalog: _angular_core.InputSignal<SpecCatalog | null>;
     /**
@@ -700,6 +715,21 @@ declare class JrElement {
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     readonly bindings: Signal<Record<string, string> | undefined>;
     private readonly entry;
+    /** Set once the real component has been shown; see {@link held}. */
+    private mounted;
+    /**
+     * Whether the component waits for its props: the spec is still loading, a
+     * catalog was given, and the props written so far do not pass the
+     * component's schema (see {@link propsArrived}).
+     *
+     * One-way. Once the component has been shown it is never swapped back for
+     * the fallback, even if a later patch takes a prop away again: a component
+     * flickering out mid-stream is worse than one showing a gap. Once latched
+     * this reads no signals, so a mounted element pays nothing for the gate on
+     * later patches — and neither does any element when nothing is loading.
+     */
+    protected readonly held: Signal<boolean>;
+    /** What the outlet shows: the component, or its fallback while held. */
     protected readonly component: Signal<_angular_core.Type<unknown> | null>;
     protected readonly devtoolsKey: Signal<string | null>;
     /**
@@ -926,6 +956,11 @@ declare class JsonRenderRootContext {
      * they apply whatever `validate` is set to.
      */
     limits: Signal<RenderLimits | null | undefined>;
+    /**
+     * The catalog the spec was generated for. While loading, an element whose
+     * props do not pass its component's schema waits for them.
+     */
+    catalog: Signal<SpecCatalog | null | undefined>;
     /** External store (controlled mode). */
     store: Signal<StateStore | null | undefined>;
     /** Initial state (uncontrolled mode); falls back to `spec.state`. */