@riverbankcms/sdk 0.62.2 → 0.62.4

package/dist/_dts/theme-core/src/site-styles/headerOpeningSection.d.ts

@@ -0,0 +1,15 @@
+import type { BlockDesignPlan, DesignBlockId, ResolvedBlockDesignPlan } from './types';
+import type { HeaderLookId, HeaderOpeningSectionContext } from './headerLooks';
+export type HeaderOpeningSectionRepair = 'promote-opening-hero-surface' | 'add-opening-contrast-overlay' | 'add-opening-top-spacing';
+export type HeaderOpeningSectionPlan<TBlockId extends DesignBlockId = DesignBlockId> = Readonly<{
+    plan: readonly BlockDesignPlan<TBlockId>[];
+    repairs: readonly HeaderOpeningSectionRepair[];
+}>;
+export declare function planGeneratedHeaderOpeningSection<TBlockId extends DesignBlockId>(input: Readonly<{
+    plan: readonly BlockDesignPlan<TBlockId>[];
+    recommendedHeaderLookIds: readonly HeaderLookId[];
+}>): HeaderOpeningSectionPlan<TBlockId>;
+export declare function deriveHeaderOpeningSectionContext(input: Readonly<{
+    openingBlock: ResolvedBlockDesignPlan | null;
+    openingContent?: Record<string, unknown> | null;
+}>): HeaderOpeningSectionContext;

package/dist/_dts/theme-core/src/site-styles/index.d.ts

@@ -5,9 +5,13 @@ export * from './contentTemplateDesignIntent';
 export * from './contentTemplateRuntimeCompiler';
 export * from './curatedChoices';
 export * from './curatedSiteStyles';
+export * from './customizableSurfaces';
 export * from './designState';
+export * from './footerLooks';
 export * from './generatedSchemas';
 export * from './generatedDesignPipeline';
+export * from './headerLooks';
+export * from './headerOpeningSection';
 export * from './lookResolution';
 export * from './pageDesignAuthority';
 export * from './pageDesignEditorErrors';
@@ -15,8 +19,10 @@ export * from './pageDesignEditorModel';
 export * from './pageDesignIntent';
 export * from './previewCustomization';
 export * from './rawStyleFields';
+export * from './records';
 export * from './resolver';
 export * from './runtimeCompiler';
+export * from './siteStyleBlockPolicies';
 export * from './sourceCatalogs';
 export * from './styleTags';
 export * from './tokenRecipes';

package/dist/_dts/theme-core/src/site-styles/pageDesignAuthority.d.ts

@@ -36,6 +36,9 @@ export type PageDesignPublishPlan = Readonly<{
     /** Persisted as content_versions.data for the page-owned published design row. */
     versionData: PublishedPageDesignVersionDataV1;
 }>;
