@getdashfy/themes 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,318 @@
+import { ThemeMode } from '@getdashfy/types';
+export { ThemeMode } from '@getdashfy/types';
+
+interface ThemeColors {
+    background: string;
+    foreground: string;
+    card: string;
+    cardForeground: string;
+    popover: string;
+    popoverForeground: string;
+    primary: string;
+    primaryForeground: string;
+    secondary: string;
+    secondaryForeground: string;
+    muted: string;
+    mutedForeground: string;
+    accent: string;
+    accentForeground: string;
+    destructive: string;
+    destructiveForeground: string;
+    success: string;
+    successForeground: string;
+    warning: string;
+    warningForeground: string;
+    error: string;
+    errorForeground: string;
+    info: string;
+    infoForeground: string;
+    border: string;
+    input: string;
+    ring: string;
+    chart1: string;
+    chart2: string;
+    chart3: string;
+    chart4: string;
+    chart5: string;
+}
+interface ThemeFonts {
+    importHref: string;
+    cssVariables: {
+        '--font-sans': string;
+        '--font-serif'?: string;
+        '--font-mono': string;
+    };
+}
+interface Theme {
+    id: string;
+    name: string;
+    displayName: string;
+    fonts?: ThemeFonts;
+    light: {
+        colors: ThemeColors;
+        cssVariables: Record<string, string>;
+    };
+    dark: {
+        colors: ThemeColors;
+        cssVariables: Record<string, string>;
+    };
+}
+
+/**
+ * Default theme for Dashfy (shadcn/ui default).
+ */
+declare const defaultTheme: Theme;
+
+/**
+ * Kodama Grove theme for Dashfy.
+ *
+ * @link https://tweakcn.com/editor/theme?theme=kodama-grove
+ */
+declare const kodamaGroveTheme: Theme;
+
+/**
+ * Midnight Blue theme for Dashfy.
+ */
+declare const midnightBlueTheme: Theme;
+
+/**
+ * Minimal monochrome theme for Dashfy.
+ */
+declare const minimalTheme: Theme;
+
+/**
+ * Nord theme for Dashfy.
+ */
+declare const nordTheme: Theme;
+
+declare const themes: {
+    readonly default: Theme;
+    readonly kodamaGrove: Theme;
+    readonly midnightBlue: Theme;
+    readonly minimal: Theme;
+    readonly nord: Theme;
+};
+type PresetThemeId = keyof typeof themes;
+
+/**
+ * [Geist](https://fonts.google.com/specimen/Geist) + [Geist Mono](https://fonts.google.com/specimen/Geist+Mono) via the [Google Fonts CSS API](https://developers.google.com/fonts/docs/css2).
+ * `applyTheme` injects `importHref` as `<link rel="stylesheet">` on the document.
+ */
+declare const DEFAULT_FONT: ThemeFonts;
+/**
+ * Geist Mono ([Google Fonts](https://fonts.google.com/specimen/Geist+Mono)).
+ */
+declare const DEFAULT_FONT_MONO: ThemeFonts;
+
+declare const DEFAULT_FONTS_FALLBACK: Record<string, string>;
+interface GoogleFontEntry {
+    /** Font family name exactly as it appears on fonts.google.com (e.g. `'Source Serif 4'`). */
+    family: string;
+    /** Numeric weights to load (default: `[400]`). */
+    weights?: number[];
+    /** Override the default fallback stack (e.g. `'serif'`). */
+    fallback?: string;
+}
+interface GoogleFontConfig {
+    sans: GoogleFontEntry;
+    serif?: GoogleFontEntry;
+    mono: GoogleFontEntry;
+}
+/**
+ * Build a {@link ThemeFonts} object from a declarative config, so you never
+ * have to hand-craft Google Fonts URLs or CSS variable fallback stacks.
+ *
+ * @example
+ * ```ts
+ * import { googleFont } from '@getdashfy/themes'
+ *
+ * const fonts = googleFont({
+ *   sans:  { family: 'Merriweather', weights: [400, 500, 600, 700], fallback: 'serif' },
+ *   serif: { family: 'Source Serif 4', weights: [400, 500, 600, 700], fallback: 'serif' },
+ *   mono:  { family: 'JetBrains Mono', weights: [400, 500, 600, 700] },
+ * })
+ * ```
+ */
+declare function googleFont(config: GoogleFontConfig): ThemeFonts;
+
+/** Default theme to use when no theme is saved or selected. */
+declare const DEFAULT_THEME: PresetThemeId;
+/**
+ * Get a theme by ID.
+ *
+ * @param id - The theme identifier (e.g., 'default', 'minimal', 'nord')
+ * @returns The theme object
+ *
+ * @example
+ * ```ts
+ * import { getTheme } from '@getdashfy/themes'
+ *
+ * const minimalTheme = getTheme('minimal')
+ * console.log(minimalTheme.displayName) // "Minimal"
+ * ```
+ */
+declare function getTheme(id: PresetThemeId): Theme;
+/**
+ * Apply a theme by setting CSS variables on the document root element.
+ *
+ * This function:
+ * - Sets all theme CSS variables on `:root`
+ * - Adds a `data-theme` attribute for theme-specific CSS selectors
+ * - Applies the appropriate mode (light or dark) based on the current mode setting
+ * - Is safe to call in SSR environments (no-op when document is undefined)
+ *
+ * @param theme - The theme object to apply
+ * @param mode - Optional mode to apply ('light' or 'dark'). If not provided, uses current mode from DOM
+ *
+ * @example
+ * ```ts
+ * import { applyTheme, defaultTheme } from '@getdashfy/themes'
+ *
+ * // Apply default theme in light mode
+ * applyTheme(defaultTheme, 'light')
+ *
+ * // Apply default theme in dark mode
+ * applyTheme(defaultTheme, 'dark')
+ *
+ * // Apply theme using current mode from DOM
+ * applyTheme(defaultTheme)
+ * ```
+ */
+declare function applyTheme(theme: Theme, mode?: ThemeMode): void;
+/**
+ * Remove a theme by clearing its CSS variables from the document root.
+ *
+ * This function:
+ * - Removes all CSS variables defined by the theme
+ * - Removes the `data-theme` attribute
+ * - Is safe to call in SSR environments (no-op when document is undefined)
+ *
+ * @param theme - The theme object to remove
+ *
+ * @remarks
+ * Typically you would just apply a new theme instead of removing one.
+ * This function is useful for cleanup or testing scenarios.
+ *
+ * @example
+ * ```ts
+ * import { removeTheme, darkTheme } from '@getdashfy/themes'
+ *
+ * // Remove theme styling
+ * removeTheme(darkTheme)
+ * ```
+ */
+declare function removeTheme(theme: Theme): void;
+/**
+ * Get the currently applied theme ID from the document.
+ *
+ * Reads the `data-theme` attribute from the document root element.
+ *
+ * @returns The current theme ID, or null if no theme is applied or in SSR
+ *
+ * @example
+ * ```ts
+ * import { getCurrentTheme, applyTheme, darkTheme } from '@getdashfy/themes'
+ *
+ * applyTheme(darkTheme)
+ * const current = getCurrentTheme()
+ * console.log(current) // "dark"
+ * ```
+ */
+declare function getCurrentTheme(): PresetThemeId | null;
+/**
+ * Get an array of all available theme IDs.
+ *
+ * @returns Array of theme identifiers
+ *
+ * @example
+ * ```ts
+ * import { listThemes } from '@getdashfy/themes'
+ *
+ * const themeIds = listThemes()
+ * console.log(themeIds) // ["default", "minimal", "nord"]
+ *
+ * // Use in a theme selector
+ * themeIds.forEach(id => {
+ *   console.log(`Available theme: ${id}`)
+ * })
+ * ```
+ */
+declare function listThemes(): PresetThemeId[];
+interface CreateThemeOptions {
+    /** Unique theme identifier (e.g., 'custom-blue') */
+    id: string;
+    /** Internal theme name (e.g., 'customBlue') */
+    name: string;
+    /** Human-readable name shown in UI (e.g., 'Custom Blue') */
+    displayName: string;
+    /** Partial color overrides for light mode */
+    lightColors: Partial<ThemeColors>;
+    /** Partial color overrides for dark mode (optional, defaults to lightColors) */
+    darkColors?: Partial<ThemeColors>;
+    /** Base theme to extend from (defaults to defaultTheme) */
+    baseTheme?: Theme;
+    /** Override typography / Google Fonts (defaults to base theme) */
+    fonts?: ThemeFonts;
+}
+/**
+ * Create a custom theme by extending an existing theme.
+ *
+ * This utility function creates a new theme object by:
+ * - Merging your custom colors with a base theme
+ * - Automatically generating CSS variables from color names
+ * - Converting camelCase color names to kebab-case CSS variables
+ * - Supports both light and dark mode colors
+ *
+ * @param options - Theme configuration options
+ * @returns A complete theme object ready to use with `applyTheme()`
+ *
+ * @example Basic custom theme
+ * ```ts
+ * import { createTheme, applyTheme } from '@getdashfy/themes'
+ *
+ * const myTheme = createTheme({
+ *   id: 'ocean',
+ *   name: 'ocean',
+ *   displayName: 'Ocean Blue',
+ *   lightColors: {
+ *     primary: 'hsl(200 80% 50%)',
+ *     secondary: 'hsl(180 70% 50%)',
+ *   }
+ * })
+ *
+ * applyTheme(myTheme, 'light')
+ * ```
+ *
+ * @example Theme with different light and dark colors
+ * ```ts
+ * import { createTheme, applyTheme } from '@getdashfy/themes'
+ *
+ * const customTheme = createTheme({
+ *   id: 'custom',
+ *   name: 'custom',
+ *   displayName: 'Custom Theme',
+ *   lightColors: { primary: 'hsl(200 80% 50%)' },
+ *   darkColors: { primary: 'hsl(200 80% 70%)' }
+ * })
+ *
+ * applyTheme(customTheme, 'dark')
+ * ```
+ *
+ * @example Extending a different base theme
+ * ```ts
+ * import { createTheme, minimalTheme, applyTheme } from '@getdashfy/themes'
+ *
+ * const customMinimal = createTheme({
+ *   id: 'custom-minimal',
+ *   name: 'customMinimal',
+ *   displayName: 'Custom Minimal',
+ *   lightColors: { primary: 'hsl(0 0% 20%)' },
+ *   baseTheme: minimalTheme
+ * })
+ *
+ * applyTheme(customMinimal, 'light')
+ * ```
+ */
+declare function createTheme(options: CreateThemeOptions): Theme;
+
+export { type CreateThemeOptions, DEFAULT_FONT, DEFAULT_FONTS_FALLBACK, DEFAULT_FONT_MONO, DEFAULT_THEME, type GoogleFontConfig, type GoogleFontEntry, type PresetThemeId, type Theme, type ThemeColors, type ThemeFonts, applyTheme, createTheme, defaultTheme, getCurrentTheme, getTheme, googleFont, kodamaGroveTheme, listThemes, midnightBlueTheme, minimalTheme, nordTheme, removeTheme, themes };