@riverbankcms/sdk 0.81.0 → 0.84.0

package/README.md

@@ -183,6 +183,10 @@ For detailed testing and verification steps, see [`docs/resilience-verification.
 
 SDK sites that need bespoke appointment booking UI can use the headless booking runtime from `@riverbankcms/sdk/bookings`. See [`docs/headless-booking.md`](./docs/headless-booking.md) for the real `blockOverrides` pattern with an `'appointment-booking'` override, `HeadlessBookingProvider`, `getAppointmentBookingOverrideInput`, and `useHeadlessBookingFlow`.
 
+### Headless Event Registration
+
+SDK sites that need bespoke event registration UI can use the headless event registration runtime from `@riverbankcms/sdk/bookings`. See [`docs/headless-event-registration.md`](./docs/headless-event-registration.md) for the real `blockOverrides` pattern with an `'event-registration'` override, `HeadlessEventRegistrationProvider`, `getEventRegistrationOverrideInput`, and `useHeadlessEventRegistrationFlow`.
+
 ### Server-Side API
 
 ```tsx
@@ -482,6 +486,27 @@ const { entries: allPosts } = await client.getEntries({
 });
 ```
 
+### Ordered Entries by Stable Identifiers
+
+Use `client.getEntriesByIdentifiers()` when structured content stores an ordered
+related-content list and you want the server to resolve only those entries.
+Refs may be entry UUIDs, stable entry identifiers, or route slugs. Missing refs
+are omitted, duplicates collapse to the first occurrence, and results preserve
+the requested order.
+
+```tsx
+const { entries: relatedMeditations } = await client.getEntriesByIdentifiers({
+  siteId: 'your-site-id',
+  contentType: 'meditation',
+  identifiers: ['metta-meditation', 'resting-in-compassion'],
+});
+```
+
+For preview requests, slug resolution prefers draft slugs before published
+slugs. Published requests prefer published slugs. Keep identifier lists small
+(maximum 50 refs per request); for larger lists, use normal paginated
+`getEntries()` queries instead.
+
 ### Parameters
 
 | Parameter | Type | Required | Description |
@@ -1486,6 +1511,8 @@ export function MyComponent() {
 
 Style Builder blocks to match your brand using the Theme Bridge. This provides CSS variables and optional component styles without requiring the full CMS theme system.
 
+For event registration specifically, see [`docs/event-registration-theming.md`](./docs/event-registration-theming.md). Generated SDK sites using `Layout` get a full `ThemeScope` by default; standalone `Page` or `Block` rendering should use `ThemeBridgeProvider` or manual `generateThemeBridgeCss` with a `data-theme-scope="sdk"` wrapper.
+
 ### Quick Start
 
 Import the SDK base stylesheet, then wrap your app with `ThemeBridgeProvider` and define your color tokens:
@@ -2092,6 +2119,9 @@ export default defineConfig({
       category: 'content',
       icon: 'User',
       tags: ['team', 'about'],
+      previewCustomize: {
+        quickFieldPriority: ['name', 'role'],
+      },
       fields: [
         { id: 'name', type: 'text', label: 'Name', required: true, multiline: false },
         { id: 'role', type: 'text', label: 'Role', required: false, multiline: false },
@@ -2103,6 +2133,8 @@ export default defineConfig({
 });
 ```
 
+`previewCustomize` is optional. When present, `quickFieldPriority` must list one or more unique field IDs to consider for compact Preview Customize controls; unlisted fields remain in the full panel.
+
 2. **Create your component** to render the block:
 
 ```tsx
@@ -2365,12 +2397,12 @@ export default defineConfig({
 });
 ```
 
-**Example: Manual Selection (Repeater + entryPicker + entryIds)**
+**Example: Manual Selection (Repeater + entryPicker + identifiers)**
 
 When authors need to manually curate a list, prefer a repeater of `entryPicker` fields over a plain text identifier field.
 Then pass the selected IDs/identifiers to `listPublishedEntries` in `mode: "manual"` to avoid fetching the full list.
 
-Note: storing `valueFrom: "identifier"` is convenient, but identifiers can change; use UUIDs (`valueFrom: "id"`) if you need immutable references.
+Note: storing `valueFrom: "identifier"` is convenient for repo-managed content and cross-environment portability, but identifiers can change; use UUIDs (`valueFrom: "id"`) if you need immutable references.
 
 ```ts
 // riverbank.config.ts
@@ -2419,7 +2451,7 @@ export default defineConfig({
             siteId: { $bind: { from: '$root.siteId' } },
             type: 'project',
             mode: { $bind: { from: 'content.mode', fallback: 'auto' } },
-            entryIds: {
+            identifiers: {
               $bind: {
                 from: 'content.entries',
                 transforms: [{ id: 'value.jsonArray' }],
@@ -2433,6 +2465,42 @@ export default defineConfig({
 });
 ```
 
+**Example: Repo-Managed Related Content Identifiers**
+
+Repo-managed content can store stable refs directly, for example:
+
+```json
+{
+  "relatedMeditations": [
+    { "meditationIdentifier": "metta-meditation" },
+    { "meditationIdentifier": "resting-in-compassion" }
+  ]
+}
+```
+
+Bind the repeater to `identifiers`; the SDK loader adapter extracts
+`meditationIdentifier` values and hydrates them through the same stable-ref
+resolver used by `client.getEntriesByIdentifiers()`.
+
+```ts
+dataLoaders: {
+  relatedMeditations: {
+    endpoint: 'listPublishedEntries',
+    params: {
+      siteId: { $bind: { from: '$root.siteId' } },
+      type: 'meditation',
+      mode: 'manual',
+      identifiers: {
+        $bind: {
+          from: 'content.relatedMeditations',
+          transforms: [{ id: 'value.jsonArray' }],
+        },
+      },
+    },
+  },
+}
+```
+
 ```tsx
 // components/blocks/FeaturedPosts.tsx
 import type { BlockOverrideProps } from '@riverbankcms/sdk/rendering';
@@ -2836,6 +2904,16 @@ entries: [
       bio: '<p>Our founder...</p>',
       role: 'CEO',
     },
+    // Optional Page Content blocks for template-declared system.entry-slot areas.
+    blocks: {
+      main: [
+        {
+          identifier: 'intro',
+          kind: 'block.body-text',
+          content: { body: 'A richer editable introduction.' },
+        },
+      ],
+    },
     metaTitle: 'John Smith | Team',
     metaDescription: 'Meet John Smith, our CEO',
   },