@riverbankcms/sdk 0.130.0 → 0.132.0

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

@@ -9,6 +9,7 @@ export * from './classNames';
 export * from './generateButtonCss';
 export * from './resolveButtonColourStates';
 export * from './buttonSurfaceContext';
+export * from './contextualHover';
 export * from './affordanceIcons';
 export * from './generateDefaultButtonSystem';
 export * from './constants';

package/dist/_dts/theme-core/src/buttons/resolveButtonColourStates.d.ts

@@ -1,4 +1,5 @@
 import type { ButtonGlobalSettings, ButtonVariant, OpaqueButtonColourToken, VariantEffects } from './types';
+import type { ButtonContextualHoverRepair } from './contextualHover';
 import { type ButtonColourContractError, type ButtonColourPalette, type ButtonVisualState, type KnownButtonSurface } from './buttonColourContract';
 export { BUTTON_CONTRAST_POLICY, BUTTON_VISUAL_STATES, formatButtonColourContractError, type ButtonColourContractError, type ButtonColourPalette, type ButtonVisualState, type KnownButtonSurface, } from './buttonColourContract';
 export { classifyButtonEffectId, type ButtonEffectClassification, } from './effectClassification';
@@ -40,10 +41,12 @@ export type ButtonColourContractResult = Readonly<{
     states: ResolvedButtonColourStates;
     focusIndicator: ResolvedButtonFocusIndicator;
     nonColourEffects: VariantEffects;
+    contextualHoverRepair: ButtonContextualHoverRepair | null;
 }> | Readonly<{
     ok: false;
     error: ButtonColourContractError;
 }>;
