@foir/sdk 0.7.0 → 0.9.0

package/dist/content/content-renderer.d.ts

@@ -1,47 +1,113 @@
 /**
  * createContentRenderer — the generic content-dispatch primitive.
  *
- * It does NOT know any concrete block types. Given a registry that maps each
- * block `__typename` to a component, it renders a `flexible` field's block
- * array: looks each block up by `__typename`, renders unknown types as null,
- * keys by the block `_id`, assigns LCP `priority` to the first block that
- * actually renders, and threads a consumer-defined `Ctx` to every component.
+ * It does NOT know any concrete item types. Given a registry that maps each
+ * entry `__typename` to a component, it renders a prose flow's entries (or a
+ * plain item array): looks each entry up by `__typename`, renders unknown
+ * types as null, keys by the entry `_key`/`_id` where one is present, assigns
+ * LCP `priority` to the first entry that actually renders, and threads a
+ * consumer-defined `Ctx` to every component.
+ *
+ * Passage entries — the flow's text — are not registry-dispatched: a run of
+ * consecutive passages renders as ONE unit through `options.passageRun` (or
+ * the SDK's `PassageList` with provider tokens when none is supplied), so
+ * prose reads as a single body with shared list structure.
  *
  * The "switch" is a typed object lookup. Exhaustiveness is enforced where the
- * registry is BUILT — against the exhaustive `BlockRegistry` type the codegen
- * plugin (EID-92) generates per project, so omitting a block type is a compile
+ * registry is BUILT — against the exhaustive `ItemRegistry` type the codegen
+ * plugin (EID-92) generates per project, so omitting an item type is a compile
  * error there, not a runtime surprise here. The consumer can supply different
  * registries per surface (e.g. web vs email).
+ *
+ * # On the word
+ *
+ * A prose field holds ENTRIES. A modeller may name the field `blocks`,
+ * `sections`, `modules` or anything else, and this renderer must not care:
+ * dispatch is on `__typename` and never on a field name. The `Block*` spellings
+ * below are deprecated aliases kept so existing consumers compile — see
+ * TTS-1391.
  */
 import { type ReactNode } from 'react';
