@tempots/beatui 0.82.1 → 0.83.3

package/dist/types/tailwind/preset.d.ts

@@ -1,3 +1,12 @@
+/**
+ * BeatUI Tailwind CSS preset.
+ *
+ * Generates a Tailwind preset that registers BeatUI's design-token CSS
+ * custom properties (colors, spacing, typography, motion, etc.) as base
+ * styles and extends Tailwind's color palette with semantic aliases.
+ *
+ * @module
+ */
 import { type SemanticColorOverrides } from '../tokens/colors';
 import type { FontFamilyOverrides, SemanticFontOverrides } from '../tokens/typography';
 import type { SemanticRadiusOverrides } from '../tokens/radius';
@@ -5,6 +14,21 @@ import type { SemanticShadowOverrides } from '../tokens/shadows';
 import type { SemanticMotionOverrides } from '../tokens/motion';
 import type { SemanticSpacingOverrides } from '../tokens/spacing';
 import type { SemanticTextShadowOverrides } from '../tokens/text-shadows';
+/**
+ * Options for customising the BeatUI Tailwind preset.
+ *
+ * Allows overriding semantic design tokens (colors, fonts, radii, shadows,
+ * motion, spacing, text-shadows) and controlling which token layers are
+ * included.
+ *
+ * @example
+ * ```ts
+ * const preset = createBeatuiPreset({
+ *   semanticColors: { primary: 'emerald' },
+ *   extendTheme: true,
+ * })
+ * ```
+ */
 export interface BeatuiPresetOptions {
     /**
      * Override the semantic color mapping BeatUI uses (e.g. map `primary` to `emerald`).
@@ -38,6 +62,36 @@ export interface BeatuiPresetOptions {
      * Override the default font family tokens (e.g. set `sans` to a custom stack).
      */
     fontFamilies?: FontFamilyOverrides;
+    /**
+     * Override the base spacing unit (`--spacing-base`). All spacing scale values
+     * are computed from this variable. Defaults to `'0.25rem'`.
+     *
+     * @example
+     * ```ts
+     * { baseSpacing: '0.3rem' }
+     * ```
+     */
+    baseSpacing?: string;
+    /**
+     * Override the base font size (`--base-font-size`). All font size and per-size
+     * line height values are computed from this variable. Defaults to `'1rem'`.
+     *
+     * @example
+     * ```ts
+     * { baseFontSize: '1.125rem' }
+     * ```
+     */
+    baseFontSize?: string;
+    /**
+     * Override the base motion duration (`--motion-duration-base`). All duration
+     * values are computed from this variable. Defaults to `'200ms'`.
+     *
+     * @example
+     * ```ts
+     * { baseMotionDuration: '150ms' }
+     * ```
+     */
+    baseMotionDuration?: string;
     /**
      * When false, skip registering core token variables (spacing, typography, etc.).
      */
@@ -51,21 +105,78 @@ export interface BeatuiPresetOptions {
      */
     extendTheme?: boolean;
 }
+/**
+ * Subset of the Tailwind plugin API used by the BeatUI preset to register
+ * base styles and custom variants.
+ */
 interface TailwindPluginApi {
+    /** Register base CSS declarations (injected into `@layer base`). */
     addBase: (base: Record<string, Record<string, string>>) => void;
+    /** Register a custom variant selector (e.g. `beatui-dark`). */
     addVariant: (name: string, variant: string | string[]) => void;
 }
+/**
+ * Shape of a Tailwind CSS preset object returned by {@link createBeatuiPreset}.
+ */
 interface TailwindPreset {
+    /** Dark mode strategy (always `'class'` for BeatUI). */
     darkMode: string;
+    /** Theme extensions (semantic color aliases). */
     theme: {
         extend: Record<string, unknown>;
     };
+    /** Array of Tailwind plugins registered by this preset. */
     plugins: TailwindPluginConfig[];
 }
+/**
+ * Configuration shape for a single Tailwind plugin (handler + optional config).
+ */
 interface TailwindPluginConfig {
+    /** The plugin handler function that receives the Tailwind plugin API. */
     handler: (api: TailwindPluginApi) => void;
+    /** Optional static configuration merged into Tailwind's config. */
     config?: Record<string, unknown>;
 }
+/**
+ * Creates a Tailwind CSS preset configured with BeatUI's design tokens.
+ *
+ * The returned preset:
+ * - Sets `darkMode: 'class'` so BeatUI's theme provider can toggle themes.
+ * - Registers core and semantic CSS custom properties as base styles.
+ * - Extends Tailwind's color palette with semantic aliases (e.g. `bg-primary-500`).
+ * - Adds convenience variants: `beatui-dark`, `beatui-light`, `beatui-rtl`, `beatui-ltr`.
+ *
+ * @param options - Optional overrides for semantic tokens and feature flags.
+ * @returns A Tailwind preset object to include in `tailwind.config.ts`.
+ *
+ * @example
+ * ```ts
+ * // tailwind.config.ts
+ * import { createBeatuiPreset } from '@tempots/beatui/tailwind'
+ *
+ * export default {
+ *   presets: [createBeatuiPreset({ semanticColors: { primary: 'emerald' } })],
+ *   content: ['./src/** /*.tsx'],
+ * }
+ * ```
+ */
 export declare function createBeatuiPreset(options?: BeatuiPresetOptions): TailwindPreset;
+/**
+ * A ready-to-use BeatUI Tailwind preset with all default options.
+ *
+ * @example
+ * ```ts
+ * // tailwind.config.ts
+ * import { beatuiPreset } from '@tempots/beatui/tailwind'
+ *
+ * export default {
+ *   presets: [beatuiPreset],
+ *   content: ['./src/** /*.tsx'],
+ * }
+ * ```
+ */
 export declare const beatuiPreset: TailwindPreset;
+/**
+ * Re-exported type alias for semantic color override configuration.
+ */
 export type { SemanticColorOverrides as BeatuiSemanticColorOverrides };

package/dist/types/tailwind/vite-plugin.d.ts

@@ -1,11 +1,46 @@
 import type { Plugin } from 'vite';
-import type { BeatuiPresetOptions } from './preset';
+import type { SemanticColorOverrides } from '../tokens/colors';
+import type { FontFamilyOverrides, SemanticFontOverrides } from '../tokens/typography';
+import type { SemanticRadiusOverrides } from '../tokens/radius';
+import type { SemanticShadowOverrides } from '../tokens/shadows';
+import type { SemanticMotionOverrides } from '../tokens/motion';
+import type { SemanticSpacingOverrides } from '../tokens/spacing';
+import type { SemanticTextShadowOverrides } from '../tokens/text-shadows';
 import { type GoogleFontRequest } from './google-fonts';
-export interface BeatuiTailwindPluginOptions extends BeatuiPresetOptions {
+export interface BeatuiTailwindPluginOptions {
+    /** Override the semantic color mapping BeatUI uses (e.g. map `primary` to `emerald`). */
+    semanticColors?: SemanticColorOverrides;
+    /** Override semantic font aliases (e.g. map `heading` to `var(--font-family-serif)`). */
+    semanticFonts?: SemanticFontOverrides;
+    /** Override semantic radius aliases for controls, surfaces, etc. */
+    semanticRadii?: SemanticRadiusOverrides;
+    /** Override semantic shadow aliases (elevation levels for surfaces, overlays, etc.). */
+    semanticShadows?: SemanticShadowOverrides;
+    /** Override semantic motion tokens (transition durations/easing). */
+    semanticMotion?: SemanticMotionOverrides;
+    /** Override spacing stack aliases for layout stacks. */
+    semanticSpacing?: SemanticSpacingOverrides;
+    /** Override semantic text shadow aliases (e.g. button emphasis shadows). */
+    semanticTextShadows?: SemanticTextShadowOverrides;
+    /** Override the default font family tokens (e.g. set `sans` to a custom stack). */
+    fontFamilies?: FontFamilyOverrides;
+    /**
+     * Override the base spacing unit (`--spacing-base`). All spacing scale values
+     * are computed from this variable. Defaults to `'0.25rem'`.
+     */
+    baseSpacing?: string;
+    /**
+     * Override the base font size (`--base-font-size`). All font size and per-size
+     * line height values are computed from this variable. Defaults to `'1rem'`.
+     */
+    baseFontSize?: string;
+    /**
+     * Override the base motion duration (`--motion-duration-base`). All duration
+     * values are computed from this variable. Defaults to `'200ms'`.
+     */
+    baseMotionDuration?: string;
     /** Automatically import the BeatUI Tailwind CSS bundle into the application entry. */
     injectCss?: boolean;
-    /** File name of the Tailwind config if it lives in a non-standard location. */
-    tailwindConfigPath?: string;
     /** Tailwind class that denotes dark mode. Defaults to 'dark'. */
     darkClass?: string;
     /** Attribute inspected for RTL mode. Defaults to `dir="rtl"`. */

package/dist/types/tokens/base-colors.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Base color palette for BeatUI.
+ *
+ * Defines the complete set of raw color values used as the foundation for the
+ * design token color system. Colors are specified in OKLCH color space for
+ * perceptual uniformity and wide gamut support.
+ *
+ * Each color includes 11 shades from 50 (lightest) to 950 (darkest), following
+ * the same shade scale as Tailwind CSS. The palette includes warm colors (red
+ * through yellow), cool colors (lime through blue), purples (indigo through
+ * rose), and neutrals (slate, gray, zinc, neutral, stone).
+ *
+ * These values are consumed by the color token system in `colors.ts` and
+ * converted to CSS custom properties at build time.
+ *
+ * @example
+ * ```ts
+ * import { colors } from './base-colors'
+ * colors.blue[500] // 'oklch(0.623 0.214 259.815)'
+ * ```
+ */
 export declare const colors: {
     readonly red: {
         readonly 50: "oklch(0.971 0.013 17.38)";

package/dist/types/tokens/breakpoints.d.ts

@@ -1,3 +1,23 @@
+/**
+ * Breakpoint design tokens for BeatUI.
+ *
+ * Defines responsive breakpoint values that are converted to CSS custom properties
+ * and media queries at build time. Breakpoints use `rem` units for accessibility
+ * and follow a mobile-first approach.
+ *
+ * @module
+ */
+/**
+ * Breakpoint size definitions mapping size names to their `rem` values.
+ *
+ * | Name | Value   | Pixels |
+ * |------|---------|--------|
+ * | sm   | 40rem   | 640px  |
+ * | md   | 48rem   | 768px  |
+ * | lg   | 64rem   | 1024px |
+ * | xl   | 80rem   | 1280px |
+ * | 2xl  | 96rem   | 1536px |
+ */
 export declare const breakpoints: {
     readonly sm: "40rem";
     readonly md: "48rem";
@@ -5,8 +25,55 @@ export declare const breakpoints: {
     readonly xl: "80rem";
     readonly '2xl': "96rem";
 };
+/**
+ * Union type of all available breakpoint size names.
+ */
 export type BreakpointName = keyof typeof breakpoints;
+/**
+ * Returns the CSS custom property name for a breakpoint size.
+ *
+ * @param size - The breakpoint size name
+ * @returns The CSS variable name (e.g., `'--breakpoint-md'`)
+ *
+ * @example
+ * ```ts
+ * getBreakpointVarName('md') // '--breakpoint-md'
+ * ```
+ */
 export declare function getBreakpointVarName(size: BreakpointName): string;
+/**
+ * Returns a CSS `var()` expression referencing the breakpoint custom property.
+ *
+ * @param size - The breakpoint size name
+ * @returns A CSS `var()` string (e.g., `'var(--breakpoint-md)'`)
+ *
+ * @example
+ * ```ts
+ * getBreakpointVar('md') // 'var(--breakpoint-md)'
+ * ```
+ */
 export declare function getBreakpointVar(size: BreakpointName): string;
+/**
+ * Returns a CSS media query string for a minimum-width breakpoint.
+ *
+ * @param size - The breakpoint size name
+ * @returns A media query string (e.g., `'@media (width >= 48rem)'`)
+ *
+ * @example
+ * ```ts
+ * getBreakpointMediaQuery('md') // '@media (width >= 48rem)'
+ * ```
+ */
 export declare function getBreakpointMediaQuery(size: BreakpointName): string;
+/**
+ * Generates CSS custom property declarations for all breakpoint tokens.
+ *
+ * @returns A record mapping CSS variable names to their breakpoint values
+ *
+ * @example
+ * ```ts
+ * const vars = generateBreakpointVariables()
+ * // vars['--breakpoint-md'] === '48rem'
+ * ```
+ */
 export declare function generateBreakpointVariables(): Record<string, string>;

package/dist/types/tokens/colors.d.ts

@@ -1,13 +1,101 @@
+/**
+ * Color design tokens for BeatUI.
+ *
+ * Defines the complete color system including base color shades, semantic color
+ * mappings, background/text/border/interactive theme colors, and CSS variable
+ * generation utilities. Colors follow a shade scale from 50 (lightest) to 950
+ * (darkest) and support light/dark theme modes.
+ *
+ * @module
+ */
 import { colors } from './base-colors';
+/**
+ * Union type of all available base color names derived from the color palette.
+ *
+ * @example
+ * ```ts
+ * const color: ColorName = 'blue'
+ * ```
+ */
 export type ColorName = keyof typeof colors;
+/**
+ * Union type representing the available shade levels in the color scale.
+ * Ranges from 50 (lightest) to 950 (darkest).
+ */
 export type ColorShade = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950;
+/**
+ * Array of all available color shade values, ordered from lightest to darkest.
+ *
+ * @example
+ * ```ts
+ * colorShades.forEach(shade => {
+ *   console.log(`--color-blue-${shade}`)
+ * })
+ * ```
+ */
 export declare const colorShades: ColorShade[];
+/**
+ * Union type of semantic color role names used throughout the theme system.
+ * Semantic colors map to base color names and can be overridden per-theme.
+ */
 export type SemanticColorName = 'primary' | 'secondary' | 'base' | 'success' | 'warning' | 'danger' | 'info';
+/**
+ * Union type of all theme-aware color names, including base colors,
+ * semantic colors, and the special 'black' and 'white' values.
+ */
 export type ThemeColorName = ColorName | SemanticColorName | 'black' | 'white';
+/**
+ * Tuple of all semantic color names, used for iteration and validation.
+ */
 export declare const semanticColorNames: readonly ["primary", "secondary", "base", "success", "warning", "danger", "info"];
+/**
+ * Array of all available theme color names, combining semantic colors,
+ * base palette colors, and the special 'black' and 'white' values.
+ *
+ * @example
+ * ```ts
+ * themeColorNames.forEach(name => {
+ *   console.log(name) // 'primary', 'blue', 'red', 'black', etc.
+ * })
+ * ```
+ */
 export declare const themeColorNames: ThemeColorName[];
+/**
+ * Default mapping from semantic color names to base color names.
+ *
+ * @default
+ * ```
+ * primary   -> 'blue'
+ * secondary -> 'gray'
+ * base      -> 'gray'
+ * success   -> 'green'
+ * warning   -> 'amber'
+ * danger    -> 'red'
+ * info      -> 'blue'
+ * ```
+ */
 export declare const semanticColors: Record<SemanticColorName, ColorName>;
+/**
+ * Partial record for overriding default semantic-to-base color mappings.
+ *
+ * @example
+ * ```ts
+ * const overrides: SemanticColorOverrides = { primary: 'indigo', danger: 'rose' }
+ * ```
+ */
 export type SemanticColorOverrides = Partial<Record<SemanticColorName, ThemeColorName>>;
+/**
+ * Resolves the full semantic color map by merging defaults with any provided overrides.
+ *
+ * @param overrides - Optional partial overrides for semantic color mappings
+ * @returns A complete mapping of semantic color names to their resolved color names
+ *
+ * @example
+ * ```ts
+ * const map = resolveSemanticColorMap({ primary: 'indigo' })
+ * // map.primary === 'indigo', map.secondary === 'gray', etc.
+ * ```
+ */
 export declare function resolveSemanticColorMap(overrides?: SemanticColorOverrides): {
     base: ThemeColorName;
     primary: ThemeColorName;
@@ -17,30 +105,110 @@ export declare function resolveSemanticColorMap(overrides?: SemanticColorOverrid
     danger: ThemeColorName;
     info: ThemeColorName;
 };
+/**
+ * Union type of background color role names used in the theme system.
+ * Each role represents a different surface elevation level.
+ */
 export type BackgroundColorName = 'background' | 'surface' | 'subtle' | 'elevated' | 'raised' | 'overlay';
+/**
+ * Background color definitions for light and dark theme modes.
+ * Each entry maps a background role to a `[ThemeColorName, ColorShade]` tuple.
+ */
 export declare const bgColors: {
     light: Record<BackgroundColorName, [ThemeColorName, ColorShade]>;
     dark: Record<BackgroundColorName, [ThemeColorName, ColorShade]>;
 };
+/**
+ * Union type of text color role names used in the theme system.
+ */
 export type TextColorName = 'normal' | 'muted' | 'inverted';
+/**
+ * Text color definitions for light and dark theme modes.
+ * Each entry maps a text role to a `[ThemeColorName, ColorShade]` tuple.
+ */
 export declare const textColors: {
     light: Record<TextColorName, [ThemeColorName, ColorShade]>;
     dark: Record<TextColorName, [ThemeColorName, ColorShade]>;
 };
-export type BorderColorName = 'border' | 'divider' | 'inverted';
+/**
+ * Union type of border color role names used in the theme system.
+ */
+export type BorderColorName = 'subtle' | 'muted' | 'border' | 'divider' | 'input' | 'strong' | 'inverted';
+/**
+ * Border color definitions for light and dark theme modes.
+ * Each entry maps a border role to a `[ThemeColorName, ColorShade]` tuple.
+ */
 export declare const borderColors: {
     light: Record<BorderColorName, [ThemeColorName, ColorShade]>;
     dark: Record<BorderColorName, [ThemeColorName, ColorShade]>;
 };
+/**
+ * Union type of interactive color role names for focus, hover, and active states.
+ */
 export type InteractiveColorName = 'focus' | 'hover' | 'active';
+/**
+ * Interactive color definitions for light and dark theme modes.
+ * Used for focus rings, hover backgrounds, and active state backgrounds.
+ */
 export declare const interactiveColors: {
     light: Record<InteractiveColorName, [ThemeColorName, ColorShade]>;
     dark: Record<InteractiveColorName, [ThemeColorName, ColorShade]>;
 };
+/**
+ * Resolves a theme color name to its underlying base color name.
+ * If the color is a semantic name (e.g., 'primary'), it is resolved through the
+ * semantic color map (with optional overrides). Otherwise, the color name is returned as-is.
+ *
+ * @param color - The theme color name to normalize
+ * @param overrides - Optional semantic color overrides
+ * @returns The resolved base color name
+ *
+ * @example
+ * ```ts
+ * normalizeColorName('primary') // 'blue'
+ * normalizeColorName('primary', { primary: 'indigo' }) // 'indigo'
+ * normalizeColorName('red') // 'red'
+ * ```
+ */
 export declare function normalizeColorName(color: ThemeColorName, overrides?: SemanticColorOverrides): ThemeColorName;
+/**
+ * Returns the CSS custom property name for a given color and shade.
+ *
+ * @param color - The theme color name
+ * @param shade - The shade level
+ * @returns The CSS variable name (e.g., `'--color-blue-500'`, `'--color-white'`)
+ *
+ * @example
+ * ```ts
+ * getColorVarName('blue', 500) // '--color-blue-500'
+ * getColorVarName('white', 500) // '--color-white'
+ * ```
+ */
 export declare function getColorVarName(color: ThemeColorName, shade: ColorShade): `--color-${ThemeColorName}-${ColorShade}` | '--color-white' | '--color-black';
+/**
+ * Returns a CSS `var()` expression referencing the color custom property.
+ *
+ * @param color - The theme color name
+ * @param shade - The shade level
+ * @returns A CSS `var()` string (e.g., `'var(--color-blue-500)'`)
+ *
+ * @example
+ * ```ts
+ * getColorVar('blue', 500) // 'var(--color-blue-500)'
+ * ```
+ */
 export declare function getColorVar(color: ThemeColorName, shade: ColorShade): string;
+/**
+ * Union type of background variant styles used for component backgrounds.
+ * Controls the shade intensity applied to colored backgrounds.
+ */
 export type BackgroundVariant = 'solid' | 'soft' | 'light' | 'lighter';
+/**
+ * Configuration object for background utility CSS generation.
+ * Contains special color overrides, standard variant shade mappings for
+ * light/dark modes, and color-specific overrides for 'white', 'black',
+ * and 'transparent'.
+ */
 export declare const backgroundConfig: {
     readonly special: {
         readonly inherit: {
@@ -63,11 +231,11 @@ export declare const backgroundConfig: {
     readonly variants: {
         readonly solid: {
             readonly light: {
-                readonly bgShade: 700;
+                readonly bgShade: 600;
                 readonly textColor: "var(--color-white)";
             };
             readonly dark: {
-                readonly bgShade: 600;
+                readonly bgShade: 400;
                 readonly textColor: "var(--color-black)";
             };
         };
@@ -83,7 +251,7 @@ export declare const backgroundConfig: {
         };
         readonly light: {
             readonly light: {
-                readonly bgShade: 200;
+                readonly bgShade: 100;
                 readonly textColor: "var(--text-normal-light)";
             };
             readonly dark: {
@@ -135,6 +303,47 @@ export declare const backgroundConfig: {
         };
     };
 };
+/**
+ * Generates CSS custom property declarations for all core (base) color tokens.
+ * Includes `--color-white`, `--color-black`, `--color-inherit`, and all
+ * base palette colors at every shade level.
+ *
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateCoreColorVariables()
+ * // vars['--color-blue-500'] === 'oklch(0.623 0.214 259.815)'
+ * // vars['--color-white'] === 'white'
+ * ```
+ */
 export declare function generateCoreColorVariables(): Record<string, string>;
+/**
+ * Generates CSS custom property declarations for semantic colors, background
+ * colors, text colors, border colors, and interactive colors. Semantic colors
+ * reference base color variables so themes can be changed by swapping the
+ * semantic mapping.
+ *
+ * @param overrides - Optional overrides for semantic color mappings
+ * @returns A record mapping CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateSemanticColorVariables({ primary: 'indigo' })
+ * // vars['--color-primary-500'] === 'var(--color-indigo-500)'
+ * ```
+ */
 export declare function generateSemanticColorVariables(overrides?: SemanticColorOverrides): Record<string, string>;
+/**
+ * Generates the complete set of CSS custom property declarations for all color tokens,
+ * combining both core color variables and semantic color variables.
+ *
+ * @returns A record mapping all color CSS variable names to their values
+ *
+ * @example
+ * ```ts
+ * const vars = generateColorVariables()
+ * // Contains both base colors and semantic mappings
+ * ```
+ */
 export declare function generateColorVariables(): Record<string, string>;