@riverbankcms/sdk 0.129.1 → 0.130.2

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog — `@riverbankcms/sdk`
+
+Notable changes to the SDK's public contracts. Releases go out through the
+release coordinator (`pnpm release sdk …`), so an entry sits under *Unreleased*
+until the next version ships and then gets the version it went out in.
+
+## Unreleased
+
+### Breaking: the `transparent` header variant is gone
+
+- **`Layout`'s `headerVariant` prop no longer accepts `'transparent'`.** The
+  union narrows from `'classic' | 'centered' | 'transparent' | 'floating'` to
+  `'classic' | 'centered' | 'floating'`. The variant never had any CSS of its
+  own, and everything it did — a transparent header background and content
+  flowing underneath an overlay header — is what `'floating'` already does, so
+  `headerVariant="floating"` is the replacement and should render the same.
+  - If you have a persisted theme that still says `variant: 'transparent'`, it
+    keeps working: the theme parse boundary reads the old spelling as
+    `floating`. Only the TypeScript prop is narrowed.
+
+### Card contracts (issue #1297 follow-up)
+
+Additive throughout — every value that parsed before still parses, so no
+consumer needs to change anything.
+
+- **`FeatureCard.surfaceRole` speaks the card-role vocabulary.** The union
+  widens from `'open' | 'panel'` to `'none' | 'open' | 'default' | 'alternative'
+  | 'panel'`. `panel` is a permanent alias of the `alternative` role, and `open`
+  keeps its historical meaning (an unmarked boxless card, which is role `none`)
+  rather than the `open` role. The exported type is
+  `FeatureCardSurfaceRole`. The `data-surface-role` attribute still carries the
+  authored value, so composition CSS selecting `[data-surface-role="open"]` is
+  unaffected.
+  - Worth knowing if you author the new spellings: the role values give you the
+    card surface but not the editorial-diptych composition. `'panel'` gets both
+    `.card-role-alternative` and the `[data-surface-role="panel"]` rules (the
+    filled media frame and background that variant's layout expects), while
+    `'alternative'` gets the card surface only. The two spellings of "statement
+    card" are therefore not interchangeable inside `editorial-diptych`.
+- **`CardStylesContent` names a card surface with `role`.** `cardVariant` is the
+  legacy name for the same thing and still parses; where both are present,
+  `role` wins.
+- **Missing compiled fields declared.** `MediaTextContent._frameStyles`,
+  `CollectionContent._cardStyles` and `EventCalendarContent._containerStyles`
+  are now part of the SDK's block content types, alongside the card fields on
+  team-members and media-text.
+- **`EventCalendarContent` catches up with the block**: `variant`,
+  `paginationMode`, `seeAllUrl`, `showCapacity`, `boardTitle`, `footerNote`,
+  `elevated` and `banded`.
+- **`EventSurfacePreset` gains `'term'`**, which the events blocks have accepted
+  for a while.
+- **Theme bridge: `open` is the boxless card it claims to be.** A bridge theme's
+  `.card-role-open` now renders the boxless marked card the role contract
+  describes (transparent, a hairline plus a short accent, no elevation) instead
+  of the fully outlined box. `.card-outlined` keeps its old declarations as a
+  compatibility class with no role attached; naming it in
+  `components.cards.variants` enables that class only.
+  - **Fixed**: a bridge `open` card's media no longer keeps rounded top corners
+    while its container is square. Card media radii now resolve from the same
+    per-corner geometry as the container, so a variant that overrides its
+    corners overrides its media edge too.
+- **`FeatureCardSurfaceRole` states the `open` exception in the type.** The
+  union is now built as `Exclude<CardRole, 'open'> | FeatureCardLegacySurfaceRole`
+  (`FeatureCardLegacySurfaceRole = 'open' | 'panel'`, also exported). The set of
+  accepted strings is unchanged — this is a documentation-in-types change, not a
+  behaviour change — but it now says out loud that `open` reaches this field
+  only as a legacy spelling. **The canonical `open` role is permanently
+  unaddressable per item on a feature card**: the alias always wins and maps it
+  to role `none`. A card that should render the marked boxless `open` surface
+  gets it from the block's card role, not from `surfaceRole`.
+- **`CardRole` is exported.** The canonical card-role vocabulary
+  (`'none' | 'open' | 'default' | 'alternative'`) is now a named public type
+  rather than being spelled out inline, and a typetest pins it equal to
+  theme-core's in both directions so the two cannot drift.
+- **Theme bridge: card role CSS is no longer opt-in.** `.card-role-default`,
+  `.card-role-alternative` and `.card-role-open` now emit from
+  `buildThemeBridgeRuntime` whether or not you configure `components.cards`.
+  They are the surface contract compiled content renders against, so a bridge
+  theme that omitted them left role-styled blocks unstyled. `components.cards`
+  continues to govern the named `.card-default` / `.card-elevated` /
+  `.card-outlined` catalogue exactly as before, including its `variants`
+  allow-list.
+- **`CHANGELOG.md` ships in the published package.** It was written but not in
+  the `files` allowlist, so installed copies of the SDK had no release record.
+  The packed-package check now asserts its presence.

package/README.md

@@ -340,7 +340,7 @@ When a path might resolve to either a page or a content entry (blog post, produc
 ### Server-Side: loadContent
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 
 export default async function DynamicRoute({ params }) {
   const path = `/${params.slug?.join('/') || ''}`;
@@ -354,6 +354,9 @@ export default async function DynamicRoute({ params }) {
 
   // Pages get rendered with the Page component
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }
 
@@ -386,6 +389,7 @@ export function DynamicContent({ path }: { path: string }) {
   if (content.error) return <div>Error: {content.error.message}</div>;
 
   if (isPageContentResult(content)) {
+    if (!content.theme) return <div>This site needs a theme before it can be displayed.</div>;
     return <Page page={content.page} theme={content.theme} siteId={content.siteId} resolvedData={content.resolvedData} />;
   }
 
@@ -405,12 +409,15 @@ export function DynamicContent({ path }: { path: string }) {
 Route entries to different components based on their content type:
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 
 export default async function DynamicRoute({ params }) {
   const content = await loadContent({ client, siteId, path: `/${params.slug?.join('/') || ''}` });
 
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }
 
@@ -981,7 +988,7 @@ Override the header variant from your code:
 ```tsx
 <Layout
   siteData={siteData}
-  headerVariant="centered"  // Options: classic, centered, transparent, floating, editorial
+  headerVariant="centered"  // Options: classic, centered, floating
 >
   <main>Content with centered header</main>
 </Layout>
@@ -2671,7 +2678,9 @@ In this mode the SDK does not resolve, parse, normalize, or build tokens from th
 
 The optional theme-independent wrapper belongs inside `rendering`: use `runtime: { kind: 'responsive-only' }` (the default) for Riverbank's generated responsive utility scope, or `runtime: { kind: 'none' }` when the host owns that too. Do not combine override-only rendering with top-level `themeRuntime`, `theme`, `themes`, or `getTheme`. If you use SDK `Layout` directly, its header and footer must both be custom or disabled. Preview receives the same rendering selection and registry.
 
-The content response still carries a compatibility theme field for now; override-only rendering deliberately ignores it. Wire-level theme nullability is tracked separately in #1290.
+`SiteResponse.theme` is required but nullable: `Theme | null`. A null value means the CMS has no theme; it does not select a rendering mode. Override-only rendering deliberately ignores it. Themed catch-all rendering first prefers explicit `theme`, `themes`, or `getTheme` inputs, then uses the CMS theme. If none resolves, it throws the exported `MissingSdkThemeError` with code `missing_sdk_theme` before theme parsing or token construction.
+
+The nullable contract must be published before the server stops supplying its temporary fallback. Externally pinned hosts must upgrade to this SDK contract and either opt into override-only rendering or provide a real local/CMS theme before that server cutover.
 
 Keep the `server-only` marker at the top of the registry so Next.js turns an accidental Client Component import into a build error. `generateMetadata()` never receives or runs host loaders—even with `customMetadata`—so a normal request does not repeat host queries for metadata and rendering.
 
@@ -3252,27 +3261,32 @@ export { generateMetadata };
 
 ### Production ISR Setup
 
-For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true`; `getISRConfig()` then returns `revalidate: 0` so draft previews stay dynamic.
+For production SDK sites, wire the catch-all route to Next ISR and let Riverbank discover published routes at build time. Next.js statically analyzes route configuration, so `revalidate` must be a literal rather than a function call or imported constant. Preview deployments should set `RIVERBANK_PREVIEW_MODE=true` and use the SDK preview integration, whose request-bound session handling keeps draft previews dynamic.
 
 ```tsx
 // src/app/[[...slug]]/page.tsx
 import {
   createCatchAllPage,
-  generateAllStaticParams,
-  getISRConfig,
+  createGenerateStaticParams,
 } from '@riverbankcms/sdk/next';
 
 import config from '@/riverbank.config';
 import { blockOverrides } from '@/lib/block-overrides';
 import { getRiverbankClient } from '@/lib/riverbank-client';
 
-export const revalidate = getISRConfig().revalidate;
+// Next.js route config values must remain statically analyzable literals.
+export const revalidate = 300;
 export const dynamicParams = true;
-export { generateAllStaticParams as generateStaticParams };
+export const generateStaticParams = createGenerateStaticParams({
+  getClient: getRiverbankClient,
+  siteId: config.siteId,
+  failureMode: 'throw',
+});
 
 const { Page, generateMetadata } = createCatchAllPage({
   getClient: getRiverbankClient,
   config,
+  searchParamsMode: 'ignore',
   blockOverrides,
 });
 
@@ -3280,7 +3294,12 @@ export default Page;
 export { generateMetadata };
 ```
 
-`generateAllStaticParams()` reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails, which keeps deploys from publishing an empty static route set silently. For strict production CI, fail the build instead:
+`searchParamsMode: 'ignore'` is required for this ISR shape because Next.js treats
+the page `searchParams` prop as a Dynamic API. Keep the default `dynamic` mode only
+when server-rendered themes, data loaders, redirects, or metadata genuinely depend
+on URL query parameters.
+
+If a site uses the SDK's generic environment variable names, `generateAllStaticParams()` is also available. It reads `RIVERBANK_API_KEY`, `RIVERBANK_SITE_ID`, and `NEXT_PUBLIC_DASHBOARD_URL`. By default it falls back to the homepage when route discovery fails. For strict production CI, fail the build instead:
 
 ```tsx
 import { generateAllStaticParams } from '@riverbankcms/sdk/next';
@@ -3627,7 +3646,7 @@ type CatchAllContext = {
 For maximum customization, skip `createCatchAllPage` and use the underlying helpers:
 
 ```tsx
-import { loadContent, isPageContent, Page } from '@riverbankcms/sdk/rendering';
+import { loadContent, isPageContent, MissingSdkThemeError, Page } from '@riverbankcms/sdk/rendering';
 import { generatePageMetadata } from '@riverbankcms/sdk/metadata';
 
 export default async function CustomPage({ params }) {
@@ -3642,6 +3661,9 @@ export default async function CustomPage({ params }) {
   });
 
   if (isPageContent(content)) {
+    if (!content.theme) {
+      throw new MissingSdkThemeError(content.siteId, 'cms_theme_absent');
+    }
     return <Page {...content} />;
   }