@frontmcp/ui 0.5.0

package/src/theme/theme.d.ts

@@ -0,0 +1,395 @@
+/**
+ * @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;