+export type PublishedPageDesignVersionDataPlan = Result<PublishedPageDesignVersionDataV1, Extract<PageDesignPublishBlocker, {
+    kind: 'missing-published-block-content';
+}>>;
 export type PageDesignRuntimePairingIssue = Readonly<{
     kind: 'missing-current-block';
     persisted: PublishedPageBlockSnapshot;
@@ -258,6 +261,10 @@ export declare function buildPageDesignPublishPlan(input: Readonly<{
     authority: PageDesignAuthority;
     blockSequence: readonly PageBlockSnapshot[];
 }>): Result<PageDesignPublishPlan, PageDesignPublishBlocker>;
+export declare function buildPublishedPageDesignVersionData(input: Readonly<{
+    pageId: DesignPageId;
+    blockSequence: readonly PageBlockSnapshot[];
+}>): PublishedPageDesignVersionDataPlan;
 export declare function buildPageDesignRuntimePairingPlan(input: Readonly<{
     versionData: PublishedPageDesignVersionDataV1;
     currentBlockSequence: readonly PageBlockSnapshot[];

package/dist/_dts/theme-core/src/site-styles/pageDesignEditorModel.d.ts

@@ -53,6 +53,10 @@ export type PageDesignEditorLayoutOption = Readonly<{
     label: string;
     profile: BlockLayoutDesignProfile;
 }>;
+export type PageDesignEditorLooksForLayout = Readonly<{
+    layoutVariantKey: LayoutVariantKey;
+    availableLooks: readonly PageDesignEditorLookOption[];
+}>;
 export type PageDesignEditorBlockContentRevision = Readonly<{
     contentId: string | null;
 }>;
@@ -62,6 +66,7 @@ export type PageDesignEditorBlock<TBlockId extends DesignBlockId = DesignBlockId
     contentRevision?: PageDesignEditorBlockContentRevision;
     layout: PageDesignEditorSelection<LayoutVariantKey> | null;
     availableLayouts: readonly PageDesignEditorLayoutOption[];
+    availableLooksByLayout: readonly PageDesignEditorLooksForLayout[];
     look: PageDesignEditorChoice<AppearancePresetId>;
     availableLooks: readonly PageDesignEditorLookOption[];
 }>;
@@ -164,3 +169,23 @@ export declare function resolveVisiblePromotedFieldPathsForEditorBlock(input: Re
     block: PageDesignEditorBlock;
     promotedFieldPaths?: readonly string[];
 }>): readonly string[];
+export type PageDesignLayoutLookIntentChange = Readonly<{
+    kind: 'preserve-auto';
+}> | Readonly<{
+    kind: 'preserve-supported-pin';
+    appearancePresetId: AppearancePresetId;
+}> | Readonly<{
+    kind: 'reset-incompatible-pin';
+    previousAppearancePresetId: AppearancePresetId;
+}>;
+export type PageDesignLayoutLookCompatibilityPlan = Readonly<{
+    kind: 'layout-unavailable';
+    layoutVariantKey: LayoutVariantKey;
+}> | Readonly<{
+    kind: 'layout-supported';
+    layout: PageDesignEditorSelection<LayoutVariantKey>;
+    availableLooks: readonly PageDesignEditorLookOption[];
+    look: PageDesignEditorChoice<AppearancePresetId>;
+    lookIntentChange: PageDesignLayoutLookIntentChange;
+}>;
+export declare function planPageDesignLayoutLookCompatibility(block: PageDesignEditorBlock, layoutVariantKey: LayoutVariantKey): PageDesignLayoutLookCompatibilityPlan;

package/dist/_dts/theme-core/src/site-styles/previewCompiler.d.ts

@@ -3,6 +3,8 @@ import { type Theme } from '../schema';
 import { type ButtonPersonalityId } from '../buttons/personalities';
 import { type PaletteOverrides, type PaletteVariantId } from '../palette/variants';
 import { type CuratedSiteStyle } from './curatedSiteStyles';
+import { type FooterLookId, type FooterSelectionContext, type FooterSelectionResult } from './footerLooks';
+import { type HeaderSelectionContext, type HeaderLookId, type HeaderSelectionResult } from './headerLooks';
 import { type CompiledBlockRuntimeFields, type CompiledPageRuntime, type ComponentRuntimeRules, type DesignRuntimeRules, type SemanticSpacing } from './runtimeCompiler';
 import type { AppearancePresetId, DesignBlockId, SiteStyleId } from './types';
 /**
@@ -16,7 +18,7 @@ import type { AppearancePresetId, DesignBlockId, SiteStyleId } from './types';
 export { defineBlockDesignMetadata, type BlockDesignMetadata, type BlockDesignMetadataInput, type BlockDesignMetadataMap, type BlockFlowBoundaryPreference, type BlockFlowContract, type BlockFlowSurfaceBehavior, type BlockFlowWeight, type BlockLayoutBoundaryBias, type BlockLayoutDesignProfile, type BlockLayoutDesignProfileInput, type BlockLayoutFamily, type BlockLayoutVisualWeight, type PageFlowRole, } from './blockFlow';
 export { buildPageDesignEditorReadModel, boundaryOptions, pageFlowPresets, type BoundaryOption, type PageDesignEditorBlock, type PageDesignEditorBoundary, type PageDesignEditorChoice, type PageDesignEditorIssue, type PageDesignEditorReadModel, type PageDesignEditorSelection, type PageFlowPreset, } from './pageDesignEditorModel';
 export { autoDesignChoice, reducePageDesignIntentForUserAction, resolvePageDesignBlockLookChoice, resolvePageDesignBoundaryChoice, userPinnedDesignChoice, type PageDesignChoice, type PageDesignIntent, type PageDesignUserAction, } from './pageDesignIntent';
-export { repairDesignIssue, resolveBlockDesignPlan, } from './resolver';
+export { repairDesignIssue, resolveBlockDesignPlan } from './resolver';
 export { cycleableOptionsFromResolved, deriveDesignCustomizationScope, recommendedDesignOption, type CycleableDesignOption, type CycleableOptions, type DesignCustomizationAuthority, type DesignCustomizationScope, type DesignCustomizationSurface, type DesignCustomizationUnsupportedReason, type DesignOptionIssue, type ResolvedDesignOption, } from './previewCustomization';
 export { compileBlockRuntimeFields, compilePageRuntimeFields, compileTokenRecipes, compiledRuntimeStyleFieldNames, defaultComponentRuntimeRules, defaultDesignRuntimeRules, stripCompiledRuntimeStyleFields, type CompiledBlockRuntime, type CompiledBlockRuntimeFields, type CompiledPageRuntime, type CompileBlockRuntimeInput, type ComponentRuntimeRules, type DesignRuntimeRules, type SemanticSpacing, } from './runtimeCompiler';
 export { defaultCuratedChoice, requireEntriesForCuratedChoices, resolveCuratedChoice, type CuratedChoice, type CuratedChoiceResolution, } from './curatedChoices';
@@ -52,13 +54,25 @@ export type SiteThemeSelectionsInput = Readonly<{
     buttonPersonalityId: ButtonPersonalityId | null;
     paletteVariantId: PaletteVariantId | null;
     paletteOverrides: PaletteOverrides | null;
+    headerLookId?: HeaderLookId | null;
+    footerLookId?: FooterLookId | null;
+    headerSelectionContext?: Partial<HeaderSelectionContext>;
+    footerSelectionContext?: Partial<FooterSelectionContext>;
 }>;
 export type SiteThemeSelectionsResult = Readonly<{
     theme: CuratedSiteStyleTheme;
+    requestedSelections: Readonly<{
+        headerLookId: HeaderLookId | null;
+        footerLookId: FooterLookId | null;
+    }>;
     resolvedSelections: Readonly<{
         buttonPersonalityId: ButtonPersonalityId;
         paletteVariantId: PaletteVariantId;
+        headerLookId: HeaderLookId;
+        footerLookId: FooterLookId;
     }>;
+    headerSelection: HeaderSelectionResult;
+    footerSelection: FooterSelectionResult;
     warnings: ReadonlyArray<SelectionFallbackWarning>;
 }>;
 /**

package/dist/_dts/theme-core/src/site-styles/records.d.ts

@@ -0,0 +1 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/_dts/theme-core/src/site-styles/siteStyleBlockPolicies.d.ts

@@ -0,0 +1,96 @@
+import type { BlockLayoutDesignProfile } from './blockFlow';
+import { autoDesignChoice, type PageDesignBlockDescriptor, type PageDesignIntent, type PageDesignUserPinnedChoice } from './pageDesignIntent';
+import { type AppearancePresetId, type BoundaryOptionId, type DesignBlockId, type LayoutVariantKey, type SiteStyleId } from './types';
+export declare const defaultPolicyPageFlowPresetId: import("@riverbankcms/blocks").PageFlowPresetId;
+export type OpenSiteStyleBlockPolicy = Readonly<{
+    kind: 'open';
+}>;
+export type LockedLookAndLayoutsSiteStyleBlockPolicy = Readonly<{
+    kind: 'locked-look-and-layouts';
+    blockKind: string;
+    lookId: AppearancePresetId;
+    allowedLayoutVariantKeys: readonly LayoutVariantKey[];
+    defaultLayoutVariantKey: LayoutVariantKey;
+    defaultBoundaryAfter?: Readonly<{
+        optionId: BoundaryOptionId;
+        mode: 'default-only';
+    }>;
+    customize: Readonly<{
+        hideDisallowedLooks: true;
+        hideDisallowedLayouts: true;
+    }>;
+}>;
+export type SiteStyleBlockPolicy = OpenSiteStyleBlockPolicy | LockedLookAndLayoutsSiteStyleBlockPolicy;
+type RegisteredSiteStyleBlockPolicy = LockedLookAndLayoutsSiteStyleBlockPolicy & Readonly<{
+    siteStyleId: SiteStyleId;
+}>;
+export type BlockPolicyDescriptor<TBlockId extends DesignBlockId = DesignBlockId> = PageDesignBlockDescriptor<TBlockId> & Readonly<{
+    currentLayoutVariantKey?: LayoutVariantKey | null;
+    layoutProfiles?: readonly BlockLayoutDesignProfile[] | null;
+}>;
+export type BlockContentVariantPolicyPlan = Readonly<{
+    kind: 'unchanged';
+}> | Readonly<{
+    kind: 'set-variant';
+    variantKey: LayoutVariantKey;
+}>;
+export type PageDesignPolicyAuditIssue<TBlockId extends DesignBlockId = DesignBlockId> = Readonly<{
+    kind: 'missing-page-design-authority';
+    siteStyleId: SiteStyleId;
+    policyBlockCount: number;
+}> | Readonly<{
+    kind: 'missing-required-look-pin';
+    blockId: TBlockId;
+    blockKind: string;
+    requiredLookId: AppearancePresetId;
+}> | Readonly<{
+    kind: 'unsupported-look-pin';
+    blockId: TBlockId;
+    blockKind: string;
+    actualLookId: AppearancePresetId;
+    requiredLookId: AppearancePresetId;
+}> | Readonly<{
+    kind: 'unsupported-layout-variant';
+    blockId: TBlockId;
+    blockKind: string;
+    actualLayoutVariantKey: LayoutVariantKey;
+    defaultLayoutVariantKey: LayoutVariantKey;
+}>;
+export declare function siteStyleBlockPolicies(): readonly RegisteredSiteStyleBlockPolicy[];
+export declare function buildInitialPolicyPageDesignIntent(siteStyleId: SiteStyleId): PageDesignIntent;
+export declare function hasPolicyForBlocks(input: Readonly<{
+    siteStyleId: SiteStyleId;
+    blocks: readonly PageDesignBlockDescriptor[];
+}>): boolean;
+export declare function deriveSiteStyleBlockPolicy(input: Readonly<{
+    siteStyleId: SiteStyleId;
+    blockKind: string;
+}>): SiteStyleBlockPolicy;
+export declare function isLayoutVariantAllowedByPolicy(policy: SiteStyleBlockPolicy, layoutVariantKey: LayoutVariantKey): boolean;
+export declare function normalizeLayoutVariantForPolicy(policy: SiteStyleBlockPolicy, layoutVariantKey: LayoutVariantKey | null | undefined): LayoutVariantKey | null;
+export declare function filterLayoutProfilesForPolicy(policy: SiteStyleBlockPolicy, layoutProfiles: readonly BlockLayoutDesignProfile[]): readonly BlockLayoutDesignProfile[];
+export declare function isLookAllowedByPolicy(policy: SiteStyleBlockPolicy, lookId: AppearancePresetId): boolean;
+export declare function filterLookIdsForPolicy<TLook extends Readonly<{
+    id: AppearancePresetId;
+}>>(policy: SiteStyleBlockPolicy, looks: readonly TLook[]): readonly TLook[];
+export declare function applySiteStyleBlockPoliciesToPageDesignIntent<TBlockId extends DesignBlockId>(intent: PageDesignIntent<TBlockId>, blocks: readonly PageDesignBlockDescriptor<TBlockId>[]): PageDesignIntent<TBlockId>;
+export declare function planBlockContentVariantPolicyUpdate(input: Readonly<{
+    policy: SiteStyleBlockPolicy;
+    content: Readonly<Record<string, unknown>>;
+}>): BlockContentVariantPolicyPlan;
+export declare function applyBlockContentVariantPolicy(input: Readonly<{
+    policy: SiteStyleBlockPolicy;
+    content: Readonly<Record<string, unknown>>;
+}>): Readonly<Record<string, unknown>>;
+export declare function auditPageDesignIntentPolicy<TBlockId extends DesignBlockId>(input: Readonly<{
+    intent: PageDesignIntent<TBlockId>;
+    blocks: readonly BlockPolicyDescriptor<TBlockId>[];
+}>): readonly PageDesignPolicyAuditIssue<TBlockId>[];
+export declare function auditPageDesignAuthorityPolicy<TBlockId extends DesignBlockId>(input: Readonly<{
+    siteStyleId: SiteStyleId;
+    intent: PageDesignIntent<TBlockId> | null;
+    blocks: readonly BlockPolicyDescriptor<TBlockId>[];
+}>): readonly PageDesignPolicyAuditIssue<TBlockId>[];
+export declare function assertRegisteredSiteStyleBlockPoliciesAreValid(): void;
+export declare function autoChoiceAllowedByPolicy(policy: SiteStyleBlockPolicy): ReturnType<typeof autoDesignChoice> | PageDesignUserPinnedChoice<AppearancePresetId>;
+export {};

package/dist/_dts/theme-core/src/site-styles/types.d.ts

@@ -1,5 +1,5 @@
 import type { Theme } from '../schema';
-type Brand<T, TBrand extends string> = T & {
+export type Brand<T, TBrand extends string> = T & {
     readonly __brand: TBrand;
 };
 export type DesignBlockId = Brand<string, 'DesignBlockId'>;
@@ -635,4 +635,3 @@ export type SiteStyleSwitchResult<TBlockId extends string = DesignBlockId, TPurp
     incompatibleBlockIds: readonly TBlockId[];
     fallbackBlockIds: readonly TBlockId[];
 }>;
-export {};

package/dist/_dts/theme-core/src/siteChrome.d.ts

@@ -1,11 +1,53 @@
-import { type ReactNode } from "react";
+import React, { type ReactNode } from "react";
 import type { Theme } from "./schema";
-export type SiteTopShellBehavior = "normal-flow" | "shared-sticky-shell";
+export type SiteTopShellBehavior = "normal-flow" | "shared-sticky-shell" | "banner-above-overlay-header";
+export type SiteTopShellPlan = Readonly<{
+    behavior: "normal-flow";
+    contentStartsUnderHeader: boolean;
+    requiresHeaderOffset: false;
+}> | Readonly<{
+    behavior: "shared-sticky-shell";
+    contentStartsUnderHeader: false;
+    requiresHeaderOffset: false;
+}> | Readonly<{
+    behavior: "banner-above-overlay-header";
+    contentStartsUnderHeader: true;
+    requiresHeaderOffset: true;
+}>;
 export type SiteChromeLayoutNodes = Readonly<{
     headerNode: ReactNode;
     bannerNode?: ReactNode;
     bannerShellBehavior?: SiteTopShellBehavior;
     footerNode: ReactNode;
 }>;
+type HeaderPositioning = NonNullable<Theme["header"]>["positioning"];
+export type SiteDocumentLayoutMode = "normal-flow" | "header-overlay";
+export type SiteDocumentPlan = Readonly<{
+    topShell: SiteTopShellPlan;
+    layoutMode: SiteDocumentLayoutMode;
+}>;
+export type SiteDocumentPlanInput = Readonly<{
+    headerPositioning: HeaderPositioning;
+    headerVariant?: Theme["header"]["variant"] | null;
+    hasVisibleBanner: boolean;
+}>;
+export type SiteDocumentLayoutProps = Omit<SiteChromeLayoutNodes, "bannerShellBehavior"> & Readonly<{
+    plan: SiteDocumentPlan;
+    children: ReactNode;
+    as?: "div" | "main";
+    role?: string;
+    className?: string | null;
+    minHeightClassName?: string | null;
+    contentClassName?: string | null;
+    style?: React.CSSProperties;
+}>;
 export declare function getStandaloneHeaderShellClassName(theme: Theme): string | null;
 export declare function renderSiteTopChrome({ headerNode, bannerNode, bannerShellBehavior, }: Pick<SiteChromeLayoutNodes, "headerNode" | "bannerNode" | "bannerShellBehavior">): ReactNode;
+export declare function planSiteDocument(input: SiteDocumentPlanInput): SiteDocumentPlan;
+export declare function SiteDocumentLayout({ plan, headerNode, bannerNode, footerNode, children, as: Root, role, className, minHeightClassName, contentClassName, style, }: SiteDocumentLayoutProps): React.ReactElement;
+export declare function planSiteTopShell(input: Readonly<{
+    headerPositioning: HeaderPositioning;
+    headerVariant?: Theme["header"]["variant"] | null;
+    hasVisibleBanner: boolean;
+}>): SiteTopShellPlan;
+export {};

package/dist/_dts/theme-core/src/tokens/colorTokenParts.d.ts

@@ -0,0 +1,13 @@
+export type ColorTokenParts = {
+    readonly kind: 'token';
+    readonly token: string;
+    readonly opacityPercent: number | null;
+} | {
+    readonly kind: 'raw';
+    readonly value: string;
+} | {
+    readonly kind: 'invalid';
+    readonly token: string;
+};
+export declare function parseOpacityPercent(source: string): number | null;
+export declare function parseColorTokenParts(source: string): ColorTokenParts;

package/dist/_dts/theme-core/src/tokens/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./tokens";
 export * from "./blockColorTokens";
+export * from "./themeColorTokens";
+export * from "./colorTokenParts";
 export { TokenResolver } from "./resolver";

package/dist/_dts/theme-core/src/tokens/themeColorTokens.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Known palette role token names. This is the low-level source of truth for
+ * palette roles used by palette variants, Theme V2 schemas, and runtime color
+ * reference parsing.
+ */
+export declare const PALETTE_TOKEN_NAMES: readonly ["primary", "primaryForeground", "secondary", "accent", "success", "warning", "destructive", "background", "surface", "surfaceAlt", "muted", "text", "border"];
+export type PaletteTokenName = (typeof PALETTE_TOKEN_NAMES)[number];
+export declare const paletteTokenNameSchema: z.ZodEnum<{
+    success: "success";
+    text: "text";
+    surface: "surface";
+    warning: "warning";
+    border: "border";
+    background: "background";
+    primary: "primary";
+    secondary: "secondary";
+    primaryForeground: "primaryForeground";
+    accent: "accent";
+    destructive: "destructive";
+    surfaceAlt: "surfaceAlt";
+    muted: "muted";
+}>;
+export type ThemeColorToken = string & {
+    readonly __brand: 'ThemeColorToken';
+};
+export declare function isThemeColorToken(value: unknown): value is ThemeColorToken;
+export declare function parseThemeColorToken(value: unknown): ThemeColorToken | null;
+export declare const themeColorTokenSchema: z.ZodString;

package/dist/_dts/theme-core/src/utils/tokenOrColor.d.ts

@@ -1,10 +1,36 @@
+import { z } from 'zod';
+import { type ThemeColorToken } from '../tokens/themeColorTokens';
 export type TokenOrColor = string;
+/**
+ * Runtime color-reference fields intentionally accept any string, including
+ * the legacy empty-string "no color" sentinel. Semantic validation needs
+ * palette context and happens in `parseThemeColorReference`.
+ */
+export declare const tokenOrCssColorValueSchema: z.ZodString;
+export type PaletteContextColorToken = string & {
+    readonly __brand: 'PaletteContextColorToken';
+};
+export type ThemeColorReference = {
+    kind: 'theme-token';
+    token: ThemeColorToken;
+} | {
+    kind: 'palette-context-token';
+    token: PaletteContextColorToken;
+} | {
+    kind: 'literal-css';
+    value: string;
+};
+export type ThemeColorReferenceContext = {
+    palette?: Readonly<Record<string, string>>;
+};
 type ParsedToken = {
     role: string;
     shade: number | null;
 };
 export declare function isCssColorLiteral(value: string): boolean;
 export declare function parseThemeToken(token: string): ParsedToken;
-export declare function resolveTokenOrCssColorValue(input: TokenOrColor): string;
+export declare function parseThemeColorReference(input: TokenOrColor, context?: ThemeColorReferenceContext): ThemeColorReference;
+export declare function resolveThemeColorReferenceValue(input: TokenOrColor, context?: ThemeColorReferenceContext): string;
+export declare function resolveTokenOrCssColorValue(input: TokenOrColor, context?: ThemeColorReferenceContext): string;
 export declare function resolveOnColorForThemeToken(token: string): string | null;
 export {};