@riverbankcms/sdk 0.130.2 → 0.132.0

package/dist/server/theme.mjs

@@ -783,6 +783,12 @@ const opaqueButtonColourTokenSchema = themeColorTokenSchema.refine((value) => pa
 	if (token === null) throw new Error("Invariant: opaque button token passed its schema");
 	return token;
 });
+const contextualButtonHoverSchema = z.strictObject({
+	kind: z.literal("shade-shift"),
+	seedToken: opaqueButtonColourTokenSchema,
+	fallbackDirection: z.enum(["lighter", "darker"]),
+	preferredToken: opaqueButtonColourTokenSchema.optional()
+});
 const buttonShadeAmountSchema = z.number().finite().min(0).max(900).multipleOf(100);
 const buttonShadowIntensitySchema = z.enum([
 	"subtle",
@@ -1122,6 +1128,7 @@ const buttonVariantSchema = z.strictObject({
 	shadow: variantShadowSchema.optional(),
 	border: buttonBorderSchema.optional(),
 	hoverBackgroundToken: opaqueButtonColourTokenSchema.optional(),
+	contextualHover: contextualButtonHoverSchema.optional(),
 	effects: variantEffectsSchema.optional(),
 	sizes: variantSizeOverridesSchema.optional(),
 	affordance: buttonVariantAffordanceSchema.optional()
@@ -1361,6 +1368,139 @@ function validateButtonTextContrast(input) {
 	};
 }
 //#endregion
+//#region ../theme-core/src/buttons/contextualHover.ts
+function resolveContextualHoverPreference(input) {
+	const preferred = input.instruction.preferredToken;
+	if (preferred && isSafeCandidate(preferred, input.palette, input.surface)) return {
+		kind: "resolved",
+		token: preferred,
+		repair: null
+	};
+	const contextual = resolveContextualHover(input);
+	return contextual.kind === "resolved" ? {
+		kind: "resolved",
+		token: contextual.token,
+		repair: preferred ? {
+			kind: "preferred-token-replaced",
+			preferredToken: preferred,
+			contextualToken: contextual.token
+		} : null
+	} : contextual;
+}
+/**
+* Resolves semantic shade movement from real palette steps. The persisted
+* instruction owns the colour family and deterministic unknown-surface
+* fallback; a proven surface may select the opposite direction when it gives
+* the button stronger separation while retaining the shared contrast contract.
+*/
+function resolveContextualHover(input) {
+	const candidates = shadeCandidates(input.instruction.seedToken, input.palette);
+	if (candidates.length === 0) return {
+		kind: "unavailable",
+		reason: "no-distinct-shade"
+	};
+	const textSafe = candidates.filter((candidate) => hasSafeTextContrast(candidate.token, input.palette));
+	if (textSafe.length === 0) return {
+		kind: "unavailable",
+		reason: "no-text-safe-candidate"
+	};
+	if (!input.surface) {
+		const selected = textSafe.find((candidate) => candidate.direction === input.instruction.fallbackDirection) ?? textSafe[0];
+		return selected ? {
+			kind: "resolved",
+			token: selected.token,
+			direction: selected.direction,
+			evidence: "fallback-direction"
+		} : {
+			kind: "unavailable",
+			reason: "no-text-safe-candidate"
+		};
+	}
+	const selected = textSafe.map((candidate) => ({
+		...candidate,
+		surfaceContrast: contrastRatio(input.palette[candidate.token] ?? "", input.surface?.backgroundHex ?? "")
+	})).filter((candidate) => candidate.surfaceContrast !== null && candidate.surfaceContrast >= BUTTON_CONTRAST_POLICY.nonTextMinimumRatio).sort((left, right) => {
+		const distanceDifference = left.distance - right.distance;
+		if (distanceDifference !== 0) return distanceDifference;
+		const contrastDifference = (right.surfaceContrast ?? 0) - (left.surfaceContrast ?? 0);
+		if (contrastDifference !== 0) return contrastDifference;
+		if (left.direction === right.direction) return left.token.localeCompare(right.token);
+		return left.direction === input.instruction.fallbackDirection ? -1 : 1;
+	})[0];
+	return selected ? {
+		kind: "resolved",
+		token: selected.token,
+		direction: selected.direction,
+		evidence: "known-surface"
+	} : {
+		kind: "unavailable",
+		reason: "no-surface-safe-candidate"
+	};
+}
+function shadeCandidates(seedToken, palette) {
+	const match = String(seedToken).match(/^(.*?)(?:-(\d{2,3}))?$/);
+	const family = match?.[1] ?? String(seedToken);
+	const currentShade = match?.[2] ? Number(match[2]) : 500;
+	const seedHex = palette[seedToken];
+	const shades = Object.keys(palette).flatMap((token) => {
+		const shade = token.match(new RegExp(`^${escapeRegExp(family)}-(\\d{2,3})$`));
+		return shade?.[1] ? [Number(shade[1])] : [];
+	}).filter((shade) => Number.isFinite(shade)).sort((left, right) => left - right);
+	const lower = [...shades].filter((shade) => shade < currentShade).sort((left, right) => right - left);
+	const higher = shades.filter((shade) => shade > currentShade);
+	return [...lower.map((shade) => candidate(family, shade, currentShade, "lighter", seedHex, palette)), ...higher.map((shade) => candidate(family, shade, currentShade, "darker", seedHex, palette))].filter((value) => value !== null);
+}
+function candidate(family, shade, currentShade, direction, seedHex, palette) {
+	const token = parseOpaqueButtonColourToken(`${family}-${shade}`);
+	if (token === null) return null;
+	const candidateHex = palette[token];
+	if (!candidateHex || candidateHex === seedHex) return null;
+	return {
+		token,
+		direction,
+		distance: Math.abs(shade - currentShade),
+		surfaceContrast: null
+	};
+}
+function hasSafeTextContrast(token, palette) {
+	const background = palette[token];
+	const foreground = palette[onColorTokenName(token)];
+	return typeof background === "string" && typeof foreground === "string" && contrastRatio(background, foreground) >= BUTTON_CONTRAST_POLICY.textMinimumRatio;
+}
+function isSafeCandidate(token, palette, surface) {
+	if (!hasSafeTextContrast(token, palette)) return false;
+	return surface ? contrastRatio(palette[token] ?? "", surface.backgroundHex) >= BUTTON_CONTRAST_POLICY.nonTextMinimumRatio : true;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region ../theme-core/src/buttons/resolveButtonHoverTreatment.ts
+function resolveButtonHoverTreatment(input) {
+	if (input.variant.contextualHover) {
+		const contextual = resolveContextualHoverPreference({
+			instruction: input.variant.contextualHover,
+			palette: input.palette,
+			surface: input.surface
+		});
+		if (contextual.kind === "resolved") return {
+			treatment: {
+				type: "solid",
+				colorToken: contextual.token
+			},
+			repair: contextual.repair
+		};
+	}
+	const token = input.variant.hoverBackgroundToken ?? (input.global.hoverColor === "token" ? input.global.hoverColorToken : void 0);
+	return {
+		treatment: token === void 0 ? input.fallback : {
+			type: "solid",
+			colorToken: token
+		},
+		repair: null
+	};
+}
+//#endregion
 //#region ../theme-core/src/buttons/resolveButtonColourStates.ts
 function compileButtonColourStates(input) {
 	const baseTransition = applyColourEffects({
@@ -1371,9 +1511,16 @@ function compileButtonColourStates(input) {
 		palette: input.palette
 	});
 	if (!baseTransition.ok) return baseTransition;
+	const hover = resolveButtonHoverTreatment({
+		variant: input.variant,
+		global: input.global,
+		fallback: baseTransition.treatment,
+		palette: input.palette,
+		surface: input.surface
+	});
 	const stateTreatments = {
 		base: baseTransition.treatment,
-		hover: hoverTreatment(input.variant, input.global, baseTransition.treatment),
+		hover: hover.treatment,
 		focus: baseTransition.treatment,
 		active: baseTransition.treatment,
 		disabled: baseTransition.treatment
@@ -1412,14 +1559,8 @@ function compileButtonColourStates(input) {
 		ok: true,
 		states: resolved,
 		focusIndicator: resolveFocusIndicator(resolved.focus),
-		nonColourEffects
-	};
-}
-function hoverTreatment(variant, global, fallback) {
-	const token = variant.hoverBackgroundToken ?? (global.hoverColor === "token" ? global.hoverColorToken : void 0);
-	return token === void 0 ? fallback : {
-		type: "solid",
-		colorToken: token
+		nonColourEffects,
+		contextualHoverRepair: hover.repair
 	};
 }
 function applyColourEffects(input) {
@@ -1833,13 +1974,7 @@ const tokenOrCssColorValueSchema = z.string();
 buttonSizeNameSchema.options;
 //#endregion
 //#region ../theme-core/src/buttons/styles/domain.ts
-const PUBLIC_BUTTON_ROLES = [
-	"primary",
-	"secondary",
-	"outline",
-	"ghost",
-	"accent"
-];
+const PUBLIC_BUTTON_ROLES = VARIANT_ROLES;
 function defineButtonStyleRecipe(recipe) {
 	return recipe;
 }
@@ -1935,6 +2070,14 @@ const BUTTON_STYLE_IDS = [
 	"quiet-arrow"
 ];
 const quietArrowParametersSchema = z.object({ secondaryTreatment: z.enum(["outlined", "solid-accent"]) }).strict();
+const flatInkHoverTreatmentSchema = z.enum([
+	"contextual",
+	"secondary",
+	"accent"
+]);
+const flatInkHoverPreferencesShape = Object.fromEntries(VARIANT_ROLES.map((role) => [role, flatInkHoverTreatmentSchema.optional()]));
+const flatInkHoverPreferencesSchema = z.strictObject(flatInkHoverPreferencesShape);
+const flatInkParametersSchema = z.strictObject({ hoverPreferences: flatInkHoverPreferencesSchema.optional() });
 const emptyParametersSchema$1 = z.object({}).strict();
 function selectionBranch(styleId, parameters) {
 	return z.object({
@@ -1949,7 +2092,7 @@ z.discriminatedUnion("styleId", [
 	selectionBranch("editorial-link", emptyParametersSchema$1),
 	selectionBranch("pebble", emptyParametersSchema$1),
 	selectionBranch("ink-stamp", emptyParametersSchema$1),
-	selectionBranch("flat-ink", emptyParametersSchema$1),
+	selectionBranch("flat-ink", flatInkParametersSchema),
 	selectionBranch("brushed-wash", emptyParametersSchema$1),
 	selectionBranch("showtime-pill", emptyParametersSchema$1),
 	selectionBranch("joy-stamp", emptyParametersSchema$1),
@@ -2086,6 +2229,189 @@ const quietArrowRecipe = defineButtonStyleRecipe({
 	})
 });
 //#endregion
+//#region ../theme-core/src/buttons/styles/recipes/flatInk.ts
+const contextualRoleConfig = {
+	primary: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("primary"),
+		fallbackDirection: "darker"
+	},
+	secondary: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("surfaceAlt"),
+		fallbackDirection: "darker"
+	},
+	outline: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("surfaceAlt"),
+		fallbackDirection: "darker"
+	},
+	ghost: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("surfaceAlt"),
+		fallbackDirection: "darker"
+	},
+	accent: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("accent"),
+		fallbackDirection: "darker"
+	}
+};
+const hoverControl = {
+	kind: "button-hover-by-role",
+	parameter: "hoverPreferences",
+	label: "Button hover",
+	roles: contextualRoleConfig,
+	options: [
+		{
+			value: "contextual",
+			label: "Contextual shade shift"
+		},
+		{
+			value: "secondary",
+			label: "Secondary button colour"
+		},
+		{
+			value: "accent",
+			label: "Accent button colour"
+		}
+	]
+};
+const lift = { effectId: "lift" };
+const flatInkRecipe = defineButtonStyleRecipe({
+	id: "flat-ink",
+	accessibilityLabel: "Flat rounded buttons with arrow affordances",
+	tags: {
+		tone: "classic",
+		energy: "calm",
+		motion: "subtle",
+		era: "editorial"
+	},
+	parameterSchema: flatInkParametersSchema,
+	defaultParameters: {},
+	controls: [hoverControl],
+	defineSystem: (parameters) => ({
+		global: {
+			cornerStyle: "rounded",
+			textTransform: "none",
+			fontWeight: 600,
+			typography: "body",
+			letterSpacing: "tight",
+			paddingPreset: "default",
+			hoverTransform: "lift",
+			hoverColor: "none"
+		},
+		sizes: {
+			sm: {
+				padding: "0.625rem 1.125rem",
+				fontSize: "text-sm"
+			},
+			md: { padding: "0.8125rem 1.375rem" },
+			lg: {
+				padding: "0.9375rem 1.625rem",
+				fontSize: "text-lg"
+			},
+			xl: {
+				padding: "1.0625rem 2rem",
+				fontSize: "text-xl"
+			}
+		},
+		roles: {
+			primary: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "solid",
+						colorToken: unsafeAsOpaqueButtonColourToken("primary")
+					},
+					borderRadius: "rounded-lg",
+					affordance: { iconId: "ArrowRight" },
+					...hoverAppearance("primary", parameters, [lift, {
+						effectId: "background-on-hover",
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("secondary") }
+					}])
+				}
+			},
+			secondary: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "surface",
+						role: "link"
+					},
+					borderRadius: "rounded-lg",
+					border: { widthClass: "border" },
+					...hoverAppearance("secondary", parameters, [lift, {
+						effectId: "background-on-hover",
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
+					}])
+				}
+			},
+			outline: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "surface",
+						role: "link"
+					},
+					borderRadius: "rounded-lg",
+					border: { widthClass: "border" },
+					...hoverAppearance("outline", parameters, [lift, {
+						effectId: "background-on-hover",
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
+					}])
+				}
+			},
+			ghost: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "surface",
+						role: "link"
+					},
+					borderRadius: "rounded-lg",
+					...hoverAppearance("ghost", parameters, [lift])
+				}
+			},
+			accent: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "solid",
+						colorToken: unsafeAsOpaqueButtonColourToken("accent")
+					},
+					borderRadius: "rounded-lg",
+					affordance: { iconId: "ArrowRight" },
+					...hoverAppearance("accent", parameters, [lift])
+				}
+			}
+		}
+	})
+});
+function hoverAppearance(role, parameters, recommended) {
+	const preference = parameters.hoverPreferences?.[role];
+	if (preference === void 0) return { effects: { hover: [...recommended] } };
+	if (preference === "contextual") {
+		const config = contextualRoleConfig[role];
+		return {
+			effects: { hover: [lift] },
+			contextualHover: {
+				kind: "shade-shift",
+				seedToken: config.contextualSeedToken,
+				fallbackDirection: config.fallbackDirection
+			}
+		};
+	}
+	const config = contextualRoleConfig[role];
+	return {
+		effects: { hover: [lift] },
+		contextualHover: {
+			kind: "shade-shift",
+			seedToken: config.contextualSeedToken,
+			fallbackDirection: config.fallbackDirection,
+			preferredToken: unsafeAsOpaqueButtonColourToken(paletteRole(preference))
+		}
+	};
+}
+function paletteRole(preference) {
+	return preference;
+}
+//#endregion
 //#region ../theme-core/src/buttons/styles/recipes/defineStaticButtonStyleRecipe.ts
 const emptyParametersSchema = z.object({}).strict();
 function defineStaticButtonStyleRecipe(input) {
@@ -2932,113 +3258,6 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 		}
 	}
 });
