@charstudios/pallet 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,400 @@
+import * as React from 'react';
+
+/**
+ * The full theming contract for a Pallet theme. Every field is optional in the
+ * partial variants used by presets and overrides; the resolved theme (produced
+ * by {@link resolveTheme}) always has concrete values.
+ */
+/** Any CSS color string. OKLCH is recommended to match shadcn's token system. */
+type CssColor = string;
+/** The set of color roles shadcn/ui expects, per color scheme. */
+interface ColorTokens {
+    background: CssColor;
+    foreground: CssColor;
+    card: CssColor;
+    cardForeground: CssColor;
+    popover: CssColor;
+    popoverForeground: CssColor;
+    primary: CssColor;
+    primaryForeground: CssColor;
+    secondary: CssColor;
+    secondaryForeground: CssColor;
+    muted: CssColor;
+    mutedForeground: CssColor;
+    accent: CssColor;
+    accentForeground: CssColor;
+    destructive: CssColor;
+    destructiveForeground: CssColor;
+    border: CssColor;
+    input: CssColor;
+    ring: CssColor;
+    chart1: CssColor;
+    chart2: CssColor;
+    chart3: CssColor;
+    chart4: CssColor;
+    chart5: CssColor;
+    sidebar: CssColor;
+    sidebarForeground: CssColor;
+    sidebarPrimary: CssColor;
+    sidebarPrimaryForeground: CssColor;
+    sidebarAccent: CssColor;
+    sidebarAccentForeground: CssColor;
+    sidebarBorder: CssColor;
+    sidebarRing: CssColor;
+}
+/** Typography configuration. Font values are CSS `font-family` stacks. */
+interface Typography {
+    /** Body font. Maps to `--font-sans`. */
+    sans: string;
+    /** Display/heading font. Maps to `--font-heading`. */
+    heading: string;
+    /** Monospace font. Maps to `--font-mono`. */
+    mono: string;
+    /**
+     * Google Font family names to auto-load at runtime (e.g. "Inter", "Outfit").
+     * Leave empty when fonts are self-hosted or provided by the host app.
+     */
+    googleFonts?: string[];
+}
+/**
+ * Roundness. `base` is the anchor radius (maps to `--radius`); the derived
+ * `--radius-sm..4xl` scale is computed from it, mirroring shadcn conventions.
+ */
+interface RadiusConfig {
+    /** Anchor radius, e.g. "0.45rem" or "1.25rem". Maps to `--radius`. */
+    base: string;
+    /** Multipliers used to derive the radius scale from `base`. */
+    scale?: Partial<RadiusScale>;
+}
+interface RadiusScale {
+    sm: number;
+    md: number;
+    lg: number;
+    xl: number;
+    "2xl": number;
+    "3xl": number;
+    "4xl": number;
+}
+/**
+ * Elevation controls the "skin" feel: shadows, border/ring strength and the
+ * surface treatment used by variant stylesheets.
+ */
+interface ElevationConfig {
+    /** Named shadow ramp. Each maps to `--shadow-*`. */
+    shadows: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+    /**
+     * Strength of hairline borders/rings on surfaces (0-1). Maps to
+     * `--surface-border-strength`, consumed by variant CSS.
+     */
+    borderStrength: number;
+    /**
+     * Default elevation level applied to elevated surfaces (cards, popovers).
+     * Maps to `--elevation` and references one of the shadow ramp keys.
+     */
+    level: "none" | "xs" | "sm" | "md" | "lg" | "xl";
+}
+/** Spacing density scales the base spacing unit and component paddings. */
+interface Density {
+    /** Base spacing unit, e.g. "0.25rem". Maps to `--spacing`. */
+    spacing: string;
+    /** Multiplier applied to component internal padding. Maps to `--density`. */
+    scale: number;
+}
+/** Motion controls animation duration and easing intensity. */
+interface Motion {
+    /** Base transition duration in ms. Maps to `--motion-duration`. */
+    duration: number;
+    /** CSS easing function. Maps to `--motion-ease`. */
+    easing: string;
+    /** 0 disables motion; 1 is full intensity. Maps to `--motion-intensity`. */
+    intensity: number;
+}
+/** Built-in visual variants ("skins"). Custom names are also allowed. */
+type VariantName = "flat" | "launch" | (string & {});
+/** A color scheme. */
+type ColorScheme = "light" | "dark";
+/**
+ * A complete theme. Presets are `ThemeConfig`; user overrides are
+ * `DeepPartial<ThemeConfig>` merged on top.
+ */
+interface ThemeConfig {
+    /** Identifier for this theme (used for persistence + tooling). */
+    name: string;
+    /** Which variant skin to apply. Sets `data-pallet-variant`. */
+    variant: VariantName;
+    /** Color tokens per scheme. */
+    colors: {
+        light: ColorTokens;
+        dark: ColorTokens;
+    };
+    typography: Typography;
+    radius: RadiusConfig;
+    elevation: ElevationConfig;
+    density: Density;
+    motion: Motion;
+}
+/** Recursive partial used for overrides and preset composition. */
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+type ThemeOverride = DeepPartial<ThemeConfig>;
+/** A flat map of CSS custom properties ("--primary" -> value). */
+type CssVarMap = Record<string, string>;
+
+/** Preference for the color scheme; "system" follows the OS setting. */
+type SchemePreference = ColorScheme | "system";
+/** The value exposed by {@link ThemeProvider} through {@link useTheme}. */
+interface PalletContextValue {
+    /** The fully resolved theme (base preset with overrides applied). */
+    theme: ThemeConfig;
+    /** The base preset before overrides. */
+    basePreset: ThemeConfig;
+    /** The current user overrides layered on top of the preset. */
+    overrides: ThemeOverride;
+    /** The actual color scheme currently rendered. */
+    scheme: ColorScheme;
+    /** The user's scheme preference (may be "system"). */
+    schemePreference: SchemePreference;
+    /** Resolved CSS variables for the current scheme. */
+    vars: CssVarMap;
+    /** Replaces the entire theme with a new preset (by object). Clears overrides. */
+    setTheme: (theme: ThemeConfig) => void;
+    /** Applies a built-in/custom preset by name or object. Clears overrides. */
+    applyPreset: (preset: ThemeConfig | string) => void;
+    /** Merges a partial override on top of the current overrides. */
+    updateTheme: (override: ThemeOverride) => void;
+    /** Clears all overrides, returning to the base preset. */
+    resetOverrides: () => void;
+    /** Sets the color-scheme preference. */
+    setSchemePreference: (preference: SchemePreference) => void;
+}
+declare const PalletContext: React.Context<PalletContextValue | null>;
+/** Reads the Pallet context. Throws if used outside a `ThemeProvider`. */
+declare function usePalletContext(): PalletContextValue;
+
+interface ThemeProviderProps {
+    children: React.ReactNode;
+    /**
+     * Preset to start from: a preset name (from built-ins or `presets`), or a
+     * full `ThemeConfig` object. Defaults to "flat".
+     */
+    defaultPreset?: ThemeConfig | string;
+    /** Initial overrides layered on top of the preset. */
+    defaultOverride?: ThemeOverride;
+    /** Initial color-scheme preference. Defaults to "system". */
+    defaultScheme?: SchemePreference;
+    /**
+     * Extra presets available to `applyPreset(name)`, merged with the built-ins.
+     */
+    presets?: Record<string, ThemeConfig>;
+    /**
+     * Where CSS variables are written:
+     * - "root" (default): on `document.documentElement`, plus the `.dark` class
+     *   and `data-pallet-variant` attribute. Best for app-wide theming.
+     * - "self": on a wrapper `<div>` this provider renders. Best for scoped
+     *   theming / previews. Emits SSR inline styles to avoid a flash.
+     */
+    scope?: "root" | "self";
+    /**
+     * If set, overrides + preset name + scheme are persisted to localStorage
+     * under this key and restored on mount.
+     */
+    storageKey?: string;
+    /** Class name applied to the wrapper element when `scope` is "self". */
+    className?: string;
+}
+declare function ThemeProvider({ children, defaultPreset, defaultOverride, defaultScheme, presets: extraPresets, scope, storageKey, className, }: ThemeProviderProps): React.JSX.Element;
+
+/**
+ * Access the full theming context: the resolved theme, current scheme, resolved
+ * CSS variables, and all mutation helpers. Must be used within a
+ * `<ThemeProvider>`.
+ */
+declare function useTheme(): PalletContextValue;
+
+/** Which scheme(s) a color update targets. */
+type SchemeTarget = ColorScheme | "both";
+interface ThemeControls {
+    /** Set a single color role for one or both schemes. */
+    setColor: (role: keyof ColorTokens, value: string, target?: SchemeTarget) => void;
+    /** Convenience for the primary color. */
+    setPrimary: (value: string, target?: SchemeTarget) => void;
+    /** Convenience for the accent color. */
+    setAccent: (value: string, target?: SchemeTarget) => void;
+    /** Merge multiple color roles at once for a given scheme. */
+    setColors: (colors: Partial<ColorTokens>, target?: SchemeTarget) => void;
+    /** Set the anchor radius (e.g. "0.5rem", "1.25rem"). */
+    setRadius: (base: string) => void;
+    /** Override individual radius-scale multipliers. */
+    setRadiusScale: (scale: Partial<RadiusScale>) => void;
+    /** Set one of the font stacks. */
+    setFont: (kind: "sans" | "heading" | "mono", family: string) => void;
+    /** Set the Google Font families to auto-load. */
+    setGoogleFonts: (families: string[]) => void;
+    /** Switch the visual variant/skin (sets `data-pallet-variant`). */
+    setVariant: (variant: VariantName) => void;
+    /** Set the default elevation level for surfaces. */
+    setElevationLevel: (level: ElevationConfig["level"]) => void;
+    /** Override a single shadow ramp entry. */
+    setShadow: (key: keyof ElevationConfig["shadows"], value: string) => void;
+    /** Set hairline border/ring strength (0-1). */
+    setBorderStrength: (value: number) => void;
+    /** Update spacing density. */
+    setDensity: (density: Partial<Density>) => void;
+    /** Update motion settings. */
+    setMotion: (motion: Partial<Motion>) => void;
+    /** Escape hatch: merge an arbitrary override. */
+    update: (override: ThemeOverride) => void;
+    /** Clear all overrides, returning to the base preset. */
+    reset: () => void;
+}
+/**
+ * Granular setters for building a theme-editor UI. Every setter layers an
+ * override on top of the active preset, so `reset()` always returns to a clean
+ * baseline. Colors default to updating both light and dark schemes; pass a
+ * target to scope them.
+ */
+declare function useThemeControls(): ThemeControls;
+
+interface UsePresetResult {
+    /** The active base preset. */
+    preset: ThemeConfig;
+    /** Names of the built-in presets. */
+    builtinNames: string[];
+    /** Apply a preset by name or object (clears overrides). */
+    applyPreset: (preset: ThemeConfig | string) => void;
+}
+/** Read the active preset and switch between presets. */
+declare function usePreset(): UsePresetResult;
+
+interface UseColorSchemeResult {
+    /** The actual scheme currently rendered. */
+    scheme: ColorScheme;
+    /** The user's preference (may be "system"). */
+    preference: SchemePreference;
+    /** Set the preference explicitly. */
+    setPreference: (preference: SchemePreference) => void;
+    /** Toggle between light and dark (resolves "system" to its current value). */
+    toggle: () => void;
+}
+/** Read and control the color scheme (light / dark / system). */
+declare function useColorScheme(): UseColorSchemeResult;
+
+/**
+ * Runtime Google Fonts loader. Injects a single stylesheet <link> for the given
+ * font families. Safe to call repeatedly: each unique family set is only loaded
+ * once, and the loader is a no-op on the server.
+ */
+interface GoogleFontsOptions {
+    /** Weights to request per family. Defaults to a useful range. */
+    weights?: number[];
+    /** `font-display` strategy. Defaults to "swap". */
+    display?: "auto" | "block" | "swap" | "fallback" | "optional";
+}
+/** Builds a Google Fonts CSS2 URL for the given families. */
+declare function buildGoogleFontsUrl(families: string[], options?: GoogleFontsOptions): string;
+/**
+ * Ensures the given Google Font families are loaded in the document. Returns the
+ * injected/updated <link> element, or null when running on the server or when
+ * there is nothing to load.
+ */
+declare function loadGoogleFonts(families: string[], options?: GoogleFontsOptions): HTMLLinkElement | null;
+
+/** Default radius multipliers, mirroring shadcn's derived `--radius-*` scale. */
+declare const DEFAULT_RADIUS_SCALE: RadiusScale;
+/** Converts a single color scheme's tokens into a CSS variable map. */
+declare function colorTokensToVars(tokens: ColorTokens): CssVarMap;
+/** Builds the scheme-independent CSS variables (radius, fonts, elevation, ...). */
+declare function structuralVars(theme: ThemeConfig): CssVarMap;
+/**
+ * Resolves a full theme into the CSS variables for a given color scheme.
+ * Combines the scheme's colors with the structural (scheme-independent) tokens.
+ */
+declare function resolveTheme(theme: ThemeConfig, scheme: ColorScheme): CssVarMap;
+/** Resolves only the color variables for a scheme (no structural tokens). */
+declare function resolveColors(theme: ThemeConfig, scheme: ColorScheme): CssVarMap;
+
+/**
+ * Applies a CSS variable map to a DOM element's inline style. Runs only in the
+ * browser; on the server it is a no-op (SSR should use {@link themeToCss}).
+ */
+declare function applyCssVars(element: HTMLElement | null | undefined, vars: CssVarMap): void;
+/** Removes the given CSS variable names from an element's inline style. */
+declare function clearCssVars(element: HTMLElement | null | undefined, names: string[]): void;
+/** Serializes a CSS variable map into a `key:value;` declaration string. */
+declare function cssVarsToString(vars: CssVarMap): string;
+
+/**
+ * Deeply merges `override` onto `base`, returning a new object. Arrays and
+ * primitives from `override` replace those in `base`; nested plain objects are
+ * merged recursively. `undefined` values in the override are ignored.
+ */
+declare function deepMerge<T>(base: T, override?: DeepPartial<T>): T;
+/** Merges any number of overrides left-to-right onto a base theme. */
+declare function mergeAll<T>(base: T, ...overrides: Array<DeepPartial<T> | undefined>): T;
+
+interface ThemeToCssOptions {
+    /**
+     * CSS selector the light-scheme variables are attached to. Defaults to
+     * `:root`. Use e.g. `[data-pallet-scope]` to scope a theme to a subtree.
+     */
+    selector?: string;
+    /**
+     * Selector for dark-scheme colors. Defaults to `.dark`, combined with
+     * `selector` (e.g. `.dark`, or `[data-pallet-scope].dark`). If you use the
+     * `.dark` class strategy this default is what you want.
+     */
+    darkSelector?: string;
+    /**
+     * When true, also emit `data-pallet-variant` as an attribute selector note in
+     * a comment. (The attribute itself is set by the provider or manually.)
+     */
+    includeVariantComment?: boolean;
+}
+/**
+ * Renders a full theme to a static CSS string, safe to inline in a server
+ * component (e.g. a Next.js layout) to avoid a flash of unstyled/incorrect
+ * theme before hydration.
+ *
+ * Structural tokens (radius, fonts, elevation, spacing, motion) are emitted on
+ * the light selector; dark-scheme *colors* are emitted on the dark selector.
+ */
+declare function themeToCss(theme: ThemeConfig, options?: ThemeToCssOptions): string;
+/** Serializes a theme (or override) to a compact JSON string for persistence. */
+declare function serializeTheme(theme: ThemeConfig | ThemeOverride): string;
+/** Parses a JSON string produced by {@link serializeTheme}. Returns null on error. */
+declare function deserializeTheme<T = ThemeOverride>(json: string): T | null;
+/** Produces the inline `style` attribute value for a scheme, for React usage. */
+declare function themeToInlineStyle(theme: ThemeConfig, scheme: ColorScheme): Record<string, string>;
+
+/**
+ * The "flat" preset: crisp hairline borders, minimal shadows, tighter radius.
+ * Mirrors the default Quill look and serves as the baseline variant.
+ */
+declare const flat: ThemeConfig;
+
+/**
+ * The "launch" preset: soft, elevated, and pill-shaped. Large radius, gentle
+ * layered shadows, subtle borders and a little extra breathing room. Pairs with
+ * `styles/variant-launch.css` which rounds controls into pills.
+ */
+declare const launch: ThemeConfig;
+
+/** All built-in presets, keyed by name. */
+declare const presets: {
+    flat: ThemeConfig;
+    launch: ThemeConfig;
+};
+type PresetName = keyof typeof presets;
+/** Returns a built-in preset by name, or undefined if it is not registered. */
+declare function getPreset(name: VariantName): ThemeConfig | undefined;
+/** The default preset used when none is specified. */
+declare const defaultPreset: ThemeConfig;
+
+export { type ColorScheme, type ColorTokens, type CssColor, type CssVarMap, DEFAULT_RADIUS_SCALE, type DeepPartial, type Density, type ElevationConfig, type GoogleFontsOptions, type Motion, PalletContext, type PalletContextValue, type PresetName, type RadiusConfig, type RadiusScale, type SchemePreference, type SchemeTarget, type ThemeConfig, type ThemeControls, type ThemeOverride, ThemeProvider, type ThemeProviderProps, type ThemeToCssOptions, type Typography, type UseColorSchemeResult, type UsePresetResult, type VariantName, applyCssVars, buildGoogleFontsUrl, clearCssVars, colorTokensToVars, cssVarsToString, deepMerge, defaultPreset, deserializeTheme, flat, getPreset, launch, loadGoogleFonts, mergeAll, presets, resolveColors, resolveTheme, serializeTheme, structuralVars, themeToCss, themeToInlineStyle, useColorScheme, usePalletContext, usePreset, useTheme, useThemeControls };