-/** Minimal shape every block in a `flexible` field carries. */
-export interface BlockLike {
+import { type PassageLike } from './richtext';
+/** Minimal shape every entry in a prose flow carries. */
+export interface ItemLike {
     __typename: string;
     _id?: string | null;
+    _key?: string | null;
 }
-/** Props a block component receives from the content renderer. */
-export interface BlockComponentProps<TBlock, TCtx = unknown> {
-    block: TBlock;
+/** Props an item component receives from the content renderer. */
+export interface ItemComponentProps<TItem, TCtx = unknown> {
+    item: TItem;
+    /**
+     * The same value as `item`.
+     *
+     * @deprecated Use `item`. Kept so components scaffolded before TTS-1391
+     * keep compiling; it is passed on every render and will be removed in a
+     * future major.
+     */
+    block: TItem;
     /** Consumer-defined render context (host product, locale, etc.). */
     ctx: TCtx;
-    /** True only for the first block that renders — the LCP candidate. */
+    /** True only for the first item that renders — the LCP candidate. */
     priority: boolean;
 }
-/** A component that renders one block type. */
-export type BlockComponent<TBlock, TCtx = unknown> = (props: BlockComponentProps<TBlock, TCtx>) => ReactNode;
+/** A component that renders one item type. */
+export type ItemComponent<TItem, TCtx = unknown> = (props: ItemComponentProps<TItem, TCtx>) => ReactNode;
 /**
- * A registry mapping `__typename` → block component. In practice this is the
- * exhaustive `BlockRegistry` type the codegen plugin emits for the project;
+ * A registry mapping `__typename` → item component. In practice this is the
+ * exhaustive `ItemRegistry` type the codegen plugin emits for the project;
  * here it's the structural lower bound the renderer needs.
  */
-export type BlockRegistry<TCtx = unknown> = Record<string, BlockComponent<any, TCtx>>;
-export interface ContentRendererProps<TCtx> {
-    blocks: readonly BlockLike[] | null | undefined;
-    /** Consumer-defined context passed to every block component. */
+export type ItemRegistry<TCtx = unknown> = Record<string, ItemComponent<any, TCtx>>;
+/** A prose flow's projection wrapper: the field value carrying `entries`. */
+export interface EntriesLike {
+    entries?: readonly (ItemLike | null | undefined)[] | null;
+}
+/**
+ * The prose field's entries — the projection wrapper (`{ entries }`), or a
+ * plain array — plus the context threaded to every component.
+ *
+ * `items` is canonical. `blocks` is the pre-TTS-1391 spelling and still
+ * accepted; passing both is a type error rather than a silent precedence rule,
+ * because a caller who set both cannot be told which one this honoured.
+ */
+export type ContentRendererProps<TCtx> = {
+    /** Consumer-defined context passed to every item component. */
+    ctx: TCtx;
+} & ({
+    items: readonly (ItemLike | null | undefined)[] | EntriesLike | null | undefined;
+    blocks?: never;
+} | {
+    /** @deprecated Use `items`. */
+    blocks: readonly (ItemLike | null | undefined)[] | EntriesLike | null | undefined;
+    items?: never;
+});
+/** Props the passage-run component receives. */
+export interface PassageRunProps<TCtx = unknown> {
+    /** The consecutive passage entries of this run, in document order. */
+    passages: PassageLike[];
+    /** Consumer-defined render context. */
     ctx: TCtx;
+    /** True only when the run is the flow's first rendered unit. */
+    priority: boolean;
+}
+export interface ContentRendererOptions<TCtx = unknown> {
+    /**
+     * Renders a run of consecutive passage entries. Defaults to the SDK's
+     * `PassageList` (typography tokens via `RichTextTypographyProvider`).
+     */
+    passageRun?: (props: PassageRunProps<TCtx>) => ReactNode;
 }
 /**
- * Build a `<ContentRenderer>` bound to a block registry. Returns a component
- * that takes the `flexible` field's `blocks` array plus a `ctx`.
+ * Build a `<ContentRenderer>` bound to an item registry. Returns a component
+ * that takes the prose field's value (or a plain entry array) plus a `ctx`.
  */
-export declare function createContentRenderer<TCtx = unknown>(registry: BlockRegistry<TCtx>): (props: ContentRendererProps<TCtx>) => ReactNode;
+export declare function createContentRenderer<TCtx = unknown>(registry: ItemRegistry<TCtx>, options?: ContentRendererOptions<TCtx>): (props: ContentRendererProps<TCtx>) => ReactNode;
+/** @deprecated Renamed to {@link ItemLike}. */
+export type BlockLike = ItemLike;
+/** @deprecated Renamed to {@link ItemComponentProps}. */
+export type BlockComponentProps<TBlock, TCtx = unknown> = ItemComponentProps<TBlock, TCtx>;
+/** @deprecated Renamed to {@link ItemComponent}. */
+export type BlockComponent<TBlock, TCtx = unknown> = ItemComponent<TBlock, TCtx>;
+/** @deprecated Renamed to {@link ItemRegistry}. */
+export type BlockRegistry<TCtx = unknown> = ItemRegistry<TCtx>;

package/dist/content/index.d.ts

@@ -1,12 +1,18 @@
 /**
  * `@foir/sdk/content` — generic content-rendering primitives.
  *
- * Ships ONLY the framework-agnostic primitives: the block-dispatch renderer
- * and a Lexical richtext renderer with injected typography tokens. Concrete
- * block components, host/Shopify context, and layout systems stay app-side.
- * `react` is a peer dependency.
+ * Ships ONLY the framework-agnostic primitives: the entry-dispatch renderer
+ * and a prose renderer (passages with spans, marks and markDefs) with
+ * injected typography tokens. Concrete item components, host/Shopify
+ * context, and layout systems stay app-side. `react` is a peer dependency.
  */
 export { createContentRenderer } from './content-renderer';
-export type { BlockLike, BlockComponent, BlockComponentProps, BlockRegistry, ContentRendererProps, } from './content-renderer';
-export { RichTextRenderer, RichTextTypographyProvider, useRichTextTypography, } from './richtext';
-export type { RichTextRendererProps, TypographyToken, } from './richtext';
+export type { ItemLike, EntriesLike, ItemComponent, ItemComponentProps, ItemRegistry, ContentRendererProps, ContentRendererOptions, PassageRunProps, } from './content-renderer';
+/**
+ * Pre-TTS-1391 spellings. `Block` was one project's name for a flexible field,
+ * never a platform concept; these are kept so existing consumers compile and
+ * will be removed in a future major.
+ */
+export type { BlockLike, BlockComponent, BlockComponentProps, BlockRegistry, } from './content-renderer';
+export { RichTextRenderer, RichTextTypographyProvider, useRichTextTypography, PassageList, passagesOf, isPassageEntry, safeHref, } from './richtext';
+export type { RichTextRendererProps, PassageListProps, TypographyToken, ProseValueLike, PassageLike, ProseSpanLike, } from './richtext';

package/dist/content/richtext.d.ts

@@ -1,23 +1,30 @@
 /**
- * RichTextRenderer — render a Foir richtext field (a Lexical EditorState) with
- * per-paragraph typography tokens applied as inline styles.
+ * RichTextRenderer — render a Foir prose value (a flow of passages) with
+ * per-passage typography tokens applied as inline styles.
  *
  * The design-token dependency is INJECTED, not imported from an app: pass the
  * resolved `typography` token array as a prop, or provide it once via
  * `<RichTextTypographyProvider>`. With no tokens the structure still renders
- * (fallback tag, no inline typography), and a doc-less value falls back to its
- * `html` projection. No `@foir`-app imports.
+ * (fallback tag, no inline typography), and a value without a typed `entries`
+ * projection falls back to its stored flow (`json`) and then its `html`
+ * projection. No `@foir`-app imports.
  *
- * Token semantics:
- *   - `token.tag` (paragraph / h1–h6 / blockquote) controls the rendered HTML
- *     element and wins over the Lexical heading `tag` when both are present.
- *   - Paragraph `format` ('left'|'center'|'right'|'justify') → text-align.
- *   - Text-node `format` bits → inline emphasis: bold(1) italic(2)
- *     strikethrough(4) underline(8) code(16).
+ * Passage semantics:
+ *   - `kind` (paragraph / h1–h6 / quote / code) picks the HTML element.
+ *   - `token` names a typography token; its resolved CSS is inlined and the
+ *     token's `tag` wins over the kind's element when both are present.
+ *   - `align` maps to text-align on the rendered element.
+ *   - `list` + `level` flatten list membership onto the passage; consecutive
+ *     list passages regroup into <ul>/<ol> with nesting rebuilt from `level`.
+ *   - Span marks are the eight decorations (bold, italic, underline,
+ *     strikethrough, code, subscript, superscript, highlight) or the `_key`
+ *     of a markDef on the same passage (links, scheme-checked through
+ *     `safeHref`).
+ *   - A soft line break is `"\n"` inside a span's text.
  */
 import { type ReactNode, type JSX } from 'react';
 /**
- * safeHref allow-lists link schemes so stored richtext can't smuggle a
+ * safeHref allow-lists link schemes so stored prose can't smuggle a
  * `javascript:` (or `data:`/`vbscript:`) URL that executes on click (EID-207).
  * Relative URLs, anchors, and the http(s)/mailto/tel schemes pass; anything
  * else collapses to '#'. Editors are not fully trusted, so this runs on the
@@ -26,7 +33,7 @@ import { type ReactNode, type JSX } from 'react';
 export declare function safeHref(url: string | undefined): string;
 /** A resolved typography token from the project's design tokens. */
 export interface TypographyToken {
-    /** Token key referenced by a Lexical node's `style`. */
+    /** Token key referenced by a passage's `token`. */
     name: string;
     /** Rendered HTML element (paragraph / h1–h6 / blockquote). */
     tag?: string;
@@ -41,8 +48,8 @@ export interface TypographyToken {
 }
 /**
  * Provide the project's resolved typography tokens to every nested
- * `<RichTextRenderer>` so callers don't thread them through each usage. A
- * `tokens` prop on the renderer still takes precedence.
+ * `<RichTextRenderer>` / `<PassageList>` so callers don't thread them through
+ * each usage. A `tokens` prop on the renderer still takes precedence.
  */
 export declare function RichTextTypographyProvider({ tokens, children, }: {
     tokens: TypographyToken[];
@@ -50,12 +57,40 @@ export declare function RichTextTypographyProvider({ tokens, children, }: {
 }): import("react/jsx-runtime").JSX.Element;
 /** Read the injected typography tokens (null when no provider is mounted). */
 export declare function useRichTextTypography(): TypographyToken[] | null;
-interface RichtextValueLike {
+export interface ProseSpanLike {
+    text?: string | null;
+    marks?: ReadonlyArray<string | null> | null;
+}
+export interface PassageLike {
+    __typename?: string;
+    _type?: string;
+    _key?: string | null;
+    kind?: string | null;
+    token?: string | null;
+    align?: string | null;
+    list?: string | null;
+    level?: number | null;
+    language?: string | null;
+    markDefs?: unknown;
+    spans?: ReadonlyArray<ProseSpanLike | null> | null;
+}
+export interface ProseValueLike {
     html?: string | null;
     json?: unknown;
+    entries?: ReadonlyArray<PassageLike | null> | null;
 }
+/** True for a passage entry from either the typed projection
+ * (`__typename: "Passage"`) or the stored flow (`_type: "passage"`). */
+export declare function isPassageEntry(entry: unknown): entry is PassageLike;
+/**
+ * Extract the renderable passages from a prose value. Prefers the typed
+ * `entries` projection; falls back to walking the stored flow (`json`).
+ * Embed entries are skipped — a prose *value* position renders text; embeds
+ * in list positions render through the consumer's content renderer instead.
+ */
+export declare function passagesOf(value: ProseValueLike | null | undefined): PassageLike[];
 export interface RichTextRendererProps {
-    value: RichtextValueLike | null | undefined;
+    value: ProseValueLike | null | undefined;
     className?: string;
     /**
      * Resolved typography tokens. Overrides any provided via
@@ -63,8 +98,21 @@ export interface RichTextRendererProps {
      * with `fallbackTag` and no inline typography.
      */
     tokens?: TypographyToken[];
-    /** Tag used for any paragraph with no token style and no Lexical tag. */
+    /** Tag used for a paragraph passage with no token tag. */
     fallbackTag?: keyof JSX.IntrinsicElements;
 }
 export declare function RichTextRenderer({ value, className, tokens, fallbackTag, }: RichTextRendererProps): import("react/jsx-runtime").JSX.Element | null;
-export {};
+export interface PassageListProps {
+    passages: ReadonlyArray<PassageLike>;
+    /** Resolved typography tokens; falls back to the provider's. */
+    tokens?: TypographyToken[];
+    /** Tag used for a paragraph passage with no token tag. */
+    fallbackTag?: keyof JSX.IntrinsicElements;
+}
+/**
+ * Render a run of passages: consecutive list passages regroup into (nested)
+ * <ul>/<ol>, everything else renders as its own element. Used by
+ * `RichTextRenderer` for prose field values and by `createContentRenderer`
+ * for passage runs inside a flow's entries.
+ */
+export declare function PassageList({ passages, tokens, fallbackTag, }: PassageListProps): import("react/jsx-runtime").JSX.Element;