ngx-json-render 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Angular renderer for json-render — stream AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -40,6 +40,10 @@
     ".": {
       "types": "./types/ngx-json-render.d.ts",
       "default": "./fesm2022/ngx-json-render.mjs"
+    },
+    "./testing": {
+      "types": "./types/ngx-json-render-testing.d.ts",
+      "default": "./fesm2022/ngx-json-render-testing.mjs"
     }
   },
   "type": "module"

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

@@ -0,0 +1,197 @@
+import { Spec, StateStore, ActionHandler, ComputedFunction, ValidationFunction, DirectiveDefinition } from '@json-render/core';
+import { Type, Provider } from '@angular/core';
+import { ComponentFixture } from '@angular/core/testing';
+import { 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,
+ * without their trailing newlines.
+ */
+type Recording = readonly string[];
+/**
+ * What to replay for a request. Either one recording for every request, a
+ * lookup by prompt, or a function for anything more involved.
+ */
+type Recordings = Recording | Readonly<Record<string, Recording>> | ((prompt: string, body: Readonly<Record<string, unknown>>) => Recording | undefined);
+/** An error the recorded server answers with instead of a stream. */
+interface RecordedFailure {
+    /** HTTP status. Defaults to 500. */
+    status?: number;
+    /** The `message` field of the JSON error body. */
+    message?: string;
+}
+/** Options for {@link recordedTransport}. */
+interface RecordedTransportOptions {
+    /**
+     * Milliseconds between lines — the pace a model would emit them at.
+     * Defaults to 0, which still yields to the event loop between lines, so a
+     * test can observe the stream in flight.
+     */
+    delayMs?: number;
+    /**
+     * Answer with an error instead of a stream. A function is called per
+     * request, so a test can turn the failure on and off between sends.
+     */
+    fail?: RecordedFailure | (() => RecordedFailure | null | undefined);
+    /**
+     * Pull the prompt out of the request body. The default reads `prompt`
+     * (what `injectUIStream` sends) and falls back to the last message's
+     * content (what `injectChatUI` sends).
+     */
+    promptOf?: (body: Readonly<Record<string, unknown>>) => string;
+}
+/**
+ * A `fetch` that answers the streaming hooks from a recording instead of a
+ * server.
+ *
+ * Both {@link injectUIStream} and {@link injectChatUI} take any function with
+ * fetch's shape, so a test runs the real client — request body, streamed
+ * lines, usage metadata, abort on supersede — with no server, no API key and
+ * no global patched behind the test's back. Only the transport is recorded.
+ *
+ * @example
+ * ```ts
+ * const ui = injectUIStream({
+ *   api: '/api/generate',
+ *   fetch: recordedTransport(specStream(spec)),
+ * });
+ * ```
+ *
+ * @example Different answers per prompt, at a visible pace:
+ * ```ts
+ * recordedTransport(
+ *   { 'a dashboard': specStream(dashboard), 'a form': specStream(form) },
+ *   { delayMs: 20 },
+ * );
+ * ```
+ */
+declare function recordedTransport(recordings: Recordings, options?: RecordedTransportOptions): typeof globalThis.fetch;
+/**
+ * The JSONL patch lines a model would emit to build `spec`: the root, then
+ * the state, then one line per element in declaration order.
+ *
+ * Recording a stream by hand means writing patches by hand; this writes them
+ * from the spec a test already has, so the test says what it renders rather
+ * than how the wire spells it.
+ */
+declare function specStream(spec: Spec): string[];
+/**
+ * The usage metadata line `injectUIStream` reads into its `usage` signal.
+ * Append it to a recording to exercise that path.
+ */
+declare function usageLine(usage: {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}): string;
+
+/** One action the spec asked for, in the order it was dispatched. */
+interface DispatchedAction {
+    name: string;
+    params?: Record<string, unknown>;
+}
+/** Options for {@link renderSpec}. Everything but `registry` is optional. */
+interface RenderSpecOptions {
+    /** Catalog type name → Angular component. The one required option. */
+    registry: ComponentRegistry;
+    /** Initial state model. Defaults to the spec's own `state`. */
+    state?: StateModel;
+    /** External store, for controlled mode. */
+    store?: StateStore | null;
+    /** Action handlers by name. Dispatches are recorded either way. */
+    handlers?: Record<string, ActionHandler>;
+    /** Catch-all handler for actions with no dedicated handler. */
+    onAction?: (name: string, params?: Record<string, unknown>) => unknown;
+    /** Navigation function for `onSuccess: { navigate }`. */
+    navigate?: (path: string) => void;
+    /** Fallback component for unknown types. */
+    fallback?: Type<unknown> | RegistryEntry | null;
+    /** Named functions for `$computed` props. */
+    functions?: Record<string, ComputedFunction>;
+    /** Custom validation functions. */
+    validationFunctions?: Record<string, ValidationFunction>;
+    /** Custom directives for `$`-prefixed values. */
+    directives?: DirectiveDefinition[];
+    /** Render as if the spec were still streaming. */
+    loading?: boolean;
+    /** Extra TestBed providers, e.g. a `JR_CONFIRM_DIALOG` replacement. */
+    providers?: Provider[];
+}
+/**
+ * A rendered spec, and the handful of things a test does to one.
+ *
+ * `fixture` and `element` are there for everything this does not cover — the
+ * harness is a shortcut, not a wall.
+ */
+interface SpecHarness {
+    /** The fixture of the host that owns the `<json-render>`. */
+    readonly fixture: ComponentFixture<unknown>;
+    /** The host element, the root of the rendered DOM. */
+    readonly element: HTMLElement;
+    /** The renderer instance. */
+    readonly renderer: JsonRenderer;
+    /** The renderer's state store. */
+    readonly store: JsonRenderStateService;
+    /** The renderer's validation service. */
+    readonly validation: JsonRenderValidationService;
+    /** Every action the spec dispatched, handled or not, in order. */
+    readonly dispatched: readonly DispatchedAction[];
+    /** Every state change the renderer emitted, flattened, in order. */
+    readonly changes: readonly StateChange[];
+    /** Render a different spec (a later streaming frame, say). */
+    setSpec(spec: Spec | null): Promise<void>;
+    /** Flip the loading flag catalog components see. */
+    setLoading(loading: boolean): Promise<void>;
+    /** Let effects, promises and change detection finish. */
+    settle(): Promise<void>;
+    /** Read a state path, e.g. `/form/email`. */
+    read(path: string): unknown;
+    /** Write a state path and settle. */
+    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;
+}
+/**
+ * Render a spec against a registry and hand back the few things a test does
+ * to it.
+ *
+ * Testing a catalog component otherwise means a host component, a TestBed
+ * module, a zoneless provider, two settle passes and a `querySelector` — the
+ * same twenty lines in every project that adopts this package, none of them
+ * about the component under test.
+ *
+ * @example
+ * ```ts
+ * const ui = await renderSpec(
+ *   {
+ *     root: 'save',
+ *     elements: {
+ *       save: { type: 'Button', props: { label: 'Save' }, on: { press: { action: 'save' } } },
+ *     },
+ *   },
+ *   { registry: { Button: MyButton } },
+ * );
+ *
+ * expect(ui.text('button')).toBe('Save');
+ * await ui.click('button');
+ * expect(ui.dispatched).toEqual([{ name: 'save', params: {} }]);
+ * ```
+ */
+declare function renderSpec(spec: Spec | null, options: RenderSpecOptions): Promise<SpecHarness>;
+
+export { recordedTransport, renderSpec, specStream, usageLine };
+export type { DispatchedAction, RecordedFailure, RecordedTransportOptions, Recording, Recordings, RenderSpecOptions, SpecHarness };