@riverbankcms/sdk 0.130.0 → 0.132.0

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

@@ -14,14 +14,30 @@ export type CardSpacing = 'none' | 'compact' | 'cozy' | 'medium' | 'comfortable'
 export type GradientDirection = 'to-r' | 'to-l' | 'to-t' | 'to-b' | 'to-tr' | 'to-tl' | 'to-br' | 'to-bl';
 export declare const cardVariantRoleValues: readonly ["default", "alternative"];
 export declare const boxlessCardVariantValue: "none";
+export declare const openCardRoleValue: "open";
 export type CardVariantRole = (typeof cardVariantRoleValues)[number];
 export type BoxlessCardVariant = typeof boxlessCardVariantValue;
-export type BoxStylesCardVariant = CardVariantRole | BoxlessCardVariant;
-export declare const legacyCardVariantRoleAliases: {
-    readonly variant1: "alternative";
-    readonly variant2: "alternative";
-};
-export type LegacyCardVariantRoleAlias = keyof typeof legacyCardVariantRoleAliases;
+/**
+ * The roles a site style implements with an actual card variant. `none` is
+ * deliberately absent: it is a role value only, never a variant.
+ */
+export declare const surfaceCardRoleValues: readonly ["default", "alternative", "open"];
+export type SurfaceCardRole = (typeof surfaceCardRoleValues)[number];
+/**
+ * The closed role vocabulary Looks and blocks use for surfaced and boxless
+ * card choices.
+ *
+ * - `none`        — no site-style card surface; the block's own composition and
+ *                   the author's own card fields govern the item. This is *not*
+ *                   a promise of visible boxlessness: a block whose base class
+ *                   draws a border still draws one. It says the Look is not
+ *                   asking the site style for a card.
+ * - `open`        — boxless but marked (a rule or accent edge, no enclosing box)
+ * - `default`     — the site's quiet everyday card
+ * - `alternative` — the statement card carrying the site's personality
+ */
+export declare const cardRoleValues: readonly ["default", "alternative", "open", "none"];
+export type CardRole = (typeof cardRoleValues)[number];
 export type CardBackground = {
     type: 'solid';
     colorToken: string;
@@ -33,10 +49,10 @@ export type CardBackground = {
 } | {
     type: 'transparent';
 };
-export interface CardBorder {
+export type CardBorder = {
     widthClass: string;
     colorToken: string;
-}
+};
 export declare const cardSpacingSchema: z.ZodEnum<{
     medium: "medium";
     none: "none";
@@ -45,6 +61,57 @@ export declare const cardSpacingSchema: z.ZodEnum<{
     spacious: "spacious";
     cozy: "cozy";
 }>;
+/** Per-axis padding, for boxless cards whose inline padding differs from block. */
+export declare const cardSpacingAxesSchema: z.ZodObject<{
+    block: z.ZodEnum<{
+        medium: "medium";
+        none: "none";
+        compact: "compact";
+        comfortable: "comfortable";
+        spacious: "spacious";
+        cozy: "cozy";
+    }>;
+    inline: z.ZodEnum<{
+        medium: "medium";
+        none: "none";
+        compact: "compact";
+        comfortable: "comfortable";
+        spacious: "spacious";
+        cozy: "cozy";
+    }>;
+}, z.core.$strip>;
+export type CardSpacingAxes = z.infer<typeof cardSpacingAxesSchema>;
+/**
+ * A card's content padding: one value for both axes, or one per axis. Two
+ * fields would let a variant say both and leave the reader to guess, so this is
+ * a union — the legacy `spacingAxes` key is lifted into it on parse.
+ */
+export declare const cardSpacingValueSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    medium: "medium";
+    none: "none";
+    compact: "compact";
+    comfortable: "comfortable";
+    spacious: "spacious";
+    cozy: "cozy";
+}>, z.ZodObject<{
+    block: z.ZodEnum<{
+        medium: "medium";
+        none: "none";
+        compact: "compact";
+        comfortable: "comfortable";
+        spacious: "spacious";
+        cozy: "cozy";
+    }>;
+    inline: z.ZodEnum<{
+        medium: "medium";
+        none: "none";
+        compact: "compact";
+        comfortable: "comfortable";
+        spacious: "spacious";
+        cozy: "cozy";
+    }>;
+}, z.core.$strip>]>;
+export type CardSpacingValue = z.infer<typeof cardSpacingValueSchema>;
 export declare const gradientDirectionSchema: z.ZodEnum<{
     "to-r": "to-r";
     "to-l": "to-l";
@@ -59,14 +126,30 @@ export declare const cardVariantRoleSchema: z.ZodEnum<{
     default: "default";
     alternative: "alternative";
 }>;
-export declare const boxStylesCardVariantSchema: z.ZodEnum<{
+export declare const surfaceCardRoleSchema: z.ZodEnum<{
+    open: "open";
+    default: "default";
+    alternative: "alternative";
+}>;
+export declare const cardRoleSchema: z.ZodEnum<{
+    open: "open";
     default: "default";
     none: "none";
     alternative: "alternative";
 }>;
 export declare function isCardVariantRole(value: unknown): value is CardVariantRole;
 export declare function normalizeCardVariantRole(value: unknown): CardVariantRole | null;
-export declare function normalizeBoxStylesCardVariant(value: unknown): BoxStylesCardVariant | null;
+/** The one untrusted-input boundary for the closed role vocabulary. */
+export declare function normalizeCardRole(value: unknown): CardRole | null;
+/**
+ * Role inference for legacy card systems authored before variants carried a
+ * `role`. Priority 1 is the everyday card, priority 2 the statement card —
+ * which is how variants are surfaced today. `open` is never inferred: a site
+ * style has to opt into it.
+ */
+export declare function inferCardVariantRoleFromPriority(priority: 1 | 2 | 3): SurfaceCardRole | null;
+/** The role a variant implements, explicit or inferred. */
+export declare function cardVariantRole(variant: Pick<CardVariant, 'role' | 'priority'>): SurfaceCardRole | null;
 export declare const cardBackgroundSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"solid">;
     colorToken: z.ZodString;
@@ -100,9 +183,17 @@ export declare const cardCornerValueSchema: z.ZodEnum<{
     expressive: "expressive";
 }>;
 export type CardCornerValue = z.infer<typeof cardCornerValueSchema>;
+export declare const cardEdgeSchema: z.ZodEnum<{
+    left: "left";
+    right: "right";
+    bottom: "bottom";
+    top: "top";
+}>;
+export type CardEdge = z.infer<typeof cardEdgeSchema>;
 /**
- * A single accented card edge (e.g. a left accent bar). When set, it replaces
- * the full `border` so the card reads as edge-accented rather than outlined.
+ * Legacy single accented card edge (e.g. a left accent bar). Persisted and
+ * curated data may still carry it; it lifts into a one-element `decorations`
+ * list at the parse boundary and has no representation after that.
  */
 export declare const cardAccentEdgeSchema: z.ZodObject<{
     edge: z.ZodEnum<{
@@ -120,6 +211,113 @@ export declare const cardAccentEdgeSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type CardAccentEdge = z.infer<typeof cardAccentEdgeSchema>;
+/** `hairline` (1px) is the widening the boxless `open` role needs. */
+export declare const cardEdgeRuleWidthSchema: z.ZodEnum<{
+    medium: "medium";
+    thin: "thin";
+    thick: "thick";
+    hairline: "hairline";
+    heavy: "heavy";
+}>;
+export type CardEdgeRuleWidth = z.infer<typeof cardEdgeRuleWidthSchema>;
+export declare const cardEdgeRuleLengthSchema: z.ZodEnum<{
+    short: "short";
+    full: "full";
+}>;
+export declare const cardEdgeRuleAlignSchema: z.ZodEnum<{
+    center: "center";
+    end: "end";
+    start: "start";
+}>;
+/**
+ * A rule drawn along one card edge. `full` renders as a border side; `short`
+ * renders as a pseudo-element of a fixed length, which is how a hairline and a
+ * brand accent coexist on the same edge (the `open` role's treatment).
+ */
+export declare const cardEdgeRuleSchema: z.ZodObject<{
+    edge: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        bottom: "bottom";
+        top: "top";
+    }>;
+    colorToken: z.ZodString;
+    width: z.ZodEnum<{
+        medium: "medium";
+        thin: "thin";
+        thick: "thick";
+        hairline: "hairline";
+        heavy: "heavy";
+    }>;
+    length: z.ZodOptional<z.ZodEnum<{
+        short: "short";
+        full: "full";
+    }>>;
+    align: z.ZodOptional<z.ZodEnum<{
+        center: "center";
+        end: "end";
+        start: "start";
+    }>>;
+    alpha: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CardEdgeRule = z.infer<typeof cardEdgeRuleSchema>;
+/**
+ * Decorations are edge rules today. The alias exists so the list can grow into
+ * a discriminated union without every call site changing.
+ */
+export declare const cardDecorationSchema: z.ZodObject<{
+    edge: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        bottom: "bottom";
+        top: "top";
+    }>;
+    colorToken: z.ZodString;
+    width: z.ZodEnum<{
+        medium: "medium";
+        thin: "thin";
+        thick: "thick";
+        hairline: "hairline";
+        heavy: "heavy";
+    }>;
+    length: z.ZodOptional<z.ZodEnum<{
+        short: "short";
+        full: "full";
+    }>>;
+    align: z.ZodOptional<z.ZodEnum<{
+        center: "center";
+        end: "end";
+        start: "start";
+    }>>;
+    alpha: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CardDecoration = CardEdgeRule;
+export declare const cardDecorationsSchema: z.ZodArray<z.ZodObject<{
+    edge: z.ZodEnum<{
+        left: "left";
+        right: "right";
+        bottom: "bottom";
+        top: "top";
+    }>;
+    colorToken: z.ZodString;
+    width: z.ZodEnum<{
+        medium: "medium";
+        thin: "thin";
+        thick: "thick";
+        hairline: "hairline";
+        heavy: "heavy";
+    }>;
+    length: z.ZodOptional<z.ZodEnum<{
+        short: "short";
+        full: "full";
+    }>>;
+    align: z.ZodOptional<z.ZodEnum<{
+        center: "center";
+        end: "end";
+        start: "start";
+    }>>;
+    alpha: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
 export declare const cardCornerRadiiSchema: z.ZodObject<{
     topLeft: z.ZodOptional<z.ZodEnum<{
         soft: "soft";
@@ -151,11 +349,16 @@ export declare const cardCornerRadiiSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type CardCornerRadii = z.infer<typeof cardCornerRadiiSchema>;
-export declare const cardVariantSchema: z.ZodObject<{
+export declare const cardVariantSchema: z.ZodPipe<z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
     enabled: z.ZodBoolean;
     priority: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+    role: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        default: "default";
+        alternative: "alternative";
+    }>>;
     background: z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"solid">;
         colorToken: z.ZodString;
@@ -176,14 +379,49 @@ export declare const cardVariantSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"transparent">;
     }, z.core.$strip>], "type">;
-    spacing: z.ZodEnum<{
+    spacing: z.ZodUnion<readonly [z.ZodEnum<{
         medium: "medium";
         none: "none";
         compact: "compact";
         comfortable: "comfortable";
         spacious: "spacious";
         cozy: "cozy";
-    }>;
+    }>, z.ZodObject<{
+        block: z.ZodEnum<{
+            medium: "medium";
+            none: "none";
+            compact: "compact";
+            comfortable: "comfortable";
+            spacious: "spacious";
+            cozy: "cozy";
+        }>;
+        inline: z.ZodEnum<{
+            medium: "medium";
+            none: "none";
+            compact: "compact";
+            comfortable: "comfortable";
+            spacious: "spacious";
+            cozy: "cozy";
+        }>;
+    }, z.core.$strip>]>;
+    spacingAxes: z.ZodOptional<z.ZodObject<{
+        block: z.ZodEnum<{
+            medium: "medium";
+            none: "none";
+            compact: "compact";
+            comfortable: "comfortable";
+            spacious: "spacious";
+            cozy: "cozy";
+        }>;
+        inline: z.ZodEnum<{
+            medium: "medium";
+            none: "none";
+            compact: "compact";
+            comfortable: "comfortable";
+            spacious: "spacious";
+            cozy: "cozy";
+        }>;
+    }, z.core.$strip>>;
     foregroundToken: z.ZodOptional<z.ZodString>;
     shadow: z.ZodOptional<z.ZodObject<{
         elevation: z.ZodEnum<{
@@ -242,6 +480,32 @@ export declare const cardVariantSchema: z.ZodObject<{
         widthClass: z.ZodString;
         colorToken: z.ZodString;
     }, z.core.$strip>>;
+    decorations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        edge: z.ZodEnum<{
+            left: "left";
+            right: "right";
+            bottom: "bottom";
+            top: "top";
+        }>;
+        colorToken: z.ZodString;
+        width: z.ZodEnum<{
+            medium: "medium";
+            thin: "thin";
+            thick: "thick";
+            hairline: "hairline";
+            heavy: "heavy";
+        }>;
+        length: z.ZodOptional<z.ZodEnum<{
+            short: "short";
+            full: "full";
+        }>>;
+        align: z.ZodOptional<z.ZodEnum<{
+            center: "center";
+            end: "end";
+            start: "start";
+        }>>;
+        alpha: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
     accentEdge: z.ZodOptional<z.ZodObject<{
         edge: z.ZodEnum<{
             left: "left";
@@ -257,13 +521,73 @@ export declare const cardVariantSchema: z.ZodObject<{
             heavy: "heavy";
         }>;
     }, z.core.$strip>>;
-}, z.core.$strip>;
-export declare const cardSystemSchema: z.ZodObject<{
-    variants: z.ZodArray<z.ZodObject<{
+}, z.core.$strip>, z.ZodTransform<CardVariant, {
+    id: string;
+    name: string;
+    enabled: boolean;
+    priority: 1 | 3 | 2;
+    background: {
+        type: "solid";
+        colorToken: string;
+    } | {
+        type: "gradient";
+        fromToken: string;
+        toToken: string;
+        direction: "to-r" | "to-l" | "to-t" | "to-b" | "to-tr" | "to-tl" | "to-br" | "to-bl";
+    } | {
+        type: "transparent";
+    };
+    spacing: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy" | {
+        block: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+        inline: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+    };
+    role?: "open" | "default" | "alternative" | undefined;
+    spacingAxes?: {
+        block: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+        inline: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+    } | undefined;
+    foregroundToken?: string | undefined;
+    shadow?: {
+        elevation: "medium" | "none" | "high" | "low";
+        softness: "crisp" | "soft" | "hard" | null;
+        position: "bottom" | "bottom-right";
+    } | undefined;
+    corners?: "soft" | "square" | "rounded" | "pill" | undefined;
+    cornerRadii?: {
+        topLeft?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+        topRight?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+        bottomLeft?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+        bottomRight?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+    } | undefined;
+    border?: {
+        widthClass: string;
+        colorToken: string;
+    } | undefined;
+    decorations?: {
+        edge: "left" | "right" | "bottom" | "top";
+        colorToken: string;
+        width: "medium" | "thin" | "thick" | "hairline" | "heavy";
+        length?: "short" | "full" | undefined;
+        align?: "center" | "end" | "start" | undefined;
+        alpha?: number | undefined;
+    }[] | undefined;
+    accentEdge?: {
+        edge: "left" | "right" | "bottom" | "top";
+        colorToken: string;
+        width: "medium" | "thin" | "thick" | "heavy";
+    } | undefined;
+}>>;
+export declare const cardSystemSchema: z.ZodPipe<z.ZodObject<{
+    variants: z.ZodArray<z.ZodPipe<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
         enabled: z.ZodBoolean;
         priority: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>;
+        role: z.ZodOptional<z.ZodEnum<{
+            open: "open";
+            default: "default";
+            alternative: "alternative";
+        }>>;
         background: z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"solid">;
             colorToken: z.ZodString;
@@ -284,14 +608,49 @@ export declare const cardSystemSchema: z.ZodObject<{
         }, z.core.$strip>, z.ZodObject<{
             type: z.ZodLiteral<"transparent">;
         }, z.core.$strip>], "type">;
-        spacing: z.ZodEnum<{
+        spacing: z.ZodUnion<readonly [z.ZodEnum<{
             medium: "medium";
             none: "none";
             compact: "compact";
             comfortable: "comfortable";
             spacious: "spacious";
             cozy: "cozy";
-        }>;
+        }>, z.ZodObject<{
+            block: z.ZodEnum<{
+                medium: "medium";
+                none: "none";
+                compact: "compact";
+                comfortable: "comfortable";
+                spacious: "spacious";
+                cozy: "cozy";
+            }>;
+            inline: z.ZodEnum<{
+                medium: "medium";
+                none: "none";
+                compact: "compact";
+                comfortable: "comfortable";
+                spacious: "spacious";
+                cozy: "cozy";
+            }>;
+        }, z.core.$strip>]>;
+        spacingAxes: z.ZodOptional<z.ZodObject<{
+            block: z.ZodEnum<{
+                medium: "medium";
+                none: "none";
+                compact: "compact";
+                comfortable: "comfortable";
+                spacious: "spacious";
+                cozy: "cozy";
+            }>;
+            inline: z.ZodEnum<{
+                medium: "medium";
+                none: "none";
+                compact: "compact";
+                comfortable: "comfortable";
+                spacious: "spacious";
+                cozy: "cozy";
+            }>;
+        }, z.core.$strip>>;
         foregroundToken: z.ZodOptional<z.ZodString>;
         shadow: z.ZodOptional<z.ZodObject<{
             elevation: z.ZodEnum<{
@@ -350,6 +709,32 @@ export declare const cardSystemSchema: z.ZodObject<{
             widthClass: z.ZodString;
             colorToken: z.ZodString;
         }, z.core.$strip>>;
+        decorations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            edge: z.ZodEnum<{
+                left: "left";
+                right: "right";
+                bottom: "bottom";
+                top: "top";
+            }>;
+            colorToken: z.ZodString;
+            width: z.ZodEnum<{
+                medium: "medium";
+                thin: "thin";
+                thick: "thick";
+                hairline: "hairline";
+                heavy: "heavy";
+            }>;
+            length: z.ZodOptional<z.ZodEnum<{
+                short: "short";
+                full: "full";
+            }>>;
+            align: z.ZodOptional<z.ZodEnum<{
+                center: "center";
+                end: "end";
+                start: "start";
+            }>>;
+            alpha: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
         accentEdge: z.ZodOptional<z.ZodObject<{
             edge: z.ZodEnum<{
                 left: "left";
@@ -365,22 +750,83 @@ export declare const cardSystemSchema: z.ZodObject<{
                 heavy: "heavy";
             }>;
         }, z.core.$strip>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export interface CardVariant {
+    }, z.core.$strip>, z.ZodTransform<CardVariant, {
+        id: string;
+        name: string;
+        enabled: boolean;
+        priority: 1 | 3 | 2;
+        background: {
+            type: "solid";
+            colorToken: string;
+        } | {
+            type: "gradient";
+            fromToken: string;
+            toToken: string;
+            direction: "to-r" | "to-l" | "to-t" | "to-b" | "to-tr" | "to-tl" | "to-br" | "to-bl";
+        } | {
+            type: "transparent";
+        };
+        spacing: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy" | {
+            block: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+            inline: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+        };
+        role?: "open" | "default" | "alternative" | undefined;
+        spacingAxes?: {
+            block: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+            inline: "medium" | "none" | "compact" | "comfortable" | "spacious" | "cozy";
+        } | undefined;
+        foregroundToken?: string | undefined;
+        shadow?: {
+            elevation: "medium" | "none" | "high" | "low";
+            softness: "crisp" | "soft" | "hard" | null;
+            position: "bottom" | "bottom-right";
+        } | undefined;
+        corners?: "soft" | "square" | "rounded" | "pill" | undefined;
+        cornerRadii?: {
+            topLeft?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+            topRight?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+            bottomLeft?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+            bottomRight?: "soft" | "square" | "rounded" | "pill" | "expressive" | undefined;
+        } | undefined;
+        border?: {
+            widthClass: string;
+            colorToken: string;
+        } | undefined;
+        decorations?: {
+            edge: "left" | "right" | "bottom" | "top";
+            colorToken: string;
+            width: "medium" | "thin" | "thick" | "hairline" | "heavy";
+            length?: "short" | "full" | undefined;
+            align?: "center" | "end" | "start" | undefined;
+            alpha?: number | undefined;
+        }[] | undefined;
+        accentEdge?: {
+            edge: "left" | "right" | "bottom" | "top";
+            colorToken: string;
+            width: "medium" | "thin" | "thick" | "heavy";
+        } | undefined;
+    }>>>;
+}, z.core.$strip>, z.ZodTransform<CardSystem, {
+    variants: CardVariant[];
+}>>;
+export type CardVariant = {
     id: string;
     name: string;
     enabled: boolean;
     priority: 1 | 2 | 3;
+    /** Falls back to `priority`-based inference when absent. */
+    role?: SurfaceCardRole;
     background: CardBackground;
-    spacing: CardSpacing;
+    /** One value for both axes, or one per axis. */
+    spacing: CardSpacingValue;
     foregroundToken?: string;
     shadow?: Shadow;
     corners?: 'square' | 'soft' | 'rounded' | 'pill';
     cornerRadii?: CardCornerRadii;
     border?: CardBorder;
-    accentEdge?: CardAccentEdge;
-}
-export interface CardSystem {
+    /** Edge rules drawn on the card. At most two. */
+    decorations?: CardDecoration[];
+};
+export type CardSystem = {
     variants: CardVariant[];
-}
+};