Add preventUnitlessValues property to PluginStyleSettings (#320)

hippotastic · web-flow · commit 6497f09c3fb7 · 2025-04-11T16:17:20.000+02:00
diff --git a/.changeset/famous-drinks-taste.md b/.changeset/famous-drinks-taste.md
@@ -0,0 +1,7 @@
+---
+'@expressive-code/plugin-collapsible-sections': minor
+'@expressive-code/plugin-text-markers': minor
+'@expressive-code/plugin-frames': minor
+---
+
+Uses the new `preventUnitlessValues` property of `PluginStyleSettings` to make style calculations in the plugins "Collapsible Sections", "Frames" and "Text Markers" more robust.
diff --git a/.changeset/heavy-jokes-doubt.md b/.changeset/heavy-jokes-doubt.md
@@ -0,0 +1,10 @@
+---
+'@expressive-code/core': minor
+'astro-expressive-code': minor
+'expressive-code': minor
+'rehype-expressive-code': minor
+---
+
+Adds new `preventUnitlessValues` property to `PluginStyleSettings`. Thank you @RantingHuman!
+
+Plugins can set this property to an array of style setting paths to prevent unitless values for specific style settings. If the user passes a unitless value to one of these settings, the engine will automatically add `px` to the value. This is recommended for settings used in CSS calculations which would otherwise break if a unitless value is passed.
diff --git a/docs/src/content/docs/reference/plugin-api.mdx b/docs/src/content/docs/reference/plugin-api.mdx
@@ -85,6 +85,9 @@ If CSS variables should not be generated for some of your style settings, you ca
 If you want to provide descriptive names for your style settings, but keep the generated CSS variable names short, you can pass an array of search and replace string pairs to the
 `cssVarReplacements` property of the object passed to the constructor. The replacements will be applied to all generated CSS variable names.
 
+If you want to prevent unitless values for specific style settings (e.g. because you intend to use them in CSS calculations), you can pass an array of style setting paths to the
+`preventUnitlessValues` property of the object passed to the constructor. If the user passes a unitless value to one of these settings, the engine will automatically add `px` to the value.
+
 ### Example
 
 ```ts
@@ -137,6 +140,7 @@ framesStyleSettings.defaultValues.frames.titleBarForeground // ({ theme }) => th
 | `options.defaultValues` | `Partial`\<[`UnresolvedStyleSettings`](/reference/plugin-api/#unresolvedstylesettings)\> |
 | `options.cssVarExclusions`? | [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[] |
 | `options.cssVarReplacements`? | \[`string`, `string`\][] |
+| `options.preventUnitlessValues`? | [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[] |
 
 ### Properties
 
@@ -158,6 +162,12 @@ framesStyleSettings.defaultValues.frames.titleBarForeground // ({ theme }) => th
 - Type: **readonly** `Partial`\<[`UnresolvedStyleSettings`](/reference/plugin-api/#unresolvedstylesettings)\>
 </PropertySignature>
 
+#### preventUnitlessValues
+
+<PropertySignature>
+- Type: **readonly** [`StyleSettingPath`](/reference/plugin-api/#stylesettingpath)[]
+</PropertySignature>
+
 ## AttachedPluginData
 
 A class that allows plugins to attach custom data to objects like code blocks, and to optionally allow external access to this data in a type-safe manner.
diff --git a/packages/@expressive-code/core/src/common/plugin-style-settings.ts b/packages/@expressive-code/core/src/common/plugin-style-settings.ts
@@ -27,6 +27,11 @@ import { UnresolvedStyleSettings, StyleSettingPath } from './style-settings'
  * `cssVarReplacements` property of the object passed to the constructor. The replacements
  * will be applied to all generated CSS variable names.
  *
+ * If you want to prevent unitless values for specific style settings (e.g. because you intend
+ * to use them in CSS calculations), you can pass an array of style setting paths to the
+ * `preventUnitlessValues` property of the object passed to the constructor. If the user passes
+ * a unitless value to one of these settings, the engine will automatically add `px` to the value.
+ *
  * @example
  * // When using TypeScript: Declare the types of your style settings
  * interface FramesStyleSettings {
@@ -66,18 +71,22 @@ export class PluginStyleSettings {
 	readonly defaultValues: Partial<UnresolvedStyleSettings>
 	readonly cssVarExclusions: StyleSettingPath[]
 	readonly cssVarReplacements: [string, string][]
+	readonly preventUnitlessValues: StyleSettingPath[]
 
 	constructor({
 		defaultValues,
 		cssVarExclusions = [],
 		cssVarReplacements = [],
+		preventUnitlessValues = [],
 	}: {
 		defaultValues: Partial<UnresolvedStyleSettings>
 		cssVarExclusions?: StyleSettingPath[] | undefined
 		cssVarReplacements?: [string, string][] | undefined
+		preventUnitlessValues?: StyleSettingPath[] | undefined
 	}) {
 		this.defaultValues = defaultValues
 		this.cssVarExclusions = cssVarExclusions
 		this.cssVarReplacements = cssVarReplacements
+		this.preventUnitlessValues = preventUnitlessValues
 	}
 }
diff --git a/packages/@expressive-code/core/src/internal/core-styles.ts b/packages/@expressive-code/core/src/internal/core-styles.ts
@@ -214,6 +214,7 @@ export const coreStyleSettings = new PluginStyleSettings({
 		scrollbarThumbHoverColor: ({ theme, resolveSetting }) =>
 			ensureColorContrastOnBackground(theme.colors['scrollbarSlider.hoverBackground'], resolveSetting('codeBackground'), 2.5, 3.5),
 	} satisfies UnresolvedStyleSettings,
+	preventUnitlessValues: ['borderRadius', 'borderWidth', 'gutterBorderWidth'],
 })
 
 export function getCoreBaseStyles({
diff --git a/packages/@expressive-code/core/src/internal/style-resolving.ts b/packages/@expressive-code/core/src/internal/style-resolving.ts
@@ -38,17 +38,32 @@ export function resolveStyleSettings({
 	// Apply any theme style overrides
 	applyStyleSettings(unresolvedByPath, getStyleSettingsByPath(theme.styleOverrides ?? {}))
 
+	// Collect all settings to be respected when resolving values
+	const preventUnitlessValues = new Set<StyleSettingPath>(coreStyleSettings.preventUnitlessValues)
+	plugins.forEach((plugin) => {
+		plugin.styleSettings?.preventUnitlessValues.forEach((path) => preventUnitlessValues.add(path))
+	})
+
 	// Define a setting resolver function that can be used both by plugins and ourselves
 	function resolveSetting(settingPath: StyleSettingPath): string {
 		let result = resolvedByPath.get(settingPath)
 		if (result === undefined && !resolvedByPath.has(settingPath)) {
 			if (attemptedToResolve.has(settingPath)) throw new Error(`Circular dependency detected while resolving style setting '${settingPath as string}'`)
 			attemptedToResolve.add(settingPath)
 
+			// Resolve the setting value
 			const valueOrResolver = unresolvedByPath.get(settingPath)
 			const resolvedDefinition = (typeof valueOrResolver === 'function' ? valueOrResolver(resolverArgs) : valueOrResolver) as StyleValueOrValues
 			result = Array.isArray(resolvedDefinition) ? resolvedDefinition[theme.type === 'dark' ? 0 : 1] : resolvedDefinition
 
+			// If the resolved result is required to have a unit,
+			// ensure that it has one
+			if (preventUnitlessValues.has(settingPath)) {
+				result = result.trim()
+				if (result in ['', 'none']) result = '0px'
+				if (result.match(/^[0-9.]+$/)) result = `${result}px`
+			}
+
 			resolvedByPath.set(settingPath, result)
 		}
 		if (result === undefined)
diff --git a/packages/@expressive-code/plugin-collapsible-sections/src/styles.ts b/packages/@expressive-code/plugin-collapsible-sections/src/styles.ts
@@ -108,6 +108,7 @@ export const collapsibleSectionsStyleSettings = new PluginStyleSettings({
 		},
 	},
 	cssVarReplacements: [['collapsibleSections', 'cs']],
+	preventUnitlessValues: ['collapsibleSections.closedBorderWidth', 'collapsibleSections.openBorderWidth'],
 })
 
 export function getCollapsibleSectionsBaseStyles({ cssVar }: ResolverContext) {
diff --git a/packages/@expressive-code/plugin-frames/src/styles.ts b/packages/@expressive-code/plugin-frames/src/styles.ts
@@ -233,6 +233,7 @@ export const framesStyleSettings = new PluginStyleSettings({
 			tooltipSuccessForeground: 'white',
 		},
 	},
+	preventUnitlessValues: ['frames.editorActiveTabIndicatorHeight', 'frames.editorTabBorderRadius'],
 })
 
 export function getFramesBaseStyles({ cssVar }: ResolverContext, options: PluginFramesOptions) {
diff --git a/packages/@expressive-code/plugin-text-markers/src/styles.ts b/packages/@expressive-code/plugin-text-markers/src/styles.ts
@@ -234,6 +234,7 @@ export const textMarkersStyleSettings = new PluginStyleSettings({
 		'textMarkers.indicatorLuminance',
 		'textMarkers.indicatorOpacity',
 	],
+	preventUnitlessValues: ['textMarkers.lineMarkerLabelPaddingInline', 'textMarkers.lineMarkerAccentWidth'],
 })
 
 export function getTextMarkersBaseStyles({ cssVar }: ResolverContext) {
