@riverbankcms/sdk 0.128.0 → 0.129.1

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

@@ -0,0 +1,106 @@
+import { type HeaderBrandPresentationPlan, type HeaderBrandPresentationSelection, type LogoAccommodationOption } from './logoBranding';
+import type { HeaderLogoContext } from './headerLookTypes';
+export declare const inlineClassicLogoAccommodations: readonly [{
+    readonly pattern: "title-only";
+    readonly supportedShapes: readonly ["none", "horizontal", "square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["title-only"];
+    readonly size: "compact";
+}, {
+    readonly pattern: "inline-wordmark";
+    readonly supportedShapes: readonly ["horizontal"];
+    readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "standard";
+    readonly maxDensity: "detailed";
+}, {
+    readonly pattern: "inline-mark-with-title";
+    readonly supportedShapes: readonly ["horizontal", "square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["no-text"];
+    readonly supportedDisplayModes: readonly ["logo-plus-title"];
+    readonly size: "compact";
+    readonly maxDensity: "simple";
+}, {
+    readonly pattern: "popout-badge";
+    readonly supportedShapes: readonly ["square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "display";
+    readonly providesBacking: true;
+}, {
+    readonly pattern: "logo-plate";
+    readonly supportedShapes: readonly ["square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "display";
+    readonly providesBacking: true;
+}];
+export declare const centeredLogoAccommodations: readonly [{
+    readonly pattern: "title-only";
+    readonly supportedShapes: readonly ["none", "horizontal", "square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["title-only"];
+    readonly size: "compact";
+}, {
+    readonly pattern: "inline-wordmark";
+    readonly supportedShapes: readonly ["horizontal"];
+    readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "standard";
+    readonly maxDensity: "detailed";
+}, {
+    readonly pattern: "inline-mark-with-title";
+    readonly supportedShapes: readonly ["horizontal", "square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["no-text"];
+    readonly supportedDisplayModes: readonly ["logo-plus-title"];
+    readonly size: "compact";
+    readonly maxDensity: "simple";
+}, {
+    readonly pattern: "centered-masthead";
+    readonly supportedShapes: readonly ["square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "display";
+    readonly providesBacking: true;
+}, {
+    readonly pattern: "centered-badge";
+    readonly supportedShapes: readonly ["square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "display";
+    readonly providesBacking: true;
+}];
+export declare const overlayLogoAccommodations: readonly [{
+    readonly pattern: "title-only";
+    readonly supportedShapes: readonly ["none", "horizontal", "square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["title-only"];
+    readonly size: "compact";
+}, {
+    readonly pattern: "inline-wordmark";
+    readonly supportedShapes: readonly ["horizontal"];
+    readonly supportedTextPresence: readonly ["contains-text", "no-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "standard";
+    readonly maxDensity: "detailed";
+}, {
+    readonly pattern: "inline-mark-with-title";
+    readonly supportedShapes: readonly ["horizontal", "square", "portrait", "tall"];
+    readonly supportedTextPresence: readonly ["no-text"];
+    readonly supportedDisplayModes: readonly ["logo-plus-title"];
+    readonly size: "compact";
+    readonly maxDensity: "simple";
+}, {
+    readonly pattern: "inline-logo-only";
+    readonly supportedShapes: readonly ["square"];
+    readonly supportedTextPresence: readonly ["contains-text", "unknown"];
+    readonly supportedDisplayModes: readonly ["logo-only"];
+    readonly size: "compact";
+    readonly providesBacking: false;
+}];
+export declare function resolveHeaderBrandPresentation(input: Readonly<{
+    logo: HeaderLogoContext;
+    accommodations: readonly LogoAccommodationOption[];
+    allowDisplayFallback?: boolean;
+}>): HeaderBrandPresentationPlan;
+export declare function requireHeaderBrandPresentationSelection(plan: HeaderBrandPresentationPlan): HeaderBrandPresentationSelection;

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

@@ -0,0 +1,2 @@
+import { type HeaderLookResolutionInput, type HeaderSelectionResult } from './headerLookTypes';
+export declare function resolveHeaderLook(input: HeaderLookResolutionInput): HeaderSelectionResult;

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

@@ -0,0 +1,212 @@
+import type { Theme, ThemeHeader } from '../schema';
+import type { HeaderInteractionPaletteOptionGroup } from './headerInteractionPalette';
+import type { HeaderOpeningForeground } from './headerOpeningForeground';
+import type { BrandDisplayMode, HeaderBrandPresentationSelection, LogoAccommodationOption, LogoAccommodationRejectionReason, LogoFacts, LogoSizePolicy } from './logoBranding';
+import type { Brand } from './types';
+export declare const headerLookIdValues: readonly ["clean-base", "classic-centered-nav", "brand-solid", "serif-line", "centered-calm", "practical-utility", "minimal-transparent", "transparent-overlay", "floating-glass"];
+export type HeaderLookIdValue = (typeof headerLookIdValues)[number];
+export type HeaderLookId = Brand<HeaderLookIdValue, 'HeaderLookId'>;
+export declare function asHeaderLookId(value: HeaderLookIdValue): HeaderLookId;
+export type PersistedHeaderLookIdParseResult = Readonly<{
+    kind: 'known';
+    id: HeaderLookId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLookId(value: string): Exclude<PersistedHeaderLookIdParseResult, {
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLookId(value: string | null | undefined): PersistedHeaderLookIdParseResult;
+export declare const headerLayoutIdValues: readonly ["classic", "centered", "floating"];
+export type HeaderLayoutIdValue = (typeof headerLayoutIdValues)[number];
+export type HeaderLayoutId = Brand<HeaderLayoutIdValue, 'HeaderLayoutId'>;
+export declare function asHeaderLayoutId(value: HeaderLayoutIdValue): HeaderLayoutId;
+export type PersistedHeaderLayoutIdParseResult = Readonly<{
+    kind: 'known';
+    id: HeaderLayoutId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLayoutId(value: string): Exclude<PersistedHeaderLayoutIdParseResult, {
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderLayoutId(value: string | null | undefined): PersistedHeaderLayoutIdParseResult;
+export declare const headerStyleIdValues: readonly ["minimal", "fine-line", "soft-bar", "pill-nav", "brand-bar", "brand-underline", "brand-pill", "brand-capsule", "serif-line", "flat-tabs", "glass", "minimal-surface", "soft-shell", "split-glass", "split-pill"];
+export type HeaderStyleIdValue = (typeof headerStyleIdValues)[number];
+export type HeaderStyleId = Brand<HeaderStyleIdValue, 'HeaderStyleId'>;
+export declare function asHeaderStyleId(value: HeaderStyleIdValue): HeaderStyleId;
+export type PersistedHeaderStyleIdParseResult = Readonly<{
+    kind: 'known';
+    id: HeaderStyleId;
+}> | Readonly<{
+    kind: 'unknown';
+    raw: string;
+}> | Readonly<{
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderStyleId(value: string): Exclude<PersistedHeaderStyleIdParseResult, {
+    kind: 'empty';
+}>;
+export declare function parsePersistedHeaderStyleId(value: string | null | undefined): PersistedHeaderStyleIdParseResult;
+export type HeaderLayoutDefinition = Readonly<{
+    id: HeaderLayoutId;
+    label: string;
+    description: string;
+    variant: ThemeHeader['variant'];
+    defaultPositioning: ThemeHeader['positioning'];
+    shrinkOnScroll: boolean;
+    maxRecommendedNavItems?: number;
+    allowedLogoShapes?: readonly HeaderLogoShape[];
+}>;
+export type HeaderStyleNavInteraction = 'color-change' | 'underline-grow' | 'pill-background' | 'flat-block' | 'glass-backed';
+export type HeaderStyleSurface = 'neutral' | 'bordered' | 'soft' | 'brand-solid' | 'floating';
+export type HeaderStyleDepth = 'none' | 'line' | 'shadow';
+export type HeaderStyleMood = 'calm' | 'professional' | 'editorial' | 'expressive' | 'utility';
+export type HeaderStyleDefinition = Readonly<{
+    id: HeaderStyleId;
+    label: string;
+    description: string;
+    supportedLayoutIds: readonly HeaderLayoutId[];
+    navInteraction: HeaderStyleNavInteraction;
+    surface: HeaderStyleSurface;
+    defaultDepth: HeaderStyleDepth;
+    navTypography: HeaderStyleNavTypography;
+    moods: readonly HeaderStyleMood[];
+    openingForegroundTarget?: 'brand-only' | 'all';
+    scrollTreatment?: 'contrast-glass';
+    interactionPalette?: HeaderInteractionPaletteOptionGroup;
+}>;
+export type HeaderLayoutStyleSelection = Readonly<{
+    layoutId: HeaderLayoutId;
+    styleId: HeaderStyleId;
+}>;
+export type HeaderStyleChoiceSource = Readonly<{
+    id: HeaderStyleId;
+}>;
+export type HeaderLayoutChoiceSource = Readonly<{
+    id: HeaderLayoutId;
+}>;
+export type HeaderStyleChoicesByLayout = Readonly<Partial<Record<HeaderLayoutIdValue, readonly HeaderStyleChoiceSource[]>>>;
+export type HeaderLayoutStyleCuration = Readonly<{
+    recommendedHeaderLayoutChoices: readonly HeaderLayoutChoiceSource[];
+    recommendedHeaderStyleChoicesByLayout: HeaderStyleChoicesByLayout;
+}>;
+export type HeaderLegacyLookAlias = Readonly<{
+    lookId: HeaderLookId;
+    selection: HeaderLayoutStyleSelection;
+}>;
+export type HeaderLayoutStyleRepair = Readonly<{
+    requested: HeaderLayoutStyleSelection;
+    resolved: HeaderLayoutStyleSelection;
+    reason: 'style-incompatible-with-layout';
+}>;
+export type HeaderLayoutStyleResolution = Readonly<{
+    kind: 'valid';
+    selection: HeaderLayoutStyleSelection;
+    layout: HeaderLayoutDefinition;
+    style: HeaderStyleDefinition;
+}> | Readonly<{
+    kind: 'repaired';
+    selection: HeaderLayoutStyleSelection;
+    layout: HeaderLayoutDefinition;
+    style: HeaderStyleDefinition;
+    repair: HeaderLayoutStyleRepair;
+}>;
+export type HeaderLookOpeningRequirement = 'none' | 'reserved-space-ok' | 'requires-image-hero-with-contrast-overlay';
+export type HeaderLogoShape = 'none' | 'text-only' | 'horizontal' | 'square' | 'tall';
+export type HeaderLogoDimensions = Readonly<{
+    width: number | null;
+    height: number | null;
+}>;
+export declare function deriveHeaderLogoShapeFromDimensions({ width, height, }: HeaderLogoDimensions): HeaderLogoShape;
+export type HeaderStyleNavTypography = 'plain' | 'heading' | 'quiet-caps' | 'brand-caps';
+export type HeaderLookDefinition = Readonly<{
+    id: HeaderLookId;
+    label: string;
+    openingRequirement: HeaderLookOpeningRequirement;
+    maxRecommendedNavItems?: number;
+    logoAccommodations: readonly LogoAccommodationOption[];
+    requiresProminentCta?: boolean;
+    compile: (theme: Theme) => Theme['header'];
+}>;
+export type HeaderOpeningSectionContext = Readonly<{
+    kind: 'unknown';
+    canAdjust: false;
+}> | Readonly<{
+    kind: 'plain';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'page-background';
+    canAdjust: true;
+}> | Readonly<{
+    kind: 'color-section';
+    contrast: 'light' | 'dark' | 'unknown';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'gradient-section';
+    contrast: 'light' | 'dark' | 'unknown';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'dynamic-media';
+    canAdjust: boolean;
+}> | Readonly<{
+    kind: 'image-hero';
+    hasContrastOverlay: boolean;
+    hasTopSpacing: boolean;
+    canAdjust: boolean;
+}>;
+export type HeaderLogoPreferences = Readonly<{
+    brandDisplayMode?: BrandDisplayMode;
+    sizePolicy?: LogoSizePolicy;
+}>;
+export type HeaderLogoShapeContext = HeaderLogoPreferences & Readonly<{
+    kind?: 'shape';
+    shape: HeaderLogoShape;
+}>;
+export type HeaderLogoFactsContext = HeaderLogoPreferences & Readonly<{
+    kind: 'facts';
+    facts: LogoFacts;
+}>;
+export type HeaderLogoContext = HeaderLogoShapeContext | HeaderLogoFactsContext;
+export type HeaderNavigationContext = Readonly<{
+    itemCount: number;
+}>;
+export type HeaderCtaContext = Readonly<{
+    importance: 'low' | 'medium' | 'high';
+}>;
+export type HeaderBannerContext = Readonly<{
+    persistentVisibility: 'none' | 'possible' | 'visible';
+}>;
+export type HeaderSelectionContext = Readonly<{
+    openingSection: HeaderOpeningSectionContext;
+    openingForeground: HeaderOpeningForeground;
+    logo: HeaderLogoContext;
+    navigation: HeaderNavigationContext;
+    cta: HeaderCtaContext;
+    banner: HeaderBannerContext;
+}>;
+export type RejectedHeaderLookReason = 'requires-image-hero-with-contrast-overlay' | 'too-many-nav-items' | LogoAccommodationRejectionReason | 'cta-treatment-unavailable';
+export type RejectedHeaderLook = Readonly<{
+    lookId: HeaderLookId;
+    reasons: readonly RejectedHeaderLookReason[];
+}>;
+export type HeaderSelectionResult = Readonly<{
+    selectedLookId: HeaderLookId;
+    selectedLook: HeaderLookDefinition;
+    header: Theme['header'];
+    brandPresentation: HeaderBrandPresentationSelection;
+    rejected: readonly RejectedHeaderLook[];
+}>;
+export type HeaderLookResolutionInput = Readonly<{
+    theme: Theme;
+    recommendedLookIds: readonly HeaderLookId[];
+    context?: Partial<HeaderSelectionContext>;
+}>;
+export declare const defaultHeaderSelectionContext: HeaderSelectionContext;
+export declare function completeHeaderSelectionContext(context: Partial<HeaderSelectionContext> | undefined): HeaderSelectionContext;