@proulr/sdui-contract 0.1.16 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proulr/sdui-contract",
-  "version": "0.1.16",
+  "version": "0.1.19",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/sdui-contract-types.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decodeSduiScreenWire,
+  isSduiAvatarWireProps,
+  isSduiContentImageWireProps,
+  isSduiIconButtonWireProps,
+  isSduiRowOverflowMenuWireProps,
+  isSduiRowTemplateEntryWireProps,
+  isSduiRowTemplateSetWireProps,
+  isSduiRowTemplateWireProps,
+  isSduiSelectedTrue,
+  isSduiVideoWireProps,
+} from './index';
+import type { SduiBlockWire } from './sdui-contract-types';
+
+const templateBlock: SduiBlockWire = {
+  id: '0.row_template.0.0',
+  type: 'column',
+  props: { action_id: 'open_post_{{item.id}}' },
+  children: [
+    { id: '0.row_template.0.0.0', type: 'text', props: { text: '{{item.author.name}}' }, children: [] },
+  ],
+};
+
+describe('isSduiRowTemplateWireProps', () => {
+  it('accepts host props carrying a row template', () => {
+    const props: Record<string, unknown> = {
+      data_ref: 'social.posts',
+      row_template: [{ id: '0.row_template.0.0', type: 'text', props: { text: '{{item.body}}' } }],
+      item_key: 'id',
+      section: 'posts',
+    };
+    expect(isSduiRowTemplateWireProps(props)).toBe(true);
+  });
+
+  it('rejects props without template or without item_key', () => {
+    expect(isSduiRowTemplateWireProps(undefined)).toBe(false);
+    expect(isSduiRowTemplateWireProps({})).toBe(false);
+    expect(isSduiRowTemplateWireProps({ row_template: [] })).toBe(false);
+    expect(isSduiRowTemplateWireProps({ row_template: [], item_key: '' })).toBe(false);
+    expect(isSduiRowTemplateWireProps({ row_template: 'nope', item_key: 'id' })).toBe(false);
+  });
+});
+
+describe('multi-template hosts (row_templates)', () => {
+  const entry = (itemKey = 'id', section?: string): Record<string, unknown> => ({
+    row_template: [{ id: 't', type: 'text', props: { text: 'x' } }],
+    item_key: itemKey,
+    ...(section ? { section } : {}),
+  });
+
+  it('isSduiRowTemplateEntryWireProps validates one ordered template', () => {
+    expect(isSduiRowTemplateEntryWireProps(entry('id', 'posts'))).toBe(true);
+    expect(isSduiRowTemplateEntryWireProps(entry('post.id'))).toBe(true);
+    expect(isSduiRowTemplateEntryWireProps(null)).toBe(false);
+    expect(isSduiRowTemplateEntryWireProps({ row_template: [] })).toBe(false);
+    expect(isSduiRowTemplateEntryWireProps({ row_template: [], item_key: '' })).toBe(false);
+    expect(isSduiRowTemplateEntryWireProps({ row_template: [], item_key: 'id', section: 3 })).toBe(
+      false,
+    );
+  });
+
+  it('isSduiRowTemplateSetWireProps accepts single hosts (no row_templates) and valid sets', () => {
+    expect(
+      isSduiRowTemplateSetWireProps({ row_template: [], item_key: 'id' }),
+    ).toBe(true);
+    expect(
+      isSduiRowTemplateSetWireProps({
+        row_template: [],
+        item_key: 'id',
+        row_templates: [entry(), entry('comment_id', 'comments')],
+      }),
+    ).toBe(true);
+  });
+
+  it('isSduiRowTemplateSetWireProps rejects malformed sets', () => {
+    expect(
+      isSduiRowTemplateSetWireProps({ row_template: [], item_key: 'id', row_templates: [] }),
+    ).toBe(false);
+    expect(
+      isSduiRowTemplateSetWireProps({
+        row_template: [],
+        item_key: 'id',
+        row_templates: [{ row_template: 'nope', item_key: 'id' }],
+      }),
+    ).toBe(false);
+    expect(isSduiRowTemplateSetWireProps({ row_templates: [entry()] })).toBe(false);
+  });
+
+  it('row_templates survives the codec untouched (ordered, snake_case entries)', () => {
+    const screen = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'social.feed',
+      blocks: [
+        {
+          id: 'feed',
+          type: 'social_post_feed',
+          props: {
+            row_template: [templateBlock],
+            item_key: 'id',
+            row_templates: [entry('id', 'posts'), entry('comment_id', 'comments')],
+          },
+          children: [],
+        },
+      ],
+    });
+    const props = screen.blocks[0].props;
+    expect(props.item_key).toBe('id');
+    expect(props.row_template).toEqual([templateBlock]);
+    expect(props.row_templates).toEqual([entry('id', 'posts'), entry('comment_id', 'comments')]);
+  });
+});
+
+describe('video block wire props', () => {
+  it('isSduiVideoWireProps accepts string path (binding allowed), rejects others', () => {
+    expect(isSduiVideoWireProps({ path: '{{item.video_path}}', aspect: 'video' })).toBe(true);
+    expect(isSduiVideoWireProps({ path: 'clips/2026/a.mp4', poster_path: 'clips/2026/a.jpg' })).toBe(
+      true,
+    );
+    expect(isSduiVideoWireProps({})).toBe(false);
+    expect(isSduiVideoWireProps({ poster_path: 'a.jpg' })).toBe(false);
+    expect(isSduiVideoWireProps(undefined)).toBe(false);
+  });
+});
+
+describe('row_overflow_menu block wire props', () => {
+  it('isSduiRowOverflowMenuWireProps requires the actions array', () => {
+    expect(
+      isSduiRowOverflowMenuWireProps({
+        actions: [{ action_id: 'delete_{{item.id}}', label: 'Excluir', destructive: true }],
+        icon: 'overflow',
+      }),
+    ).toBe(true);
+    expect(isSduiRowOverflowMenuWireProps({ actions: [] })).toBe(true);
+    expect(isSduiRowOverflowMenuWireProps({ icon: 'overflow' })).toBe(false);
+    expect(isSduiRowOverflowMenuWireProps(undefined)).toBe(false);
+  });
+});
+
+describe('row_template wire through the codec', () => {
+  it('passes row_template props through untouched (blocks without template unchanged)', () => {
+    const templateBlock: SduiBlockWire = {
+      id: '0.row_template.0.0',
+      type: 'column',
+      props: { action_id: 'open_post_{{item.id}}' },
+      children: [
+        { id: '0.row_template.0.0.0', type: 'text', props: { text: '{{item.author.name}}' }, children: [] },
+      ],
+    };
+    const screen = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'social.feed',
+      blocks: [
+        {
+          id: 'feed',
+          type: 'social_post_feed',
+          props: { data_ref: 'social.posts', row_template: [templateBlock], item_key: 'id' },
+          children: [],
+        },
+        { id: 'plain', type: 'text', props: { text: 'hello' }, children: [] },
+      ],
+    });
+
+    const host = screen.blocks[0];
+    expect(host.props.row_template).toEqual([templateBlock]);
+    expect(host.props.item_key).toBe('id');
+    // Nested wire blocks keep their shape (codec does not recurse into props).
+    const nested = (host.props.row_template as SduiBlockWire[])[0];
+    expect(nested.children?.[0]?.props?.text).toBe('{{item.author.name}}');
+    expect(screen.blocks[1].props).toEqual({ text: 'hello' });
+  });
+});
+
+describe('media/feed row block wire props', () => {
+  it('isSduiContentImageWireProps accepts string path (binding allowed), rejects others', () => {
+    expect(isSduiContentImageWireProps({ path: '{{item.media_path}}', aspect: 'square' })).toBe(true);
+    expect(isSduiContentImageWireProps({ path: 'feeds/2026/photo.jpg' })).toBe(true);
+    expect(isSduiContentImageWireProps({})).toBe(false);
+    expect(isSduiContentImageWireProps({ width: 100 })).toBe(false);
+    expect(isSduiContentImageWireProps(undefined)).toBe(false);
+  });
+
+  it('isSduiAvatarWireProps accepts path, name or initials', () => {
+    expect(isSduiAvatarWireProps({ path: '{{item.avatar_path}}' })).toBe(true);
+    expect(isSduiAvatarWireProps({ name: '{{item.author.name}}', size: 'md' })).toBe(true);
+    expect(isSduiAvatarWireProps({ initials: 'AB' })).toBe(true);
+    expect(isSduiAvatarWireProps({})).toBe(false);
+    expect(isSduiAvatarWireProps({ size: 'sm' })).toBe(false);
+    expect(isSduiAvatarWireProps(undefined)).toBe(false);
+  });
+
+  it('isSduiIconButtonWireProps requires string icon', () => {
+    expect(isSduiIconButtonWireProps({ icon: 'heart', selected: '{{item.liked_by_me}}' })).toBe(true);
+    expect(isSduiIconButtonWireProps({ icon: 'heart', selected: false })).toBe(true);
+    expect(isSduiIconButtonWireProps({ action_id: 'like' })).toBe(false);
+    expect(isSduiIconButtonWireProps(undefined)).toBe(false);
+  });
+
+  it('isSduiSelectedTrue implements the stringly-typed binding rule', () => {
+    expect(isSduiSelectedTrue(true)).toBe(true);
+    expect(isSduiSelectedTrue('true')).toBe(true);
+    expect(isSduiSelectedTrue(' True ')).toBe(true);
+    expect(isSduiSelectedTrue('false')).toBe(false);
+    expect(isSduiSelectedTrue(false)).toBe(false);
+    expect(isSduiSelectedTrue(undefined)).toBe(false);
+    expect(isSduiSelectedTrue(1)).toBe(false);
+    expect(isSduiSelectedTrue('yes')).toBe(false);
+  });
+
+  it('selected/media props survive the codec untouched (block props never camelCased)', () => {
+    const screen = decodeSduiScreenWire({
+      schema_version: 1,
+      screen_id: 'social.feed',
+      blocks: [
+        {
+          id: 'row',
+          type: 'column',
+          props: {},
+          children: [
+            {
+              id: 'row.img',
+              type: 'content_image',
+              props: { path: '{{item.media_path}}', aspect: 'square', corner: 'cornerMedium', blur_fill: false },
+            },
+            {
+              id: 'row.avatar',
+              type: 'avatar',
+              props: { path: '{{item.author.avatar_path}}', name: '{{item.author.name}}', size: 'sm' },
+            },
+            {
+              id: 'row.like',
+              type: 'icon_button',
+              props: {
+                icon: 'heart',
+                selected_icon: 'heart-filled',
+                action_id: 'like_post_{{item.id}}',
+                selected: 'true',
+              },
+            },
+          ],
+        },
+      ],
+    });
+
+    const [image, avatar, like] = screen.blocks[0].children;
+    expect(image.type).toBe('content_image');
+    expect(image.props).toEqual({
+      path: '{{item.media_path}}',
+      aspect: 'square',
+      corner: 'cornerMedium',
+      blur_fill: false,
+    });
+    expect(avatar.props.name).toBe('{{item.author.name}}');
+    expect(like.props.selected).toBe('true');
+    expect(isSduiSelectedTrue(like.props.selected)).toBe(true);
+  });
+});