+export type { ButtonContextualHoverRepair } from './contextualHover';
 export declare function compileButtonColourStates(input: Readonly<{
     variant: ButtonVariant;
     global: ButtonGlobalSettings;

package/dist/_dts/theme-core/src/buttons/resolveButtonHoverTreatment.d.ts

@@ -0,0 +1,14 @@
+import type { ButtonColourPalette, KnownButtonSurface } from './buttonColourContract';
+import { type ButtonContextualHoverRepair } from './contextualHover';
+import type { ButtonColourTreatment, ButtonGlobalSettings, ButtonVariant } from './types';
+export type ResolvedButtonHoverTreatment = Readonly<{
+    treatment: ButtonColourTreatment;
+    repair: ButtonContextualHoverRepair | null;
+}>;
+export declare function resolveButtonHoverTreatment(input: Readonly<{
+    variant: ButtonVariant;
+    global: ButtonGlobalSettings;
+    fallback: ButtonColourTreatment;
+    palette: ButtonColourPalette;
+    surface?: KnownButtonSurface;
+}>): ResolvedButtonHoverTreatment;

package/dist/_dts/theme-core/src/buttons/styles/domain.d.ts

@@ -1,11 +1,11 @@
 import type { z } from 'zod';
 import type { StyleTags } from '../../site-styles/styleTags';
-import type { ButtonGlobalSettings, ButtonSizes, ButtonSurfacePolicy, ButtonSystem, ButtonVariant } from '../types';
+import type { ButtonGlobalSettings, ButtonSizes, ButtonSurfacePolicy, ButtonSystem, ButtonVariant, OpaqueButtonColourToken, VariantRole } from '../types';
 export declare const PUBLIC_BUTTON_ROLES: readonly ["primary", "secondary", "outline", "ghost", "accent"];
-export type PublicButtonRole = (typeof PUBLIC_BUTTON_ROLES)[number];
+export type PublicButtonRole = VariantRole;
 export type CompleteButtonRole = 'primary' | 'secondary';
 export type SupportingButtonRole = Exclude<PublicButtonRole, CompleteButtonRole>;
-export type ButtonVariantAppearance = Readonly<Pick<ButtonVariant, 'background' | 'borderRadius' | 'shadow' | 'border' | 'hoverBackgroundToken' | 'effects' | 'sizes' | 'affordance'>>;
+export type ButtonVariantAppearance = Readonly<Pick<ButtonVariant, 'background' | 'borderRadius' | 'shadow' | 'border' | 'hoverBackgroundToken' | 'contextualHover' | 'effects' | 'sizes' | 'affordance'>>;
 export type PublicButtonVariant<TRole extends PublicButtonRole = PublicButtonRole> = Omit<ButtonVariant, 'id' | 'enabled'> & Readonly<{
     id: TRole;
     enabled: true;
@@ -36,6 +36,23 @@ export type ButtonStyleSystemDefinition = Readonly<{
     surfacePolicy?: ButtonSurfacePolicy;
 }>;
 type StringParameterKey<TParameters> = Extract<keyof TParameters, string>;
+export type ButtonHoverTreatmentValue = 'contextual' | 'secondary' | 'accent';
+type ButtonHoverParameterKey<TParameters> = Extract<{
+    [TKey in keyof TParameters]-?: NonNullable<TParameters[TKey]> extends Partial<Record<VariantRole, ButtonHoverTreatmentValue>> ? TKey : never;
+}[keyof TParameters], string>;
+export type ButtonHoverRoleControl<TParameter extends string = 'hoverPreferences'> = Readonly<{
+    kind: 'button-hover-by-role';
+    parameter: TParameter;
+    label: string;
+    roles: Readonly<Record<VariantRole, Readonly<{
+        contextualSeedToken: OpaqueButtonColourToken;
+        fallbackDirection: 'lighter' | 'darker';
+    }>>>;
+    options: readonly Readonly<{
+        value: ButtonHoverTreatmentValue;
+        label: string;
+    }>[];
+}>;
 export type ButtonStyleControl<TParameters> = {
     [TKey in StringParameterKey<TParameters>]: Readonly<{
         kind: 'choice';
@@ -46,7 +63,7 @@ export type ButtonStyleControl<TParameters> = {
             label: string;
         }>[];
     }>;
-}[StringParameterKey<TParameters>];
+}[StringParameterKey<TParameters>] | (ButtonHoverParameterKey<TParameters> extends never ? never : ButtonHoverRoleControl<ButtonHoverParameterKey<TParameters>>);
 export type ButtonStyleRecipe<TId extends string = string, TParameters = Readonly<Record<string, never>>> = Readonly<{
     id: TId;
     accessibilityLabel: string;

package/dist/_dts/theme-core/src/buttons/styles/recipes/flatInk.d.ts

@@ -0,0 +1,92 @@
+export declare const flatInkRecipe: Readonly<{
+    id: "flat-ink";
+    accessibilityLabel: string;
+    tags: Readonly<Partial<Readonly<{
+        tone: import("../../../../../blocks/src/index").StyleTone;
+        energy: import("../../../../../blocks/src/index").StyleEnergy;
+        motion: import("../../../../../blocks/src/index").StyleMotion;
+        era: import("../../../../../blocks/src/index").StyleEra;
+    }>>>;
+    parameterSchema: import("zod").ZodType<{
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }, unknown, import("zod/v4/core").$ZodTypeInternals<{
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }, unknown>>;
+    defaultParameters: {
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    };
+    controls: readonly import("..").ButtonStyleControl<{
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }>[];
+    defineSystem: (parameters: {
+        hoverPreferences?: {
+            outline?: "accent" | "secondary" | "contextual" | undefined;
+            accent?: "accent" | "secondary" | "contextual" | undefined;
+            primary?: "accent" | "secondary" | "contextual" | undefined;
+            secondary?: "accent" | "secondary" | "contextual" | undefined;
+            ghost?: "accent" | "secondary" | "contextual" | undefined;
+        } | undefined;
+    }) => Readonly<{
+        global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
+        sizes?: import("../..").ButtonSizes;
+        roles: Readonly<{
+            primary: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }>;
+            secondary: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }>;
+            outline: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }> | Readonly<{
+                kind: "derive";
+                from: import("..").CompleteButtonRole;
+                overrides?: Partial<import("..").ButtonVariantAppearance>;
+            }>;
+            ghost: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }> | Readonly<{
+                kind: "derive";
+                from: import("..").CompleteButtonRole;
+                overrides?: Partial<import("..").ButtonVariantAppearance>;
+            }>;
+            accent: Readonly<{
+                kind: "complete";
+                appearance: import("..").ButtonVariantAppearance;
+            }> | Readonly<{
+                kind: "derive";
+                from: import("..").CompleteButtonRole;
+                overrides?: Partial<import("..").ButtonVariantAppearance>;
+            }>;
+        }>;
+        surfacePolicy?: import("../..").ButtonSurfacePolicy;
+    }>;
+}>;

