@riverbankcms/sdk 0.60.0 → 0.60.3

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

@@ -19,19 +19,56 @@ export type HoverColor = 'none' | 'brighten' | 'darken' | 'saturate' | 'token';
 export type ButtonPaddingPreset = 'compact' | 'default' | 'spacious';
 export type GradientStyle = 'linear' | 'radial' | 'conic';
 export type GradientSharpness = 'smooth' | 'medium' | 'hard';
-export type BackgroundTreatment = 'solid' | 'gradient' | 'outline' | 'ghost';
-export type OutlineHoverEffect = 'border-glow' | 'border-shift' | 'border-grow' | 'fill-transition' | 'border-trace';
 export type GradientDirection = 'to-r' | 'to-l' | 'to-t' | 'to-b' | 'to-tr' | 'to-tl' | 'to-br' | 'to-bl';
+export type LetterSpacing = 'tight' | 'normal' | 'loose';
 export type ButtonSizeName = 'sm' | 'md' | 'lg' | 'xl';
 export interface ButtonSizeConfig {
     padding: string;
     fontSize?: string;
 }
-export type ButtonSizes = Partial<Record<ButtonSizeName, ButtonSizeConfig>> & {
-    sm: ButtonSizeConfig;
-    md: ButtonSizeConfig;
-    lg: ButtonSizeConfig;
+export type ButtonSizes = Record<ButtonSizeName, ButtonSizeConfig>;
+/**
+ * Standard semantic variant roles a theme exposes.
+ *
+ * Block content references variants by role; the active theme determines
+ * what each role looks like.
+ */
+export declare const VARIANT_ROLES: readonly ["primary", "secondary", "outline", "ghost", "link", "tertiary", "accent"];
+export type VariantRole = (typeof VARIANT_ROLES)[number];
+declare const SpecialVariantIdBrand: unique symbol;
+/**
+ * Branded ID for theme-specific special variants that don't map to a standard role
+ * (e.g. `banner`, `generous`, `pulse`, `danger`).
+ *
+ * Use `asSpecialVariantId` to construct.
+ */
+export type SpecialVariantId = string & {
+    readonly [SpecialVariantIdBrand]: 'SpecialVariantId';
 };
+export declare function asSpecialVariantId(value: string): SpecialVariantId;
+/**
+ * A variant ID is either a standard role or a branded special ID.
+ *
+ * The zod schema validates at the runtime boundary; types flow through the
+ * codebase without forcing every consumer to brand.
+ */
+export type VariantId = VariantRole | SpecialVariantId;
+/**
+ * Magic alias the CSS generator emits for the highest-priority variant.
+ *
+ * Shared between generator and renderer so neither side hard-codes the string.
+ */
+export declare const DEFAULT_VARIANT_ALIAS_ID: "default";
+export type DefaultVariantAliasId = typeof DEFAULT_VARIANT_ALIAS_ID;
+/**
+ * Per-variant size overrides.
+ *
+ * Every variant participates in the size system. Optional `sizes` on a variant
+ * lets it override individual sizes (e.g. a `link` variant declaring zero
+ * horizontal padding at every size). Sizes not listed fall back to the theme's
+ * `theme.buttons.sizes`, then to the system defaults.
+ */
+export type VariantSizeOverrides = Partial<ButtonSizes>;
 export type ButtonBackground = {
     type: 'solid';
     colorToken: string;
@@ -72,6 +109,11 @@ export declare const buttonTypographySchema: z.ZodEnum<{
     body: "body";
     heading: "heading";
 }>;
+export declare const letterSpacingSchema: z.ZodEnum<{
+    normal: "normal";
+    loose: "loose";
+    tight: "tight";
+}>;
 export declare const hoverTransformSchema: z.ZodEnum<{
     none: "none";
     scale: "scale";
@@ -100,17 +142,34 @@ export declare const gradientSharpnessSchema: z.ZodEnum<{
     smooth: "smooth";
     hard: "hard";
 }>;
+export declare const prioritySchema: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+export declare const variantRoleSchema: z.ZodEnum<{
+    link: "link";
+    primary: "primary";
+    secondary: "secondary";
+    outline: "outline";
+    accent: "accent";
+    ghost: "ghost";
+    tertiary: "tertiary";
+}>;
 export declare const buttonSizeNameSchema: z.ZodEnum<{
     sm: "sm";
     md: "md";
     lg: "lg";
     xl: "xl";
 }>;
+export declare const paddingShorthandSchema: z.ZodString;
 export declare const buttonSizeConfigSchema: z.ZodObject<{
     padding: z.ZodString;
     fontSize: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare const buttonSizesSchema: z.ZodObject<{
+/**
+ * `xl` is optional on the wire so themes persisted before the `xl` size was
+ * added (e.g. SWTS) continue to parse. When `xl` is missing the schema
+ * backfills it from `lg`, keeping `ButtonSizes` a complete `sm/md/lg/xl` map
+ * downstream — generators never need to deal with an undefined `xl`.
+ */
+export declare const buttonSizesSchema: z.ZodPipe<z.ZodObject<{
     sm: z.ZodObject<{
         padding: z.ZodString;
         fontSize: z.ZodOptional<z.ZodString>;
@@ -127,20 +186,41 @@ export declare const buttonSizesSchema: z.ZodObject<{
         padding: z.ZodString;
         fontSize: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-}, z.core.$strip>;
-export declare const backgroundTreatmentSchema: z.ZodEnum<{
-    gradient: "gradient";
-    outline: "outline";
-    solid: "solid";
-    ghost: "ghost";
-}>;
-export declare const outlineHoverEffectSchema: z.ZodEnum<{
-    "border-glow": "border-glow";
-    "border-shift": "border-shift";
-    "border-grow": "border-grow";
-    "fill-transition": "fill-transition";
-    "border-trace": "border-trace";
-}>;
+}, z.core.$strip>, z.ZodTransform<{
+    sm: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+    md: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+    lg: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+    xl: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+}, {
+    sm: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+    md: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+    lg: {
+        padding: string;
+        fontSize?: string | undefined;
+    };
+    xl?: {
+        padding: string;
+        fontSize?: string | undefined;
+    } | undefined;
+}>>;
 export declare const buttonGlobalSettingsSchema: z.ZodObject<{
     cornerStyle: z.ZodEnum<{
         rounded: "rounded";
@@ -166,6 +246,12 @@ export declare const buttonGlobalSettingsSchema: z.ZodObject<{
         body: "body";
         heading: "heading";
     }>>;
+    fontSize: z.ZodOptional<z.ZodString>;
+    letterSpacing: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        loose: "loose";
+        tight: "tight";
+    }>>;
     italic: z.ZodOptional<z.ZodBoolean>;
     paddingPreset: z.ZodOptional<z.ZodEnum<{
         compact: "compact";
@@ -235,29 +321,37 @@ export declare const buttonBorderSchema: z.ZodObject<{
     widthClass: z.ZodString;
     colorToken: z.ZodString;
 }, z.core.$strip>;
-export declare const buttonVariantLegacySchema: z.ZodObject<{
-    id: z.ZodString;
-    name: z.ZodString;
-    enabled: z.ZodBoolean;
-    priority: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
-    backgroundTreatment: z.ZodEnum<{
-        gradient: "gradient";
-        outline: "outline";
-        solid: "solid";
-        ghost: "ghost";
-    }>;
-    color: z.ZodOptional<z.ZodString>;
-    gradientColors: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-    borderColor: z.ZodOptional<z.ZodString>;
-    outlineHoverEffect: z.ZodOptional<z.ZodEnum<{
-        "border-glow": "border-glow";
-        "border-shift": "border-shift";
-        "border-grow": "border-grow";
-        "fill-transition": "fill-transition";
-        "border-trace": "border-trace";
-    }>>;
-    effectPreset: z.ZodOptional<z.ZodString>;
+/**
+ * Per-variant size overrides schema — every entry is optional.
+ *
+ * For each size key present, the values override the theme's `sizes` config
+ * for that size on this variant. Missing sizes fall through to theme.sizes,
+ * then system defaults.
+ */
+export declare const variantSizeOverridesSchema: z.ZodObject<{
+    sm: z.ZodOptional<z.ZodObject<{
+        padding: z.ZodString;
+        fontSize: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    md: z.ZodOptional<z.ZodObject<{
+        padding: z.ZodString;
+        fontSize: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    lg: z.ZodOptional<z.ZodObject<{
+        padding: z.ZodString;
+        fontSize: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    xl: z.ZodOptional<z.ZodObject<{
+        padding: z.ZodString;
+        fontSize: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * Unified variant schema. Every variant participates in the size system; the
+ * optional `sizes` field lets a variant scale differently than the theme
+ * default (e.g. link-style variants declaring zero horizontal padding at
+ * every size).
+ */
 export declare const buttonVariantSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -283,7 +377,7 @@ export declare const buttonVariantSchema: z.ZodObject<{
         type: z.ZodLiteral<"transparent">;
     }, z.core.$strip>], "type">;
     textColorToken: z.ZodString;
-    borderRadius: z.ZodString;
+    borderRadius: z.ZodOptional<z.ZodString>;
     shadow: z.ZodOptional<z.ZodObject<{
         elevation: z.ZodEnum<{
             medium: "medium";
@@ -305,8 +399,6 @@ export declare const buttonVariantSchema: z.ZodObject<{
         widthClass: z.ZodString;
         colorToken: z.ZodString;
     }, z.core.$strip>>;
-    padding: z.ZodOptional<z.ZodString>;
-    fontSize: z.ZodOptional<z.ZodString>;
     hoverBackgroundToken: z.ZodOptional<z.ZodString>;
     effects: z.ZodOptional<z.ZodObject<{
         base: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -326,6 +418,24 @@ export declare const buttonVariantSchema: z.ZodObject<{
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
         }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    sizes: z.ZodOptional<z.ZodObject<{
+        sm: z.ZodOptional<z.ZodObject<{
+            padding: z.ZodString;
+            fontSize: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        md: z.ZodOptional<z.ZodObject<{
+            padding: z.ZodString;
+            fontSize: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        lg: z.ZodOptional<z.ZodObject<{
+            padding: z.ZodString;
+            fontSize: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        xl: z.ZodOptional<z.ZodObject<{
+            padding: z.ZodString;
+            fontSize: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const buttonSystemSchema: z.ZodObject<{
     global: z.ZodObject<{
@@ -353,6 +463,12 @@ export declare const buttonSystemSchema: z.ZodObject<{
             body: "body";
             heading: "heading";
         }>>;
+        fontSize: z.ZodOptional<z.ZodString>;
+        letterSpacing: z.ZodOptional<z.ZodEnum<{
+            normal: "normal";
+            loose: "loose";
+            tight: "tight";
+        }>>;
         italic: z.ZodOptional<z.ZodBoolean>;
         paddingPreset: z.ZodOptional<z.ZodEnum<{
             compact: "compact";
@@ -410,7 +526,7 @@ export declare const buttonSystemSchema: z.ZodObject<{
             type: z.ZodLiteral<"transparent">;
         }, z.core.$strip>], "type">;
         textColorToken: z.ZodString;
-        borderRadius: z.ZodString;
+        borderRadius: z.ZodOptional<z.ZodString>;
         shadow: z.ZodOptional<z.ZodObject<{
             elevation: z.ZodEnum<{
                 medium: "medium";
@@ -432,8 +548,6 @@ export declare const buttonSystemSchema: z.ZodObject<{
             widthClass: z.ZodString;
             colorToken: z.ZodString;
         }, z.core.$strip>>;
-        padding: z.ZodOptional<z.ZodString>;
-        fontSize: z.ZodOptional<z.ZodString>;
         hoverBackgroundToken: z.ZodOptional<z.ZodString>;
         effects: z.ZodOptional<z.ZodObject<{
             base: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -453,8 +567,26 @@ export declare const buttonSystemSchema: z.ZodObject<{
                 options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
             }, z.core.$strip>>>;
         }, z.core.$strip>>;
+        sizes: z.ZodOptional<z.ZodObject<{
+            sm: z.ZodOptional<z.ZodObject<{
+                padding: z.ZodString;
+                fontSize: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            md: z.ZodOptional<z.ZodObject<{
+                padding: z.ZodString;
+                fontSize: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            lg: z.ZodOptional<z.ZodObject<{
+                padding: z.ZodString;
+                fontSize: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            xl: z.ZodOptional<z.ZodObject<{
+                padding: z.ZodString;
+                fontSize: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
-    sizes: z.ZodOptional<z.ZodObject<{
+    sizes: z.ZodOptional<z.ZodPipe<z.ZodObject<{
         sm: z.ZodObject<{
             padding: z.ZodString;
             fontSize: z.ZodOptional<z.ZodString>;
@@ -471,59 +603,108 @@ export declare const buttonSystemSchema: z.ZodObject<{
             padding: z.ZodString;
             fontSize: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodTransform<{
+        sm: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+        md: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+        lg: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+        xl: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+    }, {
+        sm: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+        md: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+        lg: {
+            padding: string;
+            fontSize?: string | undefined;
+        };
+        xl?: {
+            padding: string;
+            fontSize?: string | undefined;
+        } | undefined;
+    }>>>;
 }, z.core.$strip>;
+export type Priority = 1 | 2 | 3;
 export interface ButtonGlobalSettings {
     cornerStyle: CornerStyle;
     cornerRadius?: number;
     shadow: ShadowSize;
     textTransform: TextTransform;
     fontWeight: FontWeight;
+    /** @deprecated See JSDoc on `buttonGlobalSettingsSchema.borderWidth`. */
     borderWidth: 1 | 2 | 3;
+    /** Typography source (body or heading) — picks which theme typography pool to use */
     typography?: ButtonTypography;
+    /** Font size token for all variants in the family (e.g. "text-xs", "text-sm") */
+    fontSize?: string;
+    /** Letter spacing for all variants */
+    letterSpacing?: LetterSpacing;
+    /** Italic style */
     italic?: boolean;
+    /** Padding preset (used as sized-variant default when no sizes config) */
     paddingPreset?: ButtonPaddingPreset;
     hoverTransform: HoverTransform;
     hoverColor: HoverColor;
+    /** When hoverColor is 'token', this specifies which token to use */
     hoverColorToken?: string;
     gradientStyle?: GradientStyle;
     gradientAngle?: number;
     gradientSharpness?: GradientSharpness;
 }
-export interface ButtonVariantLegacy {
-    id: string;
-    name: string;
-    enabled: boolean;
-    priority: 1 | 2 | 3;
-    backgroundTreatment: BackgroundTreatment;
-    color?: string;
-    gradientColors?: [string, string];
-    borderColor?: string;
-    outlineHoverEffect?: OutlineHoverEffect;
-    effectPreset?: string;
+/** Effects per state group */
+export interface VariantEffects {
+    base?: EffectApplication[];
+    hover?: EffectApplication[];
+    active?: EffectApplication[];
+    focus?: EffectApplication[];
 }
+/**
+ * A button variant.
+ *
+ * Every variant participates in the size system (`sm | md | lg | xl`). Padding
+ * and fontSize at each size are resolved by:
+ *   1. `variant.sizes?.[S]` if present
+ *   2. else `theme.buttons.sizes?.[S]`
+ *   3. else the system defaults in `DEFAULT_BUTTON_SIZES`
+ *
+ * Special variants like banner, link, or tag declare per-variant `sizes`
+ * overrides to carry their distinct dimensions through every size. There is
+ * no "fixed kind" — size is universal.
+ */
 export interface ButtonVariant {
     id: string;
     name: string;
     enabled: boolean;
-    priority: 1 | 2 | 3;
+    priority: Priority;
     background: ButtonBackground;
     textColorToken: string;
-    borderRadius: string;
+    /** Tailwind radius token (e.g. `'rounded-md'`). Omit to inherit from `global.cornerStyle`. */
+    borderRadius?: string;
     shadow?: Shadow;
     border?: ButtonBorder;
-    padding?: string;
-    fontSize?: string;
     hoverBackgroundToken?: string;
-    effects?: {
-        base?: EffectApplication[];
-        hover?: EffectApplication[];
-        active?: EffectApplication[];
-        focus?: EffectApplication[];
-    };
+    effects?: VariantEffects;
+    /** Per-variant size overrides. See VariantSizeOverrides. */
+    sizes?: VariantSizeOverrides;
 }
 export interface ButtonSystem {
     global: ButtonGlobalSettings;
     variants: ButtonVariant[];
     sizes?: ButtonSizes;
 }
+export {};