package/src/sdui-contract-types.ts

@@ -25,6 +25,331 @@ export type SduiBlockWire = {
   children?: SduiBlockWire[];
 };
 
+/**
+ * Row template hoisted onto a host hybrid block's props by `compileBdcToWire`
+ * (BDC `<ListRowTemplate>` — authoring lives in proulr-sdui-components).
+ *
+ * Wire shape (snake_case, inside the host block's `props`):
+ * ```
+ * {
+ *   row_template: SduiBlockWire[],  // compiled subtree roots of the template
+ *   item_key: string,               // identifier field of each live item, e.g. 'id' (dot path allowed)
+ *   section?: string,               // optional section marker for multi-section feeds
+ * }
+ * ```
+ *
+ * Binding syntax inside template props: `{{item.field}}` / `{{item.a.b}}`
+ * (dot path against each live item; `{{index}}` is NOT supported). Any string
+ * prop value — including action ids and nested action payloads — may embed
+ * placeholders; the app resolves them at materialize time
+ * (`materializeRowTemplate` in `@proulr/sdui-components/renderer`).
+ * Unresolved paths render as empty string.
+ */
+export type SduiRowTemplateWireProps = {
+  row_template: SduiBlockWire[];
+  item_key: string;
+  section?: string;
+};
+
+/**
+ * Type guard for block props carrying a `row_template` (wire/props stay uncamelCased by the codec). */
+export function isSduiRowTemplateWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiRowTemplateWireProps {
+  return (
+    !!props &&
+    Array.isArray(props.row_template) &&
+    typeof props.item_key === 'string' &&
+    props.item_key.length > 0
+  );
+}
+
+/**
+ * One ordered template of a **multi-template host** (BDC: several
+ * `<ListRowTemplate>` children, each carrying its own `item_key`/`section`).
+ * Shape is identical to `SduiRowTemplateWireProps` — it is one entry of the
+ * host's `props.row_templates` array.
+ */
+export type SduiRowTemplateEntryWireProps = {
+  row_template: SduiBlockWire[];
+  item_key: string;
+  section?: string;
+};
+
+/**
+ * Wire shape for a host block compiled from **multiple** `<ListRowTemplate>`
+ * children (see `hoistRowTemplates` in `compileBdcToWire`):
+ * ```
+ * {
+ *   row_template: SduiBlockWire[],          // ALWAYS the FIRST template (backward compat)
+ *   item_key: string,                       // item_key of the first template
+ *   section?: string,                       // section of the first template (when set)
+ *   row_templates: SduiRowTemplateEntryWireProps[],  // ordered, one entry per template
+ * }
+ * ```
+ * Single-template hosts keep the exact `SduiRowTemplateWireProps` shape —
+ * `row_templates` only appears when the host has two or more templates, so
+ * existing readers (`readSduiRowTemplate`) keep working unchanged. New
+ * readers use `readSduiRowTemplates` (`@proulr/sdui-components/renderer`).
+ */
+export type SduiRowTemplateSetWireProps = SduiRowTemplateWireProps & {
+  row_templates?: SduiRowTemplateEntryWireProps[];
+};
+
+/** Type guard for one entry of `row_templates`. */
+export function isSduiRowTemplateEntryWireProps(
+  value: unknown,
+): value is SduiRowTemplateEntryWireProps {
+  if (!value || typeof value !== 'object') return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    Array.isArray(entry.row_template) &&
+    typeof entry.item_key === 'string' &&
+    entry.item_key.length > 0 &&
+    (entry.section === undefined || typeof entry.section === 'string')
+  );
+}
+
+/**
+ * Type guard for host props carrying an ordered template set. A plain
+ * single-template host also passes (`row_templates` optional); entries, when
+ * present, must each be a valid template.
+ */
+export function isSduiRowTemplateSetWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiRowTemplateSetWireProps {
+  if (!isSduiRowTemplateWireProps(props)) return false;
+  const set = props as SduiRowTemplateSetWireProps;
+  return (
+    set.row_templates === undefined ||
+    (Array.isArray(set.row_templates) &&
+      set.row_templates.length > 0 &&
+      set.row_templates.every(isSduiRowTemplateEntryWireProps))
+  );
+}
+
+// ─── Media / feed row blocks (generic wire blocks, snake_case) ────────────
+//
+// Block `props` pass through the codec untouched (see `mapBlockWire`), so the
+// wire shape below is also the domain shape for these blocks. Values inside
+// `path` / `selected` may embed row-template bindings (`{{item.field}}`); the
+// app resolves them at materialize time BEFORE the block renders. The media
+// PATH is data-driven; turning it into a fetchable URL is a generic
+// app-provided capability (`SduiMediaResolver` in
+// `@proulr/sdui-components/renderer`) — never product logic in the lib.
+
+/** Aspect tokens for content images (ratio values live in the renderer lib). */
+export type SduiMediaAspectToken = 'square' | 'portrait' | 'story' | 'video' | 'wide';
+
+/** Resize tokens for content images (maps to RN resizeMode in the renderer). */
+export type SduiMediaFitToken = 'cover' | 'contain';
+
+/** Size tokens for avatars (px values live in the renderer lib). */
+export type SduiAvatarSizeToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * State-driven icon flag (stringly-typed binding rule): `selected` is either a
+ * real boolean OR a string produced by row-template materialization —
+ * `{{item.liked_by_me}}` renders booleans as `'true'` / `'false'` strings.
+ * `isSduiSelectedTrue` is the single coercion contract: `true` and the string
+ * `'true'` (case-insensitive, trimmed) mean selected; everything else
+ * (`'false'`, `false`, missing, any other string) means default.
+ */
+export type SduiSelectedFlag = string | boolean;
+
+/** Coercion contract for `selected`-style stringly-typed wire flags. */
+export function isSduiSelectedTrue(value: unknown): boolean {
+  if (value === true) return true;
+  return typeof value === 'string' && value.trim().toLowerCase() === 'true';
+}
+
+/**
+ * Wire shape for block `content_image` (BDC `<ContentImage>`):
+ * ```
+ * {
+ *   path: string,               // storage path; may contain {{item.*}} binding (required)
+ *   width?: number, height?: number,
+ *   aspect?: 'square'|'portrait'|'story'|'video'|'wide',
+ *   corner?: ShapeToken,        // default cornerMedium
+ *   fit?: 'cover'|'contain',    // default cover
+ *   blur_fill?: boolean,        // fill frame behind `contain` media
+ *   test_id?: string
+ * }
+ * ```
+ * Renderer contract: empty `path` or no app `SduiMediaResolver` → renders null
+ * (never a product fallback URL).
+ */
+export type SduiContentImageWireProps = {
+  path: string;
+  width?: number;
+  height?: number;
+  aspect?: SduiMediaAspectToken;
+  corner?: ShapeToken;
+  fit?: SduiMediaFitToken;
+  blur_fill?: boolean;
+  test_id?: string;
+};
+
+/** Type guard for `content_image` block props. */
+export function isSduiContentImageWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiContentImageWireProps {
+  return !!props && typeof props.path === 'string';
+}
+
+/**
+ * Wire shape for block `avatar` (BDC `<Avatar>`):
+ * ```
+ * {
+ *   path?: string,              // storage path; may contain {{item.*}} binding
+ *   name?: string,              // display name — initials derived when no image
+ *   initials?: string,          // explicit initials (override derivation)
+ *   size?: 'xs'|'sm'|'md'|'lg'|'xl',  // default md
+ *   corner?: ShapeToken,        // default cornerFull
+ *   test_id?: string
+ * }
+ * ```
+ * No resolvable image (no path, empty path, or no resolver) falls back to
+ * initials / generic person glyph placeholder — never to a product URL.
+ */
+export type SduiAvatarWireProps = {
+  path?: string;
+  name?: string;
+  initials?: string;
+  size?: SduiAvatarSizeToken;
+  corner?: ShapeToken;
+  test_id?: string;
+};
+
+/** Type guard for `avatar` block props. */
+export function isSduiAvatarWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiAvatarWireProps {
+  if (!props) return false;
+  return (
+    typeof props.path === 'string' ||
+    typeof props.name === 'string' ||
+    typeof props.initials === 'string'
+  );
+}
+
+/**
+ * Wire shape for block `icon_button` (BDC `<IconButton>`):
+ * ```
+ * {
+ *   icon: string,               // AppIconName kebab-case (required)
+ *   selected_icon?: string,     // AppIconName used when selected (e.g. 'heart-filled')
+ *   action_id?: string,         // may contain {{item.*}} binding in row templates
+ *   selected?: string | boolean,// SduiSelectedFlag: '{{item.liked_by_me}}' → 'true'/'false'
+ *   size?: number,              // glyph px (default feedAction)
+ *   color?: ColorToken,         // default tint (unselected)
+ *   selected_color?: ColorToken,// default tint (selected)
+ *   label?: string,             // accessibility label (copy via Rosetta in BFF)
+ *   disabled?: boolean,
+ *   test_id?: string
+ * }
+ * ```
+ * `selected` coercion: `isSduiSelectedTrue` — `'true'`/`true` render filled/tinted
+ * via theme tokens, `'false'`/`false` render default.
+ */
+export type SduiIconButtonWireProps = {
+  icon: string;
+  selected_icon?: string;
+  action_id?: string;
+  selected?: SduiSelectedFlag;
+  size?: number;
+  color?: ColorToken;
+  selected_color?: ColorToken;
+  label?: string;
+  disabled?: boolean;
+  test_id?: string;
+};
+
+/** Type guard for `icon_button` block props. */
+export function isSduiIconButtonWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiIconButtonWireProps {
+  return !!props && typeof props.icon === 'string';
+}
+
+/**
+ * Wire shape for block `video` (BDC `<Video>`):
+ * ```
+ * {
+ *   path: string,               // storage path; may contain {{item.*}} binding (required)
+ *   width?: number, height?: number,
+ *   aspect?: 'square'|'portrait'|'story'|'video'|'wide',
+ *   corner?: ShapeToken,        // default cornerMedium
+ *   fit?: 'cover'|'contain',    // default cover
+ *   poster_path?: string,       // still frame (binding ok); shown when no player plugged
+ *   test_id?: string
+ * }
+ * ```
+ * Renderer contract: `path`/`poster_path` resolve through the SAME app
+ * capability as `content_image` (`SduiMediaResolver`); playback is an
+ * injectable slot (`SduiVideoPlayerProvider` in
+ * `@proulr/sdui-components/renderer`) — the RN player lives in the app.
+ * Without a player the block renders a poster/still FRAME via the resolver;
+ * empty `path` or no resolver → renders null (never a product fallback URL).
+ */
+export type SduiVideoWireProps = {
+  path: string;
+  width?: number;
+  height?: number;
+  aspect?: SduiMediaAspectToken;
+  corner?: ShapeToken;
+  fit?: SduiMediaFitToken;
+  poster_path?: string;
+  test_id?: string;
+};
+
+/** Type guard for `video` block props. */
+export function isSduiVideoWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiVideoWireProps {
+  return !!props && typeof props.path === 'string';
+}
+
+/**
+ * One action entry of block `row_overflow_menu` (nested objects stay
+ * snake_case on the wire — normalized by the BDC factory, not the codec).
+ * `action_id` and `label` may contain `{{item.*}}` bindings (template-safe).
+ */
+export type SduiRowOverflowMenuActionWire = {
+  action_id: string;
+  label: string;
+  /** AppIconName kebab-case (catalog), e.g. 'trash'. */
+  icon?: string;
+  /** Tint the entry with the theme's error token. */
+  destructive?: boolean;
+};
+
+/**
+ * Wire shape for block `row_overflow_menu` (BDC `<RowOverflowMenu>`):
+ * ```
+ * {
+ *   actions: SduiRowOverflowMenuActionWire[],  // ordered menu entries
+ *   icon?: string,                             // trigger AppIconName (default 'overflow')
+ *   test_id?: string
+ * }
+ * ```
+ * All copy is caller-supplied (BFF via Rosetta); the lib never invents
+ * product strings. Renderer opens a Modal-based menu (same mechanism as
+ * `floating_create_menu`) and dispatches `action_id` through `onAction`.
+ */
+export type SduiRowOverflowMenuWireProps = {
+  actions: SduiRowOverflowMenuActionWire[];
+  icon?: string;
+  test_id?: string;
+};
+
+/** Type guard for `row_overflow_menu` block props. */
+export function isSduiRowOverflowMenuWireProps(
+  props: Record<string, unknown> | undefined,
+): props is SduiRowOverflowMenuWireProps {
+  return !!props && Array.isArray(props.actions);
+}
+
 export type SduiHeaderWire = {
   title?: string;
   subtitle?: string;