-const flatInkRecipe = defineStaticButtonStyleRecipe({
-	id: "flat-ink",
-	accessibilityLabel: "Flat rounded buttons with arrow affordances",
-	tags: {
-		tone: "classic",
-		energy: "calm",
-		motion: "subtle",
-		era: "editorial"
-	},
-	system: {
-		global: {
-			cornerStyle: "rounded",
-			textTransform: "none",
-			fontWeight: 600,
-			typography: "body",
-			letterSpacing: "tight",
-			paddingPreset: "default",
-			hoverTransform: "lift",
-			hoverColor: "none"
-		},
-		sizes: {
-			sm: {
-				padding: "0.625rem 1.125rem",
-				fontSize: "text-sm"
-			},
-			md: { padding: "0.8125rem 1.375rem" },
-			lg: {
-				padding: "0.9375rem 1.625rem",
-				fontSize: "text-lg"
-			},
-			xl: {
-				padding: "1.0625rem 2rem",
-				fontSize: "text-xl"
-			}
-		},
-		roles: {
-			primary: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "solid",
-						colorToken: "primary"
-					},
-					borderRadius: "rounded-lg",
-					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{ effectId: "lift" }, {
-						effectId: "background-on-hover",
-						options: { colorToken: unsafeAsOpaqueButtonColourToken("secondary") }
-					}] }
-				}
-			},
-			secondary: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "surface",
-						role: "link"
-					},
-					borderRadius: "rounded-lg",
-					border: { widthClass: "border" },
-					effects: { hover: [{ effectId: "lift" }, {
-						effectId: "background-on-hover",
-						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
-					}] }
-				}
-			},
-			outline: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "surface",
-						role: "link"
-					},
-					borderRadius: "rounded-lg",
-					border: { widthClass: "border" },
-					effects: { hover: [{ effectId: "lift" }, {
-						effectId: "background-on-hover",
-						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
-					}] }
-				}
-			},
-			ghost: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "surface",
-						role: "link"
-					},
-					borderRadius: "rounded-lg",
-					effects: { hover: [{ effectId: "lift" }] }
-				}
-			},
-			accent: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "solid",
-						colorToken: "accent"
-					},
-					borderRadius: "rounded-lg",
-					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{ effectId: "lift" }] }
-				}
-			}
-		}
-	}
-});
 const showtimePillRecipe = defineStaticButtonStyleRecipe({
 	id: "showtime-pill",
 	accessibilityLabel: "Bold uppercase pill buttons with playful movement",
@@ -3460,8 +3679,8 @@ const openCardRoleValue = "open";
 */
 const surfaceCardRoleValues = [...cardVariantRoleValues, openCardRoleValue];
 /**
-* The closed card-role vocabulary Looks and blocks address cards by — this is
-* `BoxStylesCardVariant` widened with `open`, not a parallel enum.
+* 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*
@@ -3505,11 +3724,6 @@ const gradientDirectionSchema = z.enum([
 z.enum(cardVariantRoleValues);
 const surfaceCardRoleSchema = z.enum(surfaceCardRoleValues);
 const cardRoleSchema = z.enum(cardRoleValues);
-/**
-* Historical name for the role vocabulary as it reaches box styles. Widened to
-* the full `CardRole` set — old values keep parsing, `open` now parses too.
-*/
-const boxStylesCardVariantSchema = cardRoleSchema;
 const PRIORITY_ROLE_INFERENCE = {
 	1: "default",
 	2: "alternative"
@@ -4906,8 +5120,7 @@ const cardStylesOverrideSchema = z.object({
 	spacing: semanticSpacingSchema.nullable().optional(),
 	raised: z.boolean().nullable().optional(),
 	rounded: boxRoundedSchema.nullable().optional(),
-	role: cardRoleSchema.nullable().optional(),
-	cardVariant: boxStylesCardVariantSchema.nullable().optional()
+	role: cardRoleSchema.nullable().optional()
 });
 const blockStyleOverridesSchema = z.object({
 	sectionStyles: sectionStylesOverrideSchema.nullable().optional(),