From c20bc40326935e450ab3c60522f45cc3c3ba431c Mon Sep 17 00:00:00 2001 From: Brian Love Date: Tue, 9 Jun 2026 08:57:16 -0700 Subject: [PATCH] docs(render): fix snippet accuracy vs 0.0.49 API Co-Authored-By: Claude Opus 4.8 (1M context) --- .../render/api/define-angular-registry.mdx | 41 +++++++++++++++---- .../docs/render/api/provide-render.mdx | 2 +- .../docs/render/api/render-spec-component.mdx | 2 +- .../render/getting-started/introduction.mdx | 2 +- .../content/docs/render/guides/specs.mdx | 12 +++--- 5 files changed, 42 insertions(+), 17 deletions(-) diff --git a/apps/website/content/docs/render/api/define-angular-registry.mdx b/apps/website/content/docs/render/api/define-angular-registry.mdx index da9ebb98d..0a928cd63 100644 --- a/apps/website/content/docs/render/api/define-angular-registry.mdx +++ b/apps/website/content/docs/render/api/define-angular-registry.mdx @@ -12,7 +12,7 @@ import { defineAngularRegistry } from '@threadplane/render'; ```typescript function defineAngularRegistry( - componentMap: Record, + componentMap: Record, ): AngularRegistry; ``` @@ -20,9 +20,18 @@ function defineAngularRegistry( | Parameter | Type | Description | |-----------|------|-------------| -| `componentMap` | `Record` | An object mapping type name strings to Angular component classes | +| `componentMap` | `Record` | An object mapping type name strings to Angular component classes, or to `{ component, fallback? }` objects | -`AngularComponentRenderer` is defined as `Type` -- any Angular component class. +`AngularComponentRenderer` is defined as `Type` -- any Angular component class. Each entry can be a bare component class or a `RenderViewEntry` object: + +```typescript +interface RenderViewEntry { + component: AngularComponentRenderer; + fallback?: AngularComponentRenderer; +} +``` + +Use the object form to configure a custom per-entry fallback (see [Per-Component Fallbacks](#per-component-fallbacks) below). A bare component class is shorthand for `{ component }` paired with the library's default fallback. ### Returns @@ -118,15 +127,33 @@ An entry that omits `fallback` -- including every bare-component entry like `Tex ## Internal Behavior -The function converts the input object to an internal `Map` for O(1) lookups: +The function normalizes each input entry into a `{ component, fallback }` pair and stores them in an internal `Map` for O(1) lookups. A bare component class is paired with `DefaultFallbackComponent`; an object entry keeps its own `fallback` or falls back to the default: ```typescript +function normalize( + entry: AngularComponentRenderer | RenderViewEntry, +): NormalizedEntry { + // Bare Type — register with the default fallback. + if (typeof entry === 'function') { + return { component: entry, fallback: DefaultFallbackComponent }; + } + // Object form — preserve component; use configured fallback or default. + return { + component: entry.component, + fallback: entry.fallback ?? DefaultFallbackComponent, + }; +} + function defineAngularRegistry( - componentMap: Record, + componentMap: Record, ): AngularRegistry { - const map = new Map(Object.entries(componentMap)); + const map = new Map(); + for (const [name, entry] of Object.entries(componentMap)) { + map.set(name, normalize(entry)); + } return { - get: (name: string) => map.get(name), + get: (name: string) => map.get(name)?.component, + getFallback: (name: string) => map.get(name)?.fallback, names: () => [...map.keys()], }; } diff --git a/apps/website/content/docs/render/api/provide-render.mdx b/apps/website/content/docs/render/api/provide-render.mdx index 09815666a..a01bbf766 100644 --- a/apps/website/content/docs/render/api/provide-render.mdx +++ b/apps/website/content/docs/render/api/provide-render.mdx @@ -39,7 +39,7 @@ interface RenderConfig { |----------|------|-------------| | `registry` | `AngularRegistry` | Default component registry for all `` instances | | `store` | `StateStore` | Default state store for all `` instances | -| `functions` | `Record` | Default computed functions for `$fn` prop expressions | +| `functions` | `Record` | Default computed functions for `$computed` prop expressions | | `handlers` | `Record` | Default event handlers for action dispatch | All properties are optional. Only provide the defaults you need. diff --git a/apps/website/content/docs/render/api/render-spec-component.mdx b/apps/website/content/docs/render/api/render-spec-component.mdx index 7af8042c0..4d32968bc 100644 --- a/apps/website/content/docs/render/api/render-spec-component.mdx +++ b/apps/website/content/docs/render/api/render-spec-component.mdx @@ -38,7 +38,7 @@ export class MyComponent { | `spec` | `Spec \| null` | `null` | The json-render spec to render. When `null`, nothing is rendered. | | `registry` | `AngularRegistry \| undefined` | `undefined` | Component registry mapping element types to Angular components. | | `store` | `StateStore \| undefined` | `undefined` | State store for reactive prop resolution. | -| `functions` | `Record \| undefined` | `undefined` | Computed functions for `$fn` prop expressions. | +| `functions` | `Record \| undefined` | `undefined` | Computed functions for `$computed` prop expressions. | | `handlers` | `Record) => unknown \| Promise> \| undefined` | `undefined` | Event handlers invoked when components call `emit()`. | | `loading` | `boolean` | `false` | Whether the spec is currently streaming. Passed to all rendered components as the `loading` input. | diff --git a/apps/website/content/docs/render/getting-started/introduction.mdx b/apps/website/content/docs/render/getting-started/introduction.mdx index 8ea9c013b..6b723fcd5 100644 --- a/apps/website/content/docs/render/getting-started/introduction.mdx +++ b/apps/website/content/docs/render/getting-started/introduction.mdx @@ -29,7 +29,7 @@ The library resolves `Text` from your component registry, evaluates the `$state` ## How It Relates to @json-render/core -`@json-render/core` provides the spec format and the evaluation engine -- it resolves prop expressions (`$state`, `$item`, `$index`, `$bindState`, `$fn`), evaluates visibility conditions, and resolves bindings. It is framework-agnostic and has no Angular dependency. +`@json-render/core` provides the spec format and the evaluation engine -- it resolves prop expressions (`$state`, `$item`, `$index`, `$bindState`, `$computed`), evaluates visibility conditions, and resolves bindings. It is framework-agnostic and has no Angular dependency. `@threadplane/render` is the Angular adapter layer. It provides: diff --git a/apps/website/content/docs/render/guides/specs.mdx b/apps/website/content/docs/render/guides/specs.mdx index 8b692b206..e381df492 100644 --- a/apps/website/content/docs/render/guides/specs.mdx +++ b/apps/website/content/docs/render/guides/specs.mdx @@ -110,22 +110,20 @@ props: { } ``` -### $fn -- Computed Function +### $computed -- Computed Function Calls a registered computed function with the given arguments: ```typescript props: { label: { - $fn: { - name: 'uppercase', - args: { text: { $state: '/name' } } - } + $computed: 'uppercase', + args: { text: { $state: '/name' } } }, } ``` -The `name` references a function you register in a `functions` map. Each function is a `ComputedFunction` from `@json-render/core` -- `(args: Record) => unknown`. The `args` object is resolved first (so `{ $state: '/name' }` becomes the current value at `/name`), then passed to your function: +The `$computed` value names a function you register in a `functions` map. Each function is a `ComputedFunction` from `@json-render/core` -- `(args: Record) => unknown`. The `args` object is resolved first (so `{ $state: '/name' }` becomes the current value at `/name`), then passed to your function: ```typescript import type { ComputedFunction } from '@json-render/core'; @@ -154,7 +152,7 @@ provideRender({ }); ``` -With either wiring, the `$fn` expression above resolves `label` to the uppercased value of `/name`. The input takes priority over the `provideRender()` config when both are present. +With either wiring, the `$computed` expression above resolves `label` to the uppercased value of `/name`. The input takes priority over the `provideRender()` config when both are present. ## Children