@frontmcp/ui 0.5.0 → 0.6.0

package/src/theme/theme.d.ts

@@ -1,395 +0,0 @@
-/**
- * @file theme.ts
- * @description Theme Configuration System for FrontMCP UI.
- *
- * Provides a comprehensive theming system with:
- * - Color palettes with semantic naming
- * - Typography configuration
- * - Spacing and sizing
- * - Component-specific tokens
- * - Customizable CDN URLs for fonts, icons, and scripts
- * - Dark mode support
- * - Tailwind CSS v4 @theme integration
- *
- * @example
- * ```typescript
- * import { createTheme, DEFAULT_THEME } from '@frontmcp/ui';
- *
- * // Use the default GitHub/OpenAI theme
- * const theme = DEFAULT_THEME;
- *
- * // Or create a custom theme
- * const customTheme = createTheme({
- *   colors: {
- *     semantic: { primary: '#0969da' },
- *   },
- *   cdn: {
- *     fonts: {
- *       preconnect: ['https://fonts.googleapis.com'],
- *       stylesheets: ['https://fonts.googleapis.com/css2?family=Roboto&display=swap'],
- *     },
- *   },
- * });
- * ```
- *
- * @module @frontmcp/ui/theme
- */
-/**
- * Deep partial type - makes all properties and nested properties optional
- */
-export type DeepPartial<T> = T extends object ? {
-    [P in keyof T]?: DeepPartial<T[P]>;
-} : T;
-/**
- * Semantic color scale (50-950)
- */
-export interface ColorScale {
-    50?: string;
-    100?: string;
-    200?: string;
-    300?: string;
-    400?: string;
-    500?: string;
-    600?: string;
-    700?: string;
-    800?: string;
-    900?: string;
-    950?: string;
-}
-/**
- * Semantic color tokens
- */
-export interface SemanticColors {
-    /** Primary brand color */
-    primary: string | ColorScale;
-    /** Secondary brand color */
-    secondary?: string | ColorScale;
-    /** Accent/highlight color */
-    accent?: string | ColorScale;
-    /** Neutral/gray tones */
-    neutral?: string | ColorScale;
-    /** Success state */
-    success?: string;
-    /** Warning state */
-    warning?: string;
-    /** Error/danger state */
-    danger?: string;
-    /** Info state */
-    info?: string;
-}
-/**
- * Surface colors for backgrounds
- */
-export interface SurfaceColors {
-    /** Page background */
-    background?: string;
-    /** Card/panel background */
-    surface?: string;
-    /** Elevated surface (modal, dropdown) */
-    elevated?: string;
-    /** Overlay/backdrop */
-    overlay?: string;
-}
-/**
- * Text colors
- */
-export interface TextColors {
-    /** Primary text */
-    primary?: string;
-    /** Secondary/muted text */
-    secondary?: string;
-    /** Disabled text */
-    disabled?: string;
-    /** Inverse text (on dark backgrounds) */
-    inverse?: string;
-    /** Link text */
-    link?: string;
-}
-/**
- * Border colors
- */
-export interface BorderColors {
-    /** Default border */
-    default?: string;
-    /** Hover border */
-    hover?: string;
-    /** Focus border */
-    focus?: string;
-    /** Divider lines */
-    divider?: string;
-}
-/**
- * Complete color configuration
- */
-export interface ThemeColors {
-    /** Semantic colors */
-    semantic: SemanticColors;
-    /** Surface/background colors */
-    surface?: SurfaceColors;
-    /** Text colors */
-    text?: TextColors;
-    /** Border colors */
-    border?: BorderColors;
-    /** Additional custom colors */
-    custom?: Record<string, string>;
-}
-/**
- * Font family configuration
- */
-export interface FontFamilies {
-    /** Sans-serif (default) */
-    sans?: string;
-    /** Serif */
-    serif?: string;
-    /** Monospace */
-    mono?: string;
-    /** Display/heading */
-    display?: string;
-}
-/**
- * Font size configuration
- */
-export interface FontSizes {
-    xs?: string;
-    sm?: string;
-    base?: string;
-    lg?: string;
-    xl?: string;
-    '2xl'?: string;
-    '3xl'?: string;
-    '4xl'?: string;
-    '5xl'?: string;
-}
-/**
- * Font weight configuration
- */
-export interface FontWeights {
-    normal?: string;
-    medium?: string;
-    semibold?: string;
-    bold?: string;
-}
-/**
- * Complete typography configuration
- */
-export interface ThemeTypography {
-    families?: FontFamilies;
-    sizes?: FontSizes;
-    weights?: FontWeights;
-    lineHeight?: {
-        tight?: string;
-        normal?: string;
-        relaxed?: string;
-    };
-}
-/**
- * Spacing scale
- */
-export interface ThemeSpacing {
-    px?: string;
-    0?: string;
-    1?: string;
-    2?: string;
-    3?: string;
-    4?: string;
-    5?: string;
-    6?: string;
-    8?: string;
-    10?: string;
-    12?: string;
-    16?: string;
-    20?: string;
-    24?: string;
-}
-/**
- * Border radius
- */
-export interface ThemeRadius {
-    none?: string;
-    sm?: string;
-    md?: string;
-    lg?: string;
-    xl?: string;
-    '2xl'?: string;
-    full?: string;
-}
-/**
- * Shadow configuration
- */
-export interface ThemeShadows {
-    sm?: string;
-    md?: string;
-    lg?: string;
-    xl?: string;
-}
-/**
- * Button component tokens
- */
-export interface ButtonTokens {
-    radius?: string;
-    paddingX?: string;
-    paddingY?: string;
-    fontSize?: string;
-    fontWeight?: string;
-}
-/**
- * Card component tokens
- */
-export interface CardTokens {
-    radius?: string;
-    padding?: string;
-    shadow?: string;
-    borderWidth?: string;
-}
-/**
- * Input component tokens
- */
-export interface InputTokens {
-    radius?: string;
-    paddingX?: string;
-    paddingY?: string;
-    borderWidth?: string;
-    focusRingWidth?: string;
-}
-/**
- * Component-specific tokens
- */
-export interface ComponentTokens {
-    button?: ButtonTokens;
-    card?: CardTokens;
-    input?: InputTokens;
-}
-/**
- * Script resource with optional integrity hash
- */
-export interface CdnScriptResource {
-    /** URL to the script */
-    url: string;
-    /** Subresource integrity hash */
-    integrity?: string;
-}
-/**
- * Font CDN configuration
- */
-export interface ThemeCdnFonts {
-    /** Preconnect URLs for font providers */
-    preconnect?: string[];
-    /** Font stylesheet URLs */
-    stylesheets?: string[];
-}
-/**
- * Icon CDN configuration
- */
-export interface ThemeCdnIcons {
-    /** Icon library script */
-    script?: CdnScriptResource;
-}
-/**
- * Scripts CDN configuration
- */
-export interface ThemeCdnScripts {
-    /** Tailwind CSS Browser CDN URL */
-    tailwind?: string;
-    /** HTMX script resource */
-    htmx?: CdnScriptResource;
-    /** Alpine.js script resource */
-    alpine?: CdnScriptResource;
-}
-/**
- * Complete CDN configuration for theme
- *
- * Allows customizing all external resource URLs used by the theme.
- * Useful for:
- * - Using private CDN mirrors
- * - Self-hosting resources
- * - Compliance with CSP policies
- * - Using different font families
- */
-export interface ThemeCdnConfig {
-    /** Font configuration */
-    fonts?: ThemeCdnFonts;
-    /** Icon library configuration */
-    icons?: ThemeCdnIcons;
-    /** Script CDN configuration */
-    scripts?: ThemeCdnScripts;
-}
-/**
- * Complete theme configuration
- */
-export interface ThemeConfig {
-    /** Theme name/identifier */
-    name?: string;
-    /** Color configuration */
-    colors: ThemeColors;
-    /** Typography configuration */
-    typography?: ThemeTypography;
-    /** Spacing scale */
-    spacing?: ThemeSpacing;
-    /** Border radius */
-    radius?: ThemeRadius;
-    /** Shadows */
-    shadows?: ThemeShadows;
-    /** Component-specific tokens */
-    components?: ComponentTokens;
-    /** CDN resource configuration */
-    cdn?: ThemeCdnConfig;
-    /** Dark mode variant */
-    dark?: Partial<ThemeConfig>;
-    /** Additional CSS custom properties */
-    customVars?: Record<string, string>;
-    /** Additional CSS (outside @theme) */
-    customCss?: string;
-}
-/**
- * Default FrontMCP theme - GitHub/OpenAI inspired gray-black aesthetic
- *
- * Re-exported from presets for convenience. The default theme features:
- * - Monochromatic gray-black color palette
- * - System UI font stack
- * - Smaller border radii (GitHub style)
- * - Subtle shadows with gray tones
- *
- * @see ./presets/github-openai.ts for full theme definition
- */
-export declare const GITHUB_OPENAI_THEME: ThemeConfig;
-export declare const DEFAULT_THEME: ThemeConfig;
-/**
- * Deep merge two theme configurations
- *
- * @remarks
- * Dark variant handling:
- * - When override.dark is provided, it's merged on top of base.dark (if present) or base
- * - The resulting dark variant never contains a nested .dark property
- * - This prevents infinite recursion and ensures clean dark theme composition
- */
-export declare function mergeThemes(base: ThemeConfig, override: DeepPartial<ThemeConfig>): ThemeConfig;
-/**
- * Create a theme by extending the default theme
- */
-export declare function createTheme(overrides: Partial<ThemeConfig>): ThemeConfig;
-/**
- * Build Tailwind @theme CSS from theme configuration
- */
-export declare function buildThemeCss(theme: ThemeConfig): string;
-/**
- * Build complete style block with @theme and custom CSS
- *
- * @remarks
- * **Security/Trust Model:**
- * The `theme.customCss` property is injected directly into a `<style>` tag without
- * sanitization. This is intentional - CSS customization requires full CSS syntax support.
- *
- * **Trust assumptions:**
- * - Theme configurations should only come from trusted sources (developer-defined themes)
- * - Never pass user-provided input directly to `customCss`
- * - If you need user-customizable styles, validate/sanitize them before including in a theme
- *
- * **Why no sanitization:**
- * - CSS sanitization is complex and often breaks legitimate styles
- * - The theme system is designed for developer use, not end-user customization
- * - Developers creating themes are trusted to provide safe CSS
- *
- * @param theme - Theme configuration with optional customCss
- * @returns HTML style block with Tailwind @theme directive
- */
-export declare function buildStyleBlock(theme: ThemeConfig): string;