@aiaiai-pt/design-system 0.32.0 → 0.34.0

package/components/renderer/registry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * DS renderer widget registry — the extensible dispatcher layer (#492).
+ *
+ * Ships a BASE registry with the two clean DS widgets (stat-grid + results-chart)
+ * and exposes a `registerWidget` hook so host apps (the portal, the admin) can
+ * append their own coupled widgets at startup without modifying this module
+ * (open/closed principle, JSONForms model).
+ *
+ * `dispatch.ts` (the tester/priority core) is the single dispatcher both the DS
+ * base registry and host-extended registries share; the registry is generic over
+ * the payload so `selectEntry` stays component-free and unit-testable.
+ *
+ * TH-08 preserved: `resolveWidget` returns the matched entry's known-good `key`
+ * literal — the operator's raw block `type`/`binding.kind` is never the key.
+ */
+import type { Component } from "svelte";
+import { type Match, type RegistryEntry } from "./dispatch";
+import type { Block, OntologySchema, WidgetKind, WidgetProps } from "./types";
+export type WidgetComponent = Component<WidgetProps>;
+/**
+ * A TYPE-specific widget over a shared kind (JSONForms model): the authoring
+ * `type` hint ranks it ABOVE the kind-generic widget (score 20 > 10) for the
+ * same binding. `type` is UNTRUSTED — it only influences ranking; the resolved
+ * key is the entry literal (TH-08).
+ */
+export declare function byTypeOnKind(key: string, kind: WidgetKind, component: unknown): RegistryEntry<WidgetComponent>;
+/** A widget whose tester is the generic "binding.kind === K" check (score 10). */
+export declare function byKind(key: string, kind: WidgetKind, component: unknown): RegistryEntry<WidgetComponent>;
+/**
+ * Register a widget in the host-extensible registry. Call at app startup
+ * (before any `resolveWidget` calls) to append host-specific widgets. Each
+ * entry is appended in call order; ties within the same score resolve to the
+ * first-registered entry (stable, deterministic — base entries win ties).
+ *
+ * Signature mirrors `byKind` / `byTypeOnKind` so the caller writes:
+ *   `registerWidget(byKind("entity-list", "list", EntityListWidget))`
+ *
+ * @param entry - A registry entry built with `byKind`, `byTypeOnKind`, or a
+ *   hand-crafted `{ key, payload, tester }` for a custom tester.
+ */
+export declare function registerWidget(entry: RegistryEntry<WidgetComponent>): void;
+/**
+ * Resolve a block to its widget via the tester/priority dispatcher. Searches
+ * the full registry (base DS entries + host-registered). Returns `null` when
+ * no widget applies — the caller renders per blast radius (`decideRender`),
+ * never interpolating the block's raw `type`/`kind`.
+ */
+export declare function resolveWidget(block: Block, schema?: OntologySchema | null): Match<WidgetComponent> | null;

package/components/renderer/registry.ts

@@ -0,0 +1,99 @@
+/**
+ * DS renderer widget registry — the extensible dispatcher layer (#492).
+ *
+ * Ships a BASE registry with the two clean DS widgets (stat-grid + results-chart)
+ * and exposes a `registerWidget` hook so host apps (the portal, the admin) can
+ * append their own coupled widgets at startup without modifying this module
+ * (open/closed principle, JSONForms model).
+ *
+ * `dispatch.ts` (the tester/priority core) is the single dispatcher both the DS
+ * base registry and host-extended registries share; the registry is generic over
+ * the payload so `selectEntry` stays component-free and unit-testable.
+ *
+ * TH-08 preserved: `resolveWidget` returns the matched entry's known-good `key`
+ * literal — the operator's raw block `type`/`binding.kind` is never the key.
+ */
+import type { Component } from "svelte";
+import {
+  NOT_APPLICABLE,
+  selectEntry,
+  type Match,
+  type RegistryEntry,
+} from "./dispatch";
+import type { Block, OntologySchema, WidgetKind, WidgetProps } from "./types";
+
+import ResultsChartWidget from "./ResultsChartWidget.svelte";
+import StatGridWidget from "./StatGridWidget.svelte";
+
+export type WidgetComponent = Component<WidgetProps>;
+
+/**
+ * A TYPE-specific widget over a shared kind (JSONForms model): the authoring
+ * `type` hint ranks it ABOVE the kind-generic widget (score 20 > 10) for the
+ * same binding. `type` is UNTRUSTED — it only influences ranking; the resolved
+ * key is the entry literal (TH-08).
+ */
+export function byTypeOnKind(
+  key: string,
+  kind: WidgetKind,
+  component: unknown,
+): RegistryEntry<WidgetComponent> {
+  return {
+    key,
+    payload: component as WidgetComponent,
+    tester: (binding, _schema, type) =>
+      binding.kind === kind && type === key ? 20 : NOT_APPLICABLE,
+  };
+}
+
+/** A widget whose tester is the generic "binding.kind === K" check (score 10). */
+export function byKind(
+  key: string,
+  kind: WidgetKind,
+  component: unknown,
+): RegistryEntry<WidgetComponent> {
+  return {
+    key,
+    payload: component as WidgetComponent,
+    tester: (binding) => (binding.kind === kind ? 10 : NOT_APPLICABLE),
+  };
+}
+
+/**
+ * Mutable internal registry — base DS entries first, host-registered entries
+ * appended in call order. Exported (readonly view) for introspection / testing.
+ */
+const _entries: RegistryEntry<WidgetComponent>[] = [
+  // DS base: the two clean widgets shipped by this package.
+  byKind("stat-grid", "kpi", StatGridWidget),
+  byTypeOnKind("results-chart", "aggregate", ResultsChartWidget),
+];
+
+/**
+ * Register a widget in the host-extensible registry. Call at app startup
+ * (before any `resolveWidget` calls) to append host-specific widgets. Each
+ * entry is appended in call order; ties within the same score resolve to the
+ * first-registered entry (stable, deterministic — base entries win ties).
+ *
+ * Signature mirrors `byKind` / `byTypeOnKind` so the caller writes:
+ *   `registerWidget(byKind("entity-list", "list", EntityListWidget))`
+ *
+ * @param entry - A registry entry built with `byKind`, `byTypeOnKind`, or a
+ *   hand-crafted `{ key, payload, tester }` for a custom tester.
+ */
+export function registerWidget(entry: RegistryEntry<WidgetComponent>): void {
+  _entries.push(entry);
+}
+
+/**
+ * Resolve a block to its widget via the tester/priority dispatcher. Searches
+ * the full registry (base DS entries + host-registered). Returns `null` when
+ * no widget applies — the caller renders per blast radius (`decideRender`),
+ * never interpolating the block's raw `type`/`kind`.
+ */
+export function resolveWidget(
+  block: Block,
+  schema: OntologySchema | null = null,
+): Match<WidgetComponent> | null {
+  return selectEntry(_entries, block.binding, schema, block.type);
+}

package/components/renderer/resolve-data.d.ts

@@ -0,0 +1,109 @@
+/**
+ * `resolveData(block)` — the single data path between a block's pointer and a
+ * widget (#73, spec §5). Reads the `binding`, fetches through the host-injected
+ * `DataProvider` (#492 P0), and returns normalised `{ schema, data, actionDef }`.
+ * The block stores ONLY the pointer — rows are never baked in.
+ *
+ * Pure + provider-injectable so the security-critical decisions (which paths are
+ * reachable, fail-closed on misconfig/upstream error) are unit/mutation-
+ * testable without SvelteKit. The route loader is a thin wrapper that passes a
+ * `createPublicDataProvider` wrapping its server `fetch` (which carries the
+ * tenant + graduated principal).
+ *
+ * Fail-closed (§14.8): an unmappable binding never fetches; a non-OK upstream
+ * yields `{ ok: false }` and the caller renders per blast radius (see
+ * `decideRender` in `./dispatch.ts`).
+ */
+import type { Binding, Block, FeedView, OntologySchema, WidgetKind } from "./types";
+import type { DataProvider } from "./data-provider";
+/**
+ * Presentational kinds (#75 M5 hero/lookup + #105 Phase 7 landing/content) that
+ * render PURELY from their block props — no data path, no fetch. resolveData
+ * short-circuits them with `{ data: null }`, which still satisfies decideRender's
+ * "matched + dataOk" contract (the widget owns its own props). Keeping them in
+ * one set means a new content section never accidentally tries to fetch.
+ */
+export declare const PRESENTATIONAL_KINDS: ReadonlySet<WidgetKind>;
+export interface ResolvedData {
+    data: unknown;
+    /** Ontology schema for the bound entity — wired in 73d. */
+    schema: OntologySchema | null;
+    /** Action definition for form bindings — wired in 73f. */
+    actionDef: unknown | null;
+    /** The BFF path the data came from (#75 M5 slice 4) — widgets that page
+     *  (list "load more") re-fetch it client-side with `?after=`. */
+    dataPath?: string;
+}
+export type ResolveDataResult = {
+    ok: true;
+    value: ResolvedData;
+} | {
+    ok: false;
+    status: number;
+    reason: string;
+};
+/** The minimal fetch shape we depend on (injectable; SvelteKit `fetch` fits). */
+export type FetchLike = (path: string) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface ResolveDataDeps {
+    /** Host-injected data transport seam (#492 P0). */
+    provider: DataProvider;
+    /**
+     * "Now", injected by the route loader (`new Date()`), used to compute the
+     * calendar's required `start`/`end` window (73e). Optional — only the
+     * `calendar` kind reads it. Injected (not read here) so the path stays
+     * deterministic in tests.
+     */
+    now?: Date;
+    /**
+     * The active feed view (`?view=` — #308), used only by the `feed` kind to
+     * pick which underlying feed (list/map) to resolve. Absent → the block's
+     * first configured view.
+     */
+    view?: string;
+    /**
+     * The URL's facet/search params (#308), forwarded to a feed read so the SSR
+     * feed is server-FILTERED (and paging rides `dataPath`). The BFF drops any
+     * param it doesn't declare (its security contract), so the whole set is safe
+     * to pass. Reserved keys (`view`, `reference`) are stripped by the loader.
+     */
+    filterParams?: Record<string, string>;
+}
+export declare function feedViews(props: Record<string, unknown> | undefined): FeedView[];
+/** The active view = the requested one when it's an available view, else the
+ *  default (first). Keeps `?view=` shareable + an unknown value harmless. */
+export declare function activeFeedView(views: FeedView[], requested: string | undefined): FeedView;
+/** Merge facet/search params into a BFF path (handles an existing `?`). Empty
+ *  values drop; an empty param set returns the path unchanged. */
+export declare function appendQuery(path: string, params: Record<string, string> | undefined): string;
+/**
+ * Pure mapping: pointer → BFF public path (#70 surface, app-first). Returns
+ * `null` for any binding that doesn't map to a wired read endpoint — the
+ * caller fails closed (no fetch, no DOM). `binding.filter` carries the
+ * per-route selector (ref/key/id) for the single-resource kinds.
+ */
+export declare function bffPathForBinding(binding: Binding, app: string): string | null;
+/**
+ * Pure mapping: pointer → BFF public *schema* path (#73 / 73d). Only the
+ * schema-driven kinds (`list`, `detail`) have one; the entity's field shape
+ * (key/type/label) lets EntityList/DetailView render columns/fields without a
+ * hardcoded entity-type union (§14.6). Returns `null` for every other kind, and
+ * for list/detail without an entity. `binding.filter` (the detail row id) is
+ * NOT part of the schema path — the schema is per *type*, not per row.
+ */
+export declare function schemaPathForBinding(binding: Binding, app: string): string | null;
+/**
+ * The date window the `/public/calendar` fetch requires (73e). The endpoint
+ * 422s without `start`/`end`, so the calendar block fetches a window computed
+ * from the injected "now": the current month through two months out (covering
+ * the default month view plus a buffer for next-month navigation). Pure given
+ * `now`, computed in UTC so it doesn't drift with the server timezone.
+ */
+export declare function calendarWindow(now: Date): {
+    start: string;
+    end: string;
+};
+export declare function resolveData(block: Block, deps: ResolveDataDeps): Promise<ResolveDataResult>;