Utility Functions

This page documents non-composable helper functions.
For all use* APIs, see UI Helpers — Composables.

import {
  createTextStyle,
  getColorHex,
  getBackgroundStyle,
  getContrastTextColor,
  isColorDark,
  getCurrentLanguageCode,
} from '@lightspeed/crane-api';

Reference

Function	Arguments	Purpose
createTextStyle(design, options?)	design: TextDesignData; options?: style defaults/overrides	Build CSS text styles
getColorHex(color, fallback?)	color: color-like value; fallback?: hex fallback	Extract color hex string
getBackgroundStyle(design, options?)	design: BackgroundDesignData; options?: gradient direction/fallbacks	Build CSS background style value
isColorDark(color)	color: color-like value	Check if color is dark
getContrastTextColor(backgroundColor, darkTextColor?, lightTextColor?)	backgroundColor: required; darkTextColor?: text for light backgrounds; lightTextColor?: text for dark backgrounds	Return readable contrast text color
getCurrentLanguageCode(languages)	languages: Language[] | undefined	Return current language code from site languages array. Fallback chain: selected → main → 'en'

Examples

const titleDesign = useTextElementDesign<Design>('title');
const titleStyle = computed(() =>
  createTextStyle(titleDesign, { defaultSize: 24 }),
);

const dark = isColorDark('#1F2937');
const textColor = getContrastTextColor('#1F2937');
const textColorCustom = getContrastTextColor('#1F2937', '#111111', '#FAFAFA');

const bgDesign = useBackgroundElementDesign<Design>('section_bg');
const bgValue = getBackgroundStyle(bgDesign, { fallbackColor: '#FFFFFF' });

Notes

getBackgroundStyle — gradient fallback behaviour

When background.type === 'gradient', fromColor and toColor are each resolved independently via getColorHex:

• If a colour is missing and fallbackColor is omitted (defaults to ''), getColorHex returns '' and the function returns {} (no style applied).
• If a colour is missing and fallbackColor is a non-empty string, the missing stop is replaced by that fallback. This can produce a gradient where both stops are identical (e.g. linear-gradient(to right, #FFFFFF, #FFFFFF)), which is valid CSS but visually equivalent to a solid colour.

Keep this in mind when debugging unexpected gradient output.

useButtonStyles — font weight is always 400

Unlike createTextStyle, which respects the bold property from TextDesignData, useButtonStyles always sets fontWeight: '400' regardless of any bold-related properties in ButtonDesignData. This is intentional — button typography weight is considered a concern of the consuming component's own CSS, not of the design data.