@aleph-alpha/ui-library 1.12.0 → 1.14.0

package/README.md

@@ -1,6 +1,6 @@
 # UI Library
 
-📘 **[View Storybook](https://urban-broccoli-l1okew7.pages.github.io/ui-library)**
+📘 **[View Storybook](https://dev.aleph-alpha.de/ui-library)**
 
 ## Installation
 
@@ -33,11 +33,88 @@ export default defineConfig({
   presets: [
     presetWind(),
     presetAnimations(),
-    presetShadcn({ color: 'neutral' }),
+    presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
+  ],
+})
+```
+
+### Custom theme (via design tokens)
+
+`@aleph-alpha/ui-library` uses shadcn-style semantic utilities such as `bg-background`, `text-foreground`, `bg-primary`, `border-input`, etc.
+These resolve through CSS variables (e.g. `--background`, `--primary`).
+
+#### Option A: Use the built-in `tokens.json` shipped with the library (recommended)
+
+If you added/maintain tokens in `packages/ui-library/tokens.json`, you can load them directly:
+
+```typescript
+// uno.config.ts
+import { defineConfig } from 'unocss'
+import { getUiLibraryContentConfig, presetUiLibraryThemeFromTokens } from '@aleph-alpha/ui-library/config'
+import presetWind from '@unocss/preset-wind4'
+import presetAnimations from 'unocss-preset-animations'
+import presetShadcn from 'unocss-preset-shadcn'
+
+export default defineConfig({
+  ...getUiLibraryContentConfig(),
+  presets: [
+    presetWind(),
+    presetAnimations(),
+    presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
+    // Put the theme preset AFTER shadcn so it overrides shadcn's default CSS vars
+    presetUiLibraryThemeFromTokens(),
   ],
 })
 ```
 
+#### Option B: Provide your own shadcn vars explicitly
+
+To implement a custom theme from your token values, add `presetUiLibraryTheme()` **after** `presetShadcn()` so it overrides shadcn's default CSS vars:
+
+```typescript
+// uno.config.ts
+import { defineConfig } from 'unocss'
+import { getUiLibraryContentConfig, presetUiLibraryTheme } from '@aleph-alpha/ui-library/config'
+import presetWind from '@unocss/preset-wind4'
+import presetAnimations from 'unocss-preset-animations'
+import presetShadcn from 'unocss-preset-shadcn'
+
+export default defineConfig({
+  ...getUiLibraryContentConfig(),
+  presets: [
+    presetWind(),
+    presetAnimations(),
+    presetShadcn({ color: 'neutral', darkSelector: 'html.dark' }),
+    presetUiLibraryTheme({
+      light: {
+        // shadcn vars (keys without the leading `--`)
+        background: '0 0% 100%',
+        foreground: '240 10% 3.9%',
+        primary: '222.2 47.4% 11.2%',
+        'primary-foreground': '210 40% 98%',
+        border: '240 5.9% 90%',
+        input: '240 5.9% 90%',
+        ring: '240 5.9% 10%',
+      },
+      dark: {
+        background: '240 10% 3.9%',
+        foreground: '0 0% 98%',
+        primary: '210 40% 98%',
+        'primary-foreground': '222.2 47.4% 11.2%',
+        border: '240 3.7% 15.9%',
+        input: '240 3.7% 15.9%',
+        ring: '240 4.9% 83.9%',
+      },
+    }),
+  ],
+})
+```
+
+Notes:
+
+- **Value formats**: You can pass OKLCH components, or `hex`/`rgb(...)`/`hsl(...)` — they will be converted to shadcn-compatible OKLCH components.
+- **Dark mode selector**: Defaults to `html.dark`. If your app uses `.dark` on another element, pass `{ darkSelector: '.dark' }` as the second argument.
+
 ### 2. Configure Vite
 
 ```typescript

package/config.d.ts

@@ -1,11 +1,195 @@
+import type { Preset } from 'unocss';
+
 /**
  * UnoCSS content configuration for scanning ui-library components.
+ * Use this to ensure classes inside `@aleph-alpha/ui-library` are scanned.
  */
 export declare const getUiLibraryContentConfig: () => {
+  /** UnoCSS content configuration object */
   content: {
+    /** Paths to scan for class usage in node_modules */
     filesystem: string[];
+    /** Pipeline configuration for class extraction */
     pipeline: {
-      include: (RegExp | string)[];
+      /** File patterns to extract classes from */
+      include: (string | RegExp)[];
     };
   };
 };
+
+/**
+ * Theme variable record where keys are CSS variable names (without `--` prefix)
+ * and values are color strings (hex, rgb, hsl, or oklch).
+ */
+export type UiLibraryThemeVars = Record<string, string>;
+
+/**
+ * Theme configuration with light and dark mode variables.
+ */
+export interface UiLibraryTheme {
+  /** Light mode CSS variables */
+  light: UiLibraryThemeVars;
+  /** Dark mode CSS variables */
+  dark?: UiLibraryThemeVars;
+}
+
+/**
+ * Options for CSS selector customization.
+ */
+export interface UiLibraryThemeOptions {
+  /**
+   * CSS selector for the root (light) theme block.
+   * @default ':root'
+   */
+  rootSelector?: string;
+  /**
+   * CSS selector for the dark theme block.
+   * @default 'html.dark'
+   */
+  darkSelector?: string;
+}
+
+/**
+ * Configuration for customizing the theme.
+ */
+export interface UiLibraryThemeConfig {
+  /** Completely override the default theme */
+  theme?: UiLibraryTheme;
+  /** Extend/override specific variables while keeping defaults */
+  extend?: Partial<UiLibraryTheme>;
+  /**
+   * Include all token-based CSS variables in addition to shadcn variables.
+   * This enables classes like bg-background-surface-secondary, text-content-on-surface-primary, etc.
+   * @default false
+   */
+  includeAllTokens?: boolean;
+}
+
+/**
+ * Combined options for `presetUiLibraryThemeFromTokens`.
+ */
+export type UiLibraryPresetOptions = UiLibraryThemeOptions & UiLibraryThemeConfig;
+
+/**
+ * UnoCSS theme colors record where keys are color names
+ * and values are oklch CSS variable references.
+ */
+export type UiLibraryTokenColors = Record<string, string>;
+
+/**
+ * Helper function for type-safe theme configuration files.
+ * Similar to Tailwind's `defineConfig`.
+ *
+ * @example
+ * ```ts
+ * // tokens.config.ts
+ * import { defineThemeConfig } from '@aleph-alpha/ui-library/config';
+ *
+ * export default defineThemeConfig({
+ *   extend: {
+ *     light: { primary: '#ff5500' },
+ *   },
+ * });
+ * ```
+ */
+export declare const defineThemeConfig: <T extends UiLibraryThemeConfig>(config: T) => T;
+
+/**
+ * Returns the default theme derived from the library's `tokens.json`.
+ */
+export declare const getUiLibraryThemeFromTokens: () => UiLibraryTheme;
+
+/**
+ * Get all token-based CSS variables for light and dark modes.
+ * These map directly to the token structure, e.g.:
+ * - background.surface.secondary -> --background-surface-secondary
+ * - content.on-surface.primary -> --content-on-surface-primary
+ */
+export declare const getUiLibraryTokenVars: () => UiLibraryTheme;
+
+/**
+ * Get UnoCSS theme colors config for all token-based colors.
+ * This allows using classes like bg-background-surface-secondary, text-content-on-surface-primary, etc.
+ *
+ * @example
+ * ```ts
+ * // uno.config.ts
+ * import { getUiLibraryTokenColors } from '@aleph-alpha/ui-library/config';
+ *
+ * export default defineConfig({
+ *   theme: {
+ *     colors: {
+ *       ...getUiLibraryTokenColors(),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare const getUiLibraryTokenColors: () => UiLibraryTokenColors;
+
+/**
+ * Creates an UnoCSS preset with custom theme variables.
+ * Use this when you want full control over the theme.
+ *
+ * @param theme - The complete theme object with light/dark variables.
+ * @param options - CSS selector options.
+ */
+export declare const presetUiLibraryTheme: (
+  theme: UiLibraryTheme,
+  options?: UiLibraryThemeOptions,
+) => Preset;
+
+/**
+ * Creates an UnoCSS preset using the library's design tokens.
+ * Supports extending or overriding the default theme.
+ *
+ * **Important:** Place this preset AFTER `presetShadcn()` to override its CSS variables.
+ *
+ * @example
+ * ```ts
+ * // Use defaults
+ * presetUiLibraryThemeFromTokens({ darkSelector: 'html.dark' })
+ *
+ * // Extend defaults
+ * presetUiLibraryThemeFromTokens({
+ *   darkSelector: 'html.dark',
+ *   extend: { light: { primary: '#ff5500' } },
+ * })
+ *
+ * // With external config file
+ * import themeConfig from './tokens.config';
+ * presetUiLibraryThemeFromTokens({ ...themeConfig, darkSelector: 'html.dark' })
+ * ```
+ */
+export declare const presetUiLibraryThemeFromTokens: (options?: UiLibraryPresetOptions) => Preset;
+
+/**
+ * Typography shortcut tuple: [className, cssProperties]
+ */
+export type UiLibraryTypographyShortcut = [string, string];
+
+/**
+ * Get typography shortcuts for UnoCSS rules.
+ * Returns an array of [className, cssProperties] tuples that can be used with UnoCSS rules.
+ *
+ * Available typography classes:
+ * - Headings: heading-48-bold, heading-30-bold, heading-24-semi-bold, heading-20-bold
+ * - Body: body-16-normal, body-16-normal-compact, body-16-bold, body-14-normal, body-14-medium, body-14-bold
+ * - Labels: label-12-normal, label-12-medium, label-12-bold
+ *
+ * @example
+ * ```ts
+ * // uno.config.ts
+ * import { getUiLibraryTypographyShortcuts } from '@aleph-alpha/ui-library/config';
+ *
+ * const typographyShortcuts = getUiLibraryTypographyShortcuts();
+ *
+ * export default defineConfig({
+ *   rules: typographyShortcuts.map(([name, css]) => [
+ *     new RegExp(`^${name}$`),
+ *     () => Object.fromEntries(css.split(';').map(p => p.split(':').map(s => s.trim()))),
+ *   ]),
+ * });
+ * ```
+ */
+export declare const getUiLibraryTypographyShortcuts: () => UiLibraryTypographyShortcut[];