package/dist/_dts/theme-core/src/buttons/styles/recipes/staticRecipes.d.ts

@@ -9,15 +9,7 @@ export declare const softPillRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -69,15 +61,7 @@ export declare const earthPillRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -129,15 +113,7 @@ export declare const confidentChipRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -189,15 +165,7 @@ export declare const editorialLinkRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -249,15 +217,7 @@ export declare const pebbleRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -309,15 +269,7 @@ export declare const brushedWashRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -369,75 +321,7 @@ export declare const inkStampRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
-    defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
-        global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
-        sizes?: import("../..").ButtonSizes;
-        roles: Readonly<{
-            primary: Readonly<{
-                kind: "complete";
-                appearance: import("..").ButtonVariantAppearance;
-            }>;
-            secondary: Readonly<{
-                kind: "complete";
-                appearance: import("..").ButtonVariantAppearance;
-            }>;
-            outline: Readonly<{
-                kind: "complete";
-                appearance: import("..").ButtonVariantAppearance;
-            }> | Readonly<{
-                kind: "derive";
-                from: import("..").CompleteButtonRole;
-                overrides?: Partial<import("..").ButtonVariantAppearance>;
-            }>;
-            ghost: Readonly<{
-                kind: "complete";
-                appearance: import("..").ButtonVariantAppearance;
-            }> | Readonly<{
-                kind: "derive";
-                from: import("..").CompleteButtonRole;
-                overrides?: Partial<import("..").ButtonVariantAppearance>;
-            }>;
-            accent: Readonly<{
-                kind: "complete";
-                appearance: import("..").ButtonVariantAppearance;
-            }> | Readonly<{
-                kind: "derive";
-                from: import("..").CompleteButtonRole;
-                overrides?: Partial<import("..").ButtonVariantAppearance>;
-            }>;
-        }>;
-        surfacePolicy?: import("../..").ButtonSurfacePolicy;
-    }>;
-}>;
-export declare const flatInkRecipe: Readonly<{
-    id: "flat-ink";
-    accessibilityLabel: string;
-    tags: Readonly<Partial<Readonly<{
-        tone: import("../../../../../blocks/src/index").StyleTone;
-        energy: import("../../../../../blocks/src/index").StyleEnergy;
-        motion: import("../../../../../blocks/src/index").StyleMotion;
-        era: import("../../../../../blocks/src/index").StyleEra;
-    }>>>;
-    parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
-    defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -489,15 +373,7 @@ export declare const showtimePillRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -549,15 +425,7 @@ export declare const joyStampRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;
@@ -609,15 +477,7 @@ export declare const ornateRitualRecipe: Readonly<{
     }>>>;
     parameterSchema: import("zod").ZodType<Readonly<Record<string, never>>, unknown, import("zod/v4/core").$ZodTypeInternals<Readonly<Record<string, never>>, unknown>>;
     defaultParameters: Readonly<Record<string, never>>;
-    controls: readonly Readonly<{
-        kind: "choice";
-        parameter: string;
-        label: string;
-        options: readonly Readonly<{
-            value: never;
-            label: string;
-        }>[];
-    }>[];
+    controls: readonly import("..").ButtonStyleControl<Readonly<Record<string, never>>>[];
     defineSystem: (parameters: Readonly<Record<string, never>>) => Readonly<{
         global: import("../../../../../blocks/src/index").ButtonGlobalSettings;
         sizes?: import("../..").ButtonSizes;