@lightspeed/crane-api 2.3.3-rc.0 → 2.3.3-rc.2

package/CHANGELOG.md

@@ -1,10 +1,10 @@
 # Changelog
 
-## 2.3.3 - 2026-05-22
+## 2.3.3 - 2026-06-03
 
 ### Fixed
 
-- Add visible to transformed text, image, and logo design default types.
+- Support nested DECK defaults in showcase configuration; validate nested deck card setting keys recursively.
 
 ## 2.3.2 - 2026-05-21
 

package/README.md

@@ -42,8 +42,59 @@ import type { ContentType, DesignType } from './type';
 
 export default createVueClientApp<ContentType, DesignType>(Section);
 ```
+## UI Helpers
 
-## Content Composables
+Higher-level composables and utilities that reduce boilerplate in template development. Import from `@lightspeed/crane-api`:
+
+```typescript
+import {
+  useCurrentLanguage,
+  useBackgroundStyle,
+  useButtonStyles,
+  createTextStyle,
+  getColorHex,
+  getBackgroundStyle,
+  getContrastTextColor,
+  isColorDark,
+} from '@lightspeed/crane-api';
+```
+
+### Composables
+
+#### `useCurrentLanguage()`
+
+Returns the current language code from site context with fallback chain: selected → main → `'en'`.
+
+```typescript
+const { currentLanguage } = useCurrentLanguage();
+// currentLanguage.value === 'en' | 'nl' | 'fr' | ...
+```
+
+#### `useBackgroundStyle(backgroundDesign, options?)`
+
+Creates reactive CSS background styles from `BackgroundDesignData`. Supports solid colors and gradients.
+
+```typescript
+const bg = useBackgroundElementDesign<DesignType>('section_bg');
+const bgStyle = useBackgroundStyle(bg, { direction: 'to bottom' });
+// <div :style="bgStyle">
+```
+
+#### `useButtonStyles(buttonDesign, options?)`
+
+Generates button CSS styles from `ButtonDesignData`. Handles size, appearance, shape, and auto contrast text color for solid buttons.
+
+> **Note:** `fontWeight` is always set to `'400'`. Unlike `createTextStyle`, button styles intentionally ignore any bold-related properties — weight is expected to be controlled by the component's own CSS.
+
+```typescript
+const btn = useButtonElementDesign<DesignType>('cta_button');
+const btnStyle = useButtonStyles(btn, {
+  sizes: { large: { fontSize: '20px', padding: '16px 32px' } },
+});
+// <button :style="btnStyle">
+```
+
+### Content Composables
 
 Access content defined in `settings/content.ts`:
 
@@ -63,7 +114,7 @@ Access content defined in `settings/content.ts`:
 | `useNavigationMenuElementContent` | NAVIGATION_MENU | `Reactive<MenuContent>` |
 | `useTranslation` | — | Translation helper |
 
-### Example
+#### Example
 
 ```typescript
 import { useInputboxElementContent, useImageElementContent } from '@lightspeed/crane-api';
@@ -74,7 +125,7 @@ const image = useImageElementContent<ContentType>('hero_image');
 
 ```
 
-## Design Composables
+### Design Composables
 
 Access design settings defined in `settings/design.ts`:
 
@@ -90,7 +141,7 @@ Access design settings defined in `settings/design.ts`:
 | `useLayoutElementDesign` | — | `Reactive<LayoutDesignData>` |
 | `useLogoElementDesign` | LOGO | `ComputedRef<LogoDesignData>` |
 
-### Example
+#### Example
 
 ```typescript
 import { useTextElementDesign, useBackgroundElementDesign } from '@lightspeed/crane-api';
@@ -101,7 +152,7 @@ const background = useBackgroundElementDesign<DesignType>('section_background');
 
 ```
 
-## Working with DECK
+### Working with DECK
 
 DECK allows collections of cards. Use `getReactiveRef` to access card fields:
 
@@ -118,6 +169,31 @@ slides.cards?.forEach(card => {
 });
 ```
 
+### Utility Functions
+
+| Function | Arguments | Description                                                                                |
+|----------|-----------|--------------------------------------------------------------------------------------------|
+| `createTextStyle(design, options?)` | `design`: TextDesignData; `options?`: style defaults/overrides | Creates CSS properties from `TextDesignData` (font, size, color, bold, italic, visibility) |
+| `getColorHex(color, fallback?)` | `color`: color-like value; `fallback?`: hex fallback | Extracts hex string from a `Color` object, string, or undefined                            |
+| `getBackgroundStyle(design, options?)` | `design`: BackgroundDesignData; `options?`: gradient direction/fallbacks | Returns CSS background style object                                                        |
+| `isColorDark(color)` | `color`: color-like value | Returns `true` when the color is considered dark                                           |
+| `getContrastTextColor(backgroundColor, darkTextColor?, lightTextColor?)` | `backgroundColor`: required; `darkTextColor?`: text for light backgrounds; `lightTextColor?`: text for dark backgrounds | Returns a readable contrast text color for the given background                            |
+| `getCurrentLanguageCode(languages)` | `languages`: `Language[] \| undefined` | Returns current language code from an array of site languages. Fallback chain: selected → main → `'en'` |
+
+```typescript
+// createTextStyle — use inside computed for reactivity
+const titleDesign = useTextElementDesign<DesignType>('title');
+const titleStyle = computed(() => createTextStyle(titleDesign, {
+  defaultFont: 'Inter',
+  defaultSize: 24,
+}));
+
+// contrast helpers
+const dark = isColorDark('#1a1a2e'); // true
+const textColor = getContrastTextColor('#1a2e1a'); // '#FFFFFF'
+const textColorCustom = getContrastTextColor('#1a2e1a', '#111111', '#FAFAFA');
+```
+
 ## Requirements
 
 - Node.js >= 20