ngx-json-render 0.4.0 → 0.5.1

package/package.json

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

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

@@ -1,7 +1,7 @@
 import { Spec, StateStore, ActionHandler, ComputedFunction, ValidationFunction, DirectiveDefinition } from '@json-render/core';
-import { Type, Provider } from '@angular/core';
+import { Provider, Type } from '@angular/core';
 import { ComponentFixture } from '@angular/core/testing';
-import { ComponentRegistry, StateModel, RegistryEntry, JsonRenderer, JsonRenderStateService, JsonRenderValidationService, StateChange } from 'ngx-json-render';
+import { RenderContext, ComponentRegistry, StateModel, RegistryEntry, JsonRenderer, JsonRenderStateService, JsonRenderValidationService, StateChange } from 'ngx-json-render';
 
 /**
  * The lines of one recorded response body, in the order the server sent them,
@@ -85,6 +85,111 @@ declare function usageLine(usage: {
     totalTokens?: number;
 }): string;
 
+/** The DOM half of a harness. */
+interface DomQueries {
+    /** Trimmed text of the first match, or of everything when given nothing. */
+    text(selector?: string): string;
+    /** Trimmed text of every match. */
+    texts(selector: string): string[];
+    /** The first match. Throws when there is none. */
+    find<T extends HTMLElement>(selector: string): T;
+    /** Every match, possibly none. */
+    findAll<T extends HTMLElement>(selector: string): T[];
+    /** Click an element (or the first match of a selector) and settle. */
+    click(target: string | Element): Promise<void>;
+    /** Set an input's value, fire `input`, and settle. */
+    fill(target: string | Element, value: string): Promise<void>;
+}
+
+/** One `setBound` call that reached a bound prop, in order. */
+interface BoundWrite {
+    prop: string;
+    value: unknown;
+}
+/** Options for {@link renderComponent}. Everything is optional. */
+interface RenderComponentOptions<P extends object> {
+    /** The resolved props the component sees. Defaults to `{}`. */
+    props?: P;
+    /**
+     * Which props are two-way bound, as `prop → state path` — what
+     * `$bindState` / `$bindItem` would have resolved to. A `setBound` on a prop
+     * listed here is recorded and written back into `props`; on any other prop
+     * it is a no-op, exactly as under the renderer.
+     */
+    bindings?: Record<string, string>;
+    /**
+     * The events the spec would bind in `on`. Only affects what `ctx.on(event)`
+     * reports as `bound` — `emitted` records every event regardless.
+     */
+    on?: readonly string[];
+    /** The loading flag the component sees. */
+    loading?: boolean;
+    /** The spec key, for components that `injectElementKey()`. */
+    key?: string;
+    /** The element's catalog type name. */
+    type?: string;
+    /** Extra TestBed providers for anything else the component injects. */
+    providers?: Provider[];
+}
+/**
+ * A catalog component mounted on its own, and what it said to the renderer
+ * it thinks it is inside.
+ */
+interface ComponentHarness<T, P extends object> extends DomQueries {
+    /** The fixture of the host the component is mounted in. */
+    readonly fixture: ComponentFixture<unknown>;
+    /** The host element, the root of the rendered DOM. */
+    readonly element: HTMLElement;
+    /** The component instance. */
+    readonly component: T;
+    /** The render context the component injected. */
+    readonly context: RenderContext<P>;
+    /** Every event the component emitted, bound or not, in order. */
+    readonly emitted: readonly string[];
+    /** Every `setBound` that reached a bound prop, in order. */
+    readonly writes: readonly BoundWrite[];
+    /** The props as the component currently sees them. */
+    props(): P;
+    /** Replace the props and settle. */
+    setProps(props: P): Promise<void>;
+    /** Merge into the props and settle. */
+    patchProps(patch: Partial<P>): Promise<void>;
+    /** Flip the loading flag and settle. */
+    setLoading(loading: boolean): Promise<void>;
+    /** Let effects, promises and change detection finish. */
+    settle(): Promise<void>;
+    /** Destroy the fixture. Rarely needed — TestBed resets between tests. */
+    destroy(): void;
+}
+/**
+ * Mount a catalog component with no renderer and no spec: hand it props, and
+ * read back the events it emitted and the values it wrote to bound props.
+ *
+ * This is the test of a component as a presentational one — what it draws
+ * for these props, and what it says when used. What the spec then does with
+ * that is the renderer's business, and `renderSpec` is where to test it.
+ *
+ * `props` is not inferred from the first value, so a later `patchProps` can
+ * set a prop the first render left out. Pass `P` to have the props typed.
+ *
+ * A component that renders `<jr-children>`, registers field validation or
+ * dispatches actions directly needs the renderer's services and fails with a
+ * message pointing at `renderSpec`.
+ *
+ * @example
+ * ```ts
+ * const button = await renderComponent(MyButton, { props: { label: 'Save' } });
+ *
+ * expect(button.text('button')).toBe('Save');
+ * await button.click('button');
+ * expect(button.emitted).toEqual(['press']);
+ *
+ * await button.patchProps({ disabled: true });
+ * expect(button.find<HTMLButtonElement>('button').disabled).toBe(true);
+ * ```
+ */
+declare function renderComponent<T, P extends object = Record<string, unknown>>(component: Type<T>, options?: RenderComponentOptions<NoInfer<P>>): Promise<ComponentHarness<T, P>>;
+
 /** One action the spec asked for, in the order it was dispatched. */
 interface DispatchedAction {
     name: string;
@@ -123,7 +228,7 @@ interface RenderSpecOptions {
  * `fixture` and `element` are there for everything this does not cover — the
  * harness is a shortcut, not a wall.
  */
-interface SpecHarness {
+interface SpecHarness extends DomQueries {
     /** The fixture of the host that owns the `<json-render>`. */
     readonly fixture: ComponentFixture<unknown>;
     /** The host element, the root of the rendered DOM. */
@@ -150,18 +255,6 @@ interface SpecHarness {
     write(path: string, value: unknown): Promise<void>;
     /** The whole state model. */
     state(): StateModel;
-    /** Trimmed text of the first match, or of everything when given nothing. */
-    text(selector?: string): string;
-    /** Trimmed text of every match. */
-    texts(selector: string): string[];
-    /** The first match. Throws when there is none. */
-    find<T extends HTMLElement>(selector: string): T;
-    /** Every match, possibly none. */
-    findAll<T extends HTMLElement>(selector: string): T[];
-    /** Click an element (or the first match of a selector) and settle. */
-    click(target: string | Element): Promise<void>;
-    /** Set an input's value, fire `input`, and settle. */
-    fill(target: string | Element, value: string): Promise<void>;
     /** Destroy the fixture. Rarely needed — TestBed resets between tests. */
     destroy(): void;
 }
@@ -193,5 +286,5 @@ interface SpecHarness {
  */
 declare function renderSpec(spec: Spec | null, options: RenderSpecOptions): Promise<SpecHarness>;
 
-export { recordedTransport, renderSpec, specStream, usageLine };
-export type { DispatchedAction, RecordedFailure, RecordedTransportOptions, Recording, Recordings, RenderSpecOptions, SpecHarness };
+export { recordedTransport, renderComponent, renderSpec, specStream, usageLine };
+export type { BoundWrite, ComponentHarness, DispatchedAction, RecordedFailure, RecordedTransportOptions, Recording, Recordings, RenderComponentOptions, RenderSpecOptions, SpecHarness };

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

@@ -604,7 +604,22 @@ declare class JrElement {
     /** Prop/visibility resolution context (state + repeat scope + extensions). */
     private readonly resolutionCtx;
     protected readonly visible: Signal<boolean>;
-    /** The element with all prop expressions resolved. */
+    /**
+     * The element with all prop expressions resolved.
+     *
+     * Resolving builds a new props object on every state write, whatever the
+     * write touched. Handing that on as a change would re-run every catalog
+     * template in the tree for one keystroke, so a result that holds the same
+     * values as the last one counts as unchanged and keeps the old object.
+     *
+     * Two-way bound elements are the exception, and keep treating every
+     * resolution as a change. Their component writes the user's input into the
+     * DOM before it reaches state, so the DOM can differ from a prop whose
+     * value never did: typing and a `clearStatePath` in the same turn take
+     * the prop from '' through 'milk' back to '' with nobody reading 'milk'.
+     * The README tells catalog authors to sync such inputs with an effect on
+     * props, and that effect only gets to put the DOM right if it runs.
+     */
     readonly resolvedElement: Signal<UIElement<string, Record<string, unknown>> | undefined>;
     /** Two-way binding paths ($bindState / $bindItem) by prop name. */
     readonly bindings: Signal<Record<string, string> | undefined>;
@@ -643,6 +658,12 @@ declare class JrElement {
      */
     private fireEvent;
     private emitEvent;
+    /**
+     * Run an `on` or `watch` binding's actions in order. Params are resolved
+     * per action, just before it runs, so a `$state` read in a later action of
+     * the chain sees what an earlier one wrote.
+     */
+    private dispatch;
     private eventHandle;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<JrElement, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<JrElement, "jr-element", never, { "elementKey": { "alias": "elementKey"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;