@aiaiai-pt/design-system 0.33.0 → 0.35.0

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

@@ -0,0 +1,82 @@
+/**
+ * DataProvider — the host-injected data transport seam (#492 P0).
+ *
+ * Each host (portal, admin) owns its own DataProvider. The portal constructs a
+ * `createPublicDataProvider` that routes through the auth-optional `/bff` proxy.
+ * A future admin host constructs its own provider over the RLS-authenticated
+ * entity-proxy lane. `resolveData` depends only on this interface, never on
+ * the proxy prefix or the tenant/app segment directly.
+ */
+import type { Binding } from "./types";
+import type { FetchLike } from "./resolve-data";
+import type { VoteReadConfig } from "./vote";
+export interface DataUrlOpts {
+    /** Calendar window injected from `now` (73e) — applied only for the `calendar` kind. */
+    calendarWindow?: {
+        start: string;
+        end: string;
+    };
+    /** URL facet/search params forwarded from the page URL (#308) — applied for `list`/`map`. */
+    filterParams?: Record<string, string>;
+}
+/**
+ * SECURITY INVARIANT (never remove this comment):
+ * Each host owns its own DataProvider and its own security boundary. The
+ * portal's DataProvider routes through the public /bff proxy (auth-optional,
+ * SSRF-pinned to /{app}/public/). A future admin DataProvider routes through
+ * the RLS-authenticated entity-proxy lane. NEVER share one transport across
+ * both hosts. NEVER let a public widget read through an authed token, nor
+ * expose the authed lane through the public proxy. A "simplification" that
+ * collapses the two providers is a tenant/RLS leak.
+ */
+export interface DataProvider {
+    /**
+     * The raw data path for the binding, with calendar window and filter params
+     * applied. Returns `null` for unmappable bindings (caller fails closed).
+     * The path is the PAGEABLE surface: widgets re-fetch it client-side with
+     * `?after=` for "load more". It does NOT include the proxy prefix — the
+     * provider's `fetch` adds the prefix on the outbound call.
+     */
+    dataUrl(binding: Binding, opts?: DataUrlOpts): string | null;
+    /**
+     * The entity schema path for the binding. Returns `null` for kinds that
+     * carry no schema (content, map, calendar, …). The path does NOT include
+     * the proxy prefix.
+     */
+    schemaUrl(binding: Binding): string | null;
+    /**
+     * The authed account lane URL for the given path segment.
+     * Returns `/me/{segment}` — NO `/bff` prefix. This is a different security
+     * boundary (require_auth + OWN-scoped) from the public `/bff` surface.
+     */
+    accountUrl(segment: string): string;
+    /**
+     * The option-view read URL (for subscription scope dropdowns, #252).
+     * Returns the FULL URL including the proxy prefix.
+     */
+    optionViewUrl(view: string, limit: number): string;
+    /** Edition read path for the `vote` ballot composer. Full URL. */
+    voteEditionUrl(cfg: VoteReadConfig, editionId: string): string;
+    /** Options read path for the `vote` ballot composer. Full URL. */
+    voteOptionsUrl(cfg: VoteReadConfig, editionId: string): string;
+    /** The fetch transport. Accepts any URL returned by the methods above. */
+    fetch: FetchLike;
+}
+/**
+ * Construct the portal's public DataProvider.
+ *
+ * Reproduces today's `resolveData` URL behavior byte-for-byte:
+ *   - `dataUrl` / `schemaUrl` return the raw `/{app}/public/...` path (no
+ *     `/bff` prefix). The provider's `fetch` adds `/bff` on the outbound call
+ *     so the raw path is also the pageable `dataPath` the widgets store.
+ *   - `accountUrl` returns `/me/{segment}` — the authed lane, never proxied
+ *     through `/bff`. The provider's `fetch` passes `/me/...` through as-is.
+ *   - `optionViewUrl`, `voteEditionUrl`, `voteOptionsUrl` return the full URL
+ *     already including `/bff`. The provider's `fetch` passes them through.
+ *
+ * The `fetch` wrapper decides by prefix: `/bff/` and `/me/` are passed
+ * through unchanged; anything else (raw `/{app}/public/...` paths) gets
+ * `/bff` prepended. This keeps the `fetch` self-contained in the provider —
+ * `resolveData` never sees or constructs a proxy prefix.
+ */
+export declare function createPublicDataProvider(app: string, fetchImpl: FetchLike): DataProvider;

package/components/renderer/data-provider.ts

