/**
 * 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 ColorShadeMap, 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';
/**
 * 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<C extends string = never> {
    /**
     * Register custom color palettes. Each key is a color name and the value
     * defines all 11 shades (50–950). Custom color names can be referenced in
     * `semanticColors` and in component `color` props (after type registration).
     *
     * The BeatUI Vite plugin automatically generates a `.d.ts` file that
     * registers these names with the type system. When using the preset directly
     * (without the Vite plugin), augment {@link CustomColorRegistry} manually.
     *
     * @example
     * ```ts
     * createBeatuiPreset({
     *   customColors: {
     *     rust: { 50: 'oklch(...)', 100: '...', ..., 950: '...' },
     *   },
     *   semanticColors: { primary: 'rust' },
     * })
     * ```
     */
    customColors?: Record<C, ColorShadeMap>;
    /**
     * Override the semantic color mapping BeatUI uses (e.g. map `primary` to `emerald`).
     * When `customColors` is provided, custom color names are also accepted.
     */
    semanticColors?: SemanticColorOverrides<C>;
    /**
     * 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'`.
     *
     * @example
     * ```ts
     * { baseSpacing: '0.3rem' }
     * ```
     */
    baseSpacing?: string;
    /**
     * Override the base font size (`--font-size-base`). 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.).
     */
    includeCoreTokens?: boolean;
    /**
     * When false, skip registering semantic token aliases.
     */
    includeSemanticTokens?: boolean;
    /**
     * Extend Tailwind's theme with BeatUI semantic color aliases.
     */
    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-light`, `beatui-rtl`, `beatui-ltr`.
 *
 * @remarks
 * This preset targets the legacy Tailwind v3 config format (`tailwind.config.ts`
 * with `presets: [...]`). BeatUI's docs target Tailwind v4, which is configured
 * via CSS and the `beatuiTailwindPlugin` Vite plugin — prefer that integration
 * path for new projects.
 *
 * @param options - Optional overrides for semantic tokens and feature flags.
 * @returns A Tailwind preset object.
 */
export declare function createBeatuiPreset<C extends string = never>(options?: BeatuiPresetOptions<C>): TailwindPreset;
/**
 * A ready-to-use BeatUI Tailwind preset with all default options.
 *
 * @remarks
 * Legacy Tailwind v3 preset. For Tailwind v4, use `beatuiTailwindPlugin` from
 * `@tempots/beatui/tailwind/vite-plugin` instead.
 */
export declare const beatuiPreset: TailwindPreset;
/**
 * Re-exported type alias for semantic color override configuration.
 */
export type { SemanticColorOverrides as BeatuiSemanticColorOverrides };