import type { Preset, UserConfig } 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: {
      /** 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;
  /**
   * Font size emitted on the root selector to control the UI library rem base.
   * String values are used as-is (for example, '100%', '16px', '62.5%').
   * Number values are treated as pixels.
   */
  rootFontSize?: string | number;
}

/**
 * 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 true
   */
  includeAllTokens?: boolean;
  /**
   * Select which token theme set is used for resolving semantic token refs.
   * - `default` reads `2-theme/AA Base`
   * - `accessible` reads `2-theme/WCAG 2.2`
   * @default 'default'
   */
  themeMode?: 'default' | 'accessible';
  /**
   * Convenience alias for `themeMode: 'accessible'`.
   * @default false
   */
  accessible?: boolean;
  /**
   * Emit an additional accessible-theme CSS variable block that can be toggled
   * at runtime by adding `accessibleSelector` to the root element.
   * @default false
   */
  accessibleTheme?: boolean;
  /**
   * Selector used for the runtime accessible-theme block.
   * @default 'html.accessible-theme'
   */
  accessibleSelector?: string;
}

/**
 * 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>;

/**
 * UnoCSS border-radius record where keys are utility suffixes
 * and values are CSS length values.
 */
export type UiLibraryTokenBorderRadius = 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: (
  options?: Pick<UiLibraryThemeConfig, 'themeMode' | 'accessible'> & {
    referenceThemeSet?: string;
  },
) => 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: (
  options?: Pick<UiLibraryThemeConfig, 'themeMode' | 'accessible'> & {
    referenceThemeSet?: string;
  },
) => 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;

/**
 * Get UnoCSS border-radius config from corner-radius design tokens.
 * This allows using classes like rounded-xs, rounded-md, rounded-4xl, rounded-full, etc.
 */
export declare const getUiLibraryTokenBorderRadius: () => UiLibraryTokenBorderRadius;

/**
 * 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.
 *
 * This preset bundles everything needed for the UI library:
 * - CSS variables for all design tokens (light/dark mode)
 * - Token-based theme colors (bg-background-surface-secondary, text-content-on-surface-primary, etc.)
 * - Token-based border radius utilities (rounded-xs, rounded-md, rounded-full, etc.)
 * - Semantic color overrides (background, foreground, modal, link, etc.)
 * - Typography classes from design tokens (heading-s, body-14-normal, label-12-medium, etc.)
 * - Custom rules for Tailwind v4 CSS variable syntax (w-(--var), h-(--var), etc.)
 *
 * @example
 * ```ts
 * // Use defaults (recommended — includes everything)
 * presetUiLibraryThemeFromTokens()
 *
 * // Extend defaults
 * presetUiLibraryThemeFromTokens({
 *   extend: { light: { primary: '#ff5500' } },
 * })
 *
 * // With external config file
 * import themeConfig from './tokens.config';
 * presetUiLibraryThemeFromTokens(themeConfig)
 * ```
 */
export declare const presetUiLibraryThemeFromTokens: (
  options?: UiLibraryPresetOptions,
) => Preset;

/**
 * UnoCSS preset with utility rules required by the UI library's components.
 * Adds Tailwind v4 CSS variable syntax (w-(--var), h-(--var), etc.)
 * that preset-wind4 does not yet support.
 */
export declare const presetUiLibraryUtils: () => Preset;

/** Overlay tier keys for the `v-hover` directive (injected hover overlay span). */
export declare const vHoverOverlayVariants: Readonly<{
  subtle: 'subtle';
  default: 'default';
  strong: 'strong';
}>;

/**
 * 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.
 *
 * Scale headings use one utility per token group: `heading-s`, `heading-m`, … `heading-2xl`.
 * Other groups (labels, body, …) follow `group-variant` from token names.
 *
 * @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[];

/**
 * Spark token preset with typography utilities removed when ui-library owns the
 * same class names.
 */
export declare const getSparkTokenPresetWithoutUiLibraryTypography: () => Preset;

/**
 * Options for `defineUiLibraryConfig`.
 * Combines theme customization with additional UnoCSS config.
 */
export interface UiLibraryConfigOptions extends UiLibraryPresetOptions {
  /** Additional UnoCSS presets to append after the built-in ones */
  presets?: Preset[];
  /** Additional UnoCSS rules */
  rules?: UserConfig['rules'];
  /** Additional UnoCSS shortcuts */
  shortcuts?: UserConfig['shortcuts'];
  /** Any other UnoCSS config fields (safelist, blocklist, etc.) */
  [key: string]: unknown;
}

/**
 * Creates a complete UnoCSS config with all required presets, content scanning,
 * font loading, and theme from design tokens.
 *
 * This is the recommended way to set up UnoCSS with the UI library.
 * It replaces manually importing and composing presetWind, presetAnimations,
 * presetShadcn, presetUiLibraryThemeFromTokens, and presetUiLibraryUtils.
 *
 * @example
 * ```ts
 * // uno.config.ts — minimal
 * import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
 * export default defineUiLibraryConfig()
 *
 * // uno.config.ts — with theme customization
 * import { defineUiLibraryConfig } from '@aleph-alpha/ui-library/config'
 * export default defineUiLibraryConfig({
 *   extend: { light: { primary: '#ff5500' } },
 *   darkSelector: 'html.dark',
 *   rootFontSize: '100%',
 * })
 * ```
 */
export declare const defineUiLibraryConfig: (
  options?: UiLibraryConfigOptions,
) => UserConfig;