@@ -0,0 +1,162 @@
+/**
+ * DataProvider — the host-injected data transport seam (#492 P0).
+ *
+ * Each host (portal, admin) owns its own DataProvider. The portal constructs a
+ * `createPublicDataProvider` that routes through the auth-optional `/bff` proxy.
+ * A future admin host constructs its own provider over the RLS-authenticated
+ * entity-proxy lane. `resolveData` depends only on this interface, never on
+ * the proxy prefix or the tenant/app segment directly.
+ */
+
+import type { Binding } from "./types";
+import type { FetchLike } from "./resolve-data";
+import type { VoteReadConfig } from "./vote";
+import {
+  bffPathForBinding,
+  schemaPathForBinding,
+  appendQuery,
+} from "./resolve-data";
+import { editionReadPath, optionsReadPath } from "./vote";
+
+export interface DataUrlOpts {
+  /** Calendar window injected from `now` (73e) — applied only for the `calendar` kind. */
+  calendarWindow?: { start: string; end: string };
+  /** URL facet/search params forwarded from the page URL (#308) — applied for `list`/`map`. */
+  filterParams?: Record<string, string>;
+}
+
+/**
+ * SECURITY INVARIANT (never remove this comment):
+ * Each host owns its own DataProvider and its own security boundary. The
+ * portal's DataProvider routes through the public /bff proxy (auth-optional,
+ * SSRF-pinned to /{app}/public/). A future admin DataProvider routes through
+ * the RLS-authenticated entity-proxy lane. NEVER share one transport across
+ * both hosts. NEVER let a public widget read through an authed token, nor
+ * expose the authed lane through the public proxy. A "simplification" that
+ * collapses the two providers is a tenant/RLS leak.
+ */
+export interface DataProvider {
+  /**
+   * The raw data path for the binding, with calendar window and filter params
+   * applied. Returns `null` for unmappable bindings (caller fails closed).
+   * The path is the PAGEABLE surface: widgets re-fetch it client-side with
+   * `?after=` for "load more". It does NOT include the proxy prefix — the
+   * provider's `fetch` adds the prefix on the outbound call.
+   */
+  dataUrl(binding: Binding, opts?: DataUrlOpts): string | null;
+
+  /**
+   * The entity schema path for the binding. Returns `null` for kinds that
+   * carry no schema (content, map, calendar, …). The path does NOT include
+   * the proxy prefix.
+   */
+  schemaUrl(binding: Binding): string | null;
+
+  /**
+   * The authed account lane URL for the given path segment.
+   * Returns `/me/{segment}` — NO `/bff` prefix. This is a different security
+   * boundary (require_auth + OWN-scoped) from the public `/bff` surface.
+   */
+  accountUrl(segment: string): string;
+
+  /**
+   * The option-view read URL (for subscription scope dropdowns, #252).
+   * Returns the FULL URL including the proxy prefix.
+   */
+  optionViewUrl(view: string, limit: number): string;
+
+  /** Edition read path for the `vote` ballot composer. Full URL. */
+  voteEditionUrl(cfg: VoteReadConfig, editionId: string): string;
+
+  /** Options read path for the `vote` ballot composer. Full URL. */
+  voteOptionsUrl(cfg: VoteReadConfig, editionId: string): string;
+
+  /** The fetch transport. Accepts any URL returned by the methods above. */
+  fetch: FetchLike;
+}
+
+function enc(value: string): string {
+  return encodeURIComponent(value);
+}
+
+/**
+ * Construct the portal's public DataProvider.
+ *
+ * Reproduces today's `resolveData` URL behavior byte-for-byte:
+ *   - `dataUrl` / `schemaUrl` return the raw `/{app}/public/...` path (no
+ *     `/bff` prefix). The provider's `fetch` adds `/bff` on the outbound call
+ *     so the raw path is also the pageable `dataPath` the widgets store.
+ *   - `accountUrl` returns `/me/{segment}` — the authed lane, never proxied
+ *     through `/bff`. The provider's `fetch` passes `/me/...` through as-is.
+ *   - `optionViewUrl`, `voteEditionUrl`, `voteOptionsUrl` return the full URL
+ *     already including `/bff`. The provider's `fetch` passes them through.
+ *
+ * The `fetch` wrapper decides by prefix: `/bff/` and `/me/` are passed
+ * through unchanged; anything else (raw `/{app}/public/...` paths) gets
+ * `/bff` prepended. This keeps the `fetch` self-contained in the provider —
+ * `resolveData` never sees or constructs a proxy prefix.
+ */
+export function createPublicDataProvider(
+  app: string,
+  fetchImpl: FetchLike,
+): DataProvider {
+  /**
+   * Portal fetch transport. Paths that already carry their proxy prefix
+   * (`/bff/...` for the public lane, `/me/...` for the authed account lane)
+   * are forwarded unchanged. Raw `/{app}/public/...` paths (returned by
+   * `dataUrl` and `schemaUrl`) are proxied through `/bff`.
+   */
+  const fetch: FetchLike = (url: string) => {
+    if (url.startsWith("/bff/") || url.startsWith("/me/")) {
+      return fetchImpl(url);
+    }
+    return fetchImpl(`/bff${url}`);
+  };
+
+  return {
+    dataUrl(binding: Binding, opts?: DataUrlOpts): string | null {
+      const path = bffPathForBinding(binding, app);
+      if (path === null) return null;
+      let url = path;
+      // Calendar requires start/end (73e); the window is pre-computed in
+      // resolveData from `now` and passed in via opts.
+      if (binding.kind === "calendar" && opts?.calendarWindow) {
+        const { start, end } = opts.calendarWindow;
+        url = `${path}?start=${start}&end=${end}`;
+      }
+      // Forward URL facet/search params (#308) for list + map feeds so the
+      // SSR result is server-FILTERED. The BFF drops undeclared params.
+      if (
+        (binding.kind === "list" || binding.kind === "map") &&
+        opts?.filterParams
+      ) {
+        url = appendQuery(url, opts.filterParams);
+      }
+      return url;
+    },
+
+    schemaUrl(binding: Binding): string | null {
+      return schemaPathForBinding(binding, app);
+    },
+
+    accountUrl(segment: string): string {
+      return `/me/${segment}`;
+    },
+
+    optionViewUrl(view: string, limit: number): string {
+      return `/bff/${enc(app)}/public/${enc(view)}?limit=${limit}`;
+    },
+
+    voteEditionUrl(cfg: VoteReadConfig, editionId: string): string {
+      // Delegates to the unchanged vote.ts helper — guarantees byte-identical
+      // vote URLs (vote.ts must NOT be modified, spec §P0).
+      return editionReadPath(app, cfg, editionId);
+    },
+
+    voteOptionsUrl(cfg: VoteReadConfig, editionId: string): string {
+      return optionsReadPath(app, cfg, editionId);
+    },
+
+    fetch,
+  };
+}

package/components/renderer/dispatch.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Widget dispatcher — tester/priority, not a flat map (D4, JSONForms model).
+ *
+ * Generalises the admin app's XSS-hardened layout registry
+ * (`admin/src/lib/renderer-layouts/resolve.ts`) from form-row LayoutKeys to
+ * widget `kind`s. Each entry carries a `tester(binding, schema) → score`; the
+ * highest score wins. A more specific tester (e.g. "list of `occurrence`")
+ * outranks the generic "any list" and overrides one widget for one entity
+ * WITHOUT editing the catalog (open/closed).
+ *
+ * The ranking core here is generic over the payload `P` so it stays
+ * component-free and fully unit/mutation-testable; the real registry (73b)
+ * instantiates it with Svelte `Component`s.
+ *
+ * TH-08 (R-SEC-07) preserved: the resolved `key` is a known-good literal from
+ * the matched entry — the operator's raw `binding.kind`/`entity`/block `type`
+ * is NEVER returned as the key, so it never reaches `class`/`data-*`/`style`.
+ */
+import type { Binding, Block, OntologySchema } from "./types";
+/** Tester sentinel — "this widget does not apply to this binding". */
+export declare const NOT_APPLICABLE = -1;
+/**
+ * A tester ranks a registry entry against a binding (+ optional schema and the
+ * block's authoring `type` hint). JSONForms model: testers see the full
+ * element, so a type-specific widget (e.g. `filter-bar`) can out-rank the
+ * generic kind widget (`entity-list`) for the SAME `binding.kind` without
+ * editing the kind entry. `type` is UNTRUSTED — it only influences ranking; the
+ * resolved `key` still comes from the matched entry (TH-08), never from `type`.
+ */
+export type WidgetTester = (binding: Binding, schema: OntologySchema | null, type?: string) => number;
+export interface RegistryEntry<P> {
+    /** Known-good literal. Safe to render as `data-widget={key}` (TH-08). */
+    key: string;
+    payload: P;
+    tester: WidgetTester;
+}
+export interface Match<P> {
+    key: string;
+    payload: P;
+}
+/**
+ * Run every tester against the binding; the highest applicable score wins.
+ * Ties resolve to the first-registered entry (stable, deterministic). Returns
+ * `null` when no tester is applicable — the caller fails closed per blast
+ * radius; nothing about the binding is interpolated.
+ */
+export declare function selectEntry<P>(entries: ReadonlyArray<RegistryEntry<P>>, binding: Binding, schema: OntologySchema | null, type?: string): Match<P> | null;
+export type RenderDecision = {
+    render: "widget";
+} | {
+    render: "empty";
+} | {
+    render: "error";
+};
+/**
+ * Fail-closed per blast radius (§14.8). Given whether a widget matched AND
+ * whether its data resolved, decide how the slot renders:
+ *   - matched + data ok        → render the widget
+ *   - failed, optional slot    → soft-empty (render nothing)
+ *   - failed, structural slot  → visible error (MUST NOT silently vanish)
+ * The operator's raw `type`/`kind` is never interpolated in any branch.
+ */
+export declare function decideRender(block: Pick<Block, "importance">, matched: boolean, dataOk: boolean): RenderDecision;

package/components/renderer/dispatch.ts

@@ -0,0 +1,99 @@
+/**
+ * Widget dispatcher — tester/priority, not a flat map (D4, JSONForms model).
+ *
+ * Generalises the admin app's XSS-hardened layout registry
+ * (`admin/src/lib/renderer-layouts/resolve.ts`) from form-row LayoutKeys to
+ * widget `kind`s. Each entry carries a `tester(binding, schema) → score`; the
+ * highest score wins. A more specific tester (e.g. "list of `occurrence`")
+ * outranks the generic "any list" and overrides one widget for one entity
+ * WITHOUT editing the catalog (open/closed).
+ *
+ * The ranking core here is generic over the payload `P` so it stays
+ * component-free and fully unit/mutation-testable; the real registry (73b)
+ * instantiates it with Svelte `Component`s.
+ *
+ * TH-08 (R-SEC-07) preserved: the resolved `key` is a known-good literal from
+ * the matched entry — the operator's raw `binding.kind`/`entity`/block `type`
+ * is NEVER returned as the key, so it never reaches `class`/`data-*`/`style`.
+ */
+import type { Binding, Block, OntologySchema } from "./types";
+
+/** Tester sentinel — "this widget does not apply to this binding". */
+export const NOT_APPLICABLE = -1;
+
+/**
+ * A tester ranks a registry entry against a binding (+ optional schema and the
+ * block's authoring `type` hint). JSONForms model: testers see the full
+ * element, so a type-specific widget (e.g. `filter-bar`) can out-rank the
+ * generic kind widget (`entity-list`) for the SAME `binding.kind` without
+ * editing the kind entry. `type` is UNTRUSTED — it only influences ranking; the
+ * resolved `key` still comes from the matched entry (TH-08), never from `type`.
+ */
+export type WidgetTester = (
+  binding: Binding,
+  schema: OntologySchema | null,
+  type?: string,
+) => number;
+
+export interface RegistryEntry<P> {
+  /** Known-good literal. Safe to render as `data-widget={key}` (TH-08). */
+  key: string;
+  payload: P;
+  tester: WidgetTester;
+}
+
+export interface Match<P> {
+  key: string;
+  payload: P;
+}
+
+/**
+ * Run every tester against the binding; the highest applicable score wins.
+ * Ties resolve to the first-registered entry (stable, deterministic). Returns
+ * `null` when no tester is applicable — the caller fails closed per blast
+ * radius; nothing about the binding is interpolated.
+ */
+export function selectEntry<P>(
+  entries: ReadonlyArray<RegistryEntry<P>>,
+  binding: Binding,
+  schema: OntologySchema | null,
+  type?: string,
+): Match<P> | null {
+  let best: RegistryEntry<P> | null = null;
+  let bestScore: number = NOT_APPLICABLE;
+  for (const entry of entries) {
+    const score = entry.tester(binding, schema, type);
+    // Strictly greater → first registered wins ties.
+    if (score > bestScore) {
+      bestScore = score;
+      best = entry;
+    }
+  }
+  if (best === null) return null;
+  // TH-08: key from the matched entry, never from the binding/block.
+  return { key: best.key, payload: best.payload };
+}
+
+export type RenderDecision =
+  | { render: "widget" }
+  | { render: "empty" }
+  | { render: "error" };
+
+/**
+ * Fail-closed per blast radius (§14.8). Given whether a widget matched AND
+ * whether its data resolved, decide how the slot renders:
+ *   - matched + data ok        → render the widget
+ *   - failed, optional slot    → soft-empty (render nothing)
+ *   - failed, structural slot  → visible error (MUST NOT silently vanish)
+ * The operator's raw `type`/`kind` is never interpolated in any branch.
+ */
+export function decideRender(
+  block: Pick<Block, "importance">,
+  matched: boolean,
+  dataOk: boolean,
+): RenderDecision {
+  if (matched && dataOk) return { render: "widget" };
+  return block.importance === "structural"
+    ? { render: "error" }
+    : { render: "empty" };
+}

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,101 @@
+/**
+ * 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 EChartWidget from "./EChartWidget.svelte";
+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),
+  byTypeOnKind("chart", "aggregate", EChartWidget),
+];
+
+/**
+ * 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>;