/**
* @fileoverview Unified Saasflare provider — light/dark mode, brand palette, surface, radius, animation.
* @module packages/ui/providers/saasflare-provider
* @package ui
*
* Single authority for the five design-system axes on :
* - class="dark" → owned by next-themes (light/dark mode)
* - data-palette="…" → preset or custom brand palette
* - data-style="flat|glass" → surface style (material)
* - data-radius="sharp|soft|rounded|pill" → radius preset (geometry)
* - data-animated="true|…" → global animation kill-switch
*
* Layering (lowest → highest specificity):
* 1. globals.css → baseline tokens
* 2. [data-palette="…"] → preset overrides (palettes.css) or
* app-registered selectors
* 3. Inline CSS vars → CustomPalette runtime overrides
*
* `palette` prop precedence:
* - omitted (undefined) → defers to persisted preference, then baseline
* - Preset id / string → forces [data-palette]
* - CustomPalette object → forces [data-palette] + injects inline vars
*
* For first-paint correctness when a non-baseline palette is persisted,
* render inside before any React hydration.
*/
import { type ReactNode } from "react";
import type { Palette, Radius, RadiusProp, StyleVariant, Surface } from "../types";
import type { IconWeight } from "../components/ui/phosphor";
/** Context value exposed by useSaasflareTheme(). */
interface SaasflareThemeContextType {
/** Active brand palette id, or null when using baseline. */
palette: string | null;
/** Active surface style. */
surface: StyleVariant;
/** Active radius preset. */
radius: Radius;
/** Active icon weight for component-rendered Phosphor icons. */
iconWeight: IconWeight;
/** Set the active brand palette (persists to localStorage). */
setPalette: (id: string) => void;
/** Set the active surface style (persists to localStorage). */
setSurface: (style: StyleVariant) => void;
/** Set the active radius preset (persists to localStorage). */
setRadius: (radius: Radius) => void;
/** Set the active icon weight (persists to localStorage). */
setIconWeight: (weight: IconWeight) => void;
}
/**
* Access the Saasflare theme context.
* Safe to call without a provider — returns baseline defaults.
*/
export declare function useSaasflareTheme(): SaasflareThemeContextType;
/** Props for SaasflareProvider. */
export interface SaasflareProviderProps {
children: ReactNode;
/**
* Light/dark mode (forwarded to next-themes).
* Distinct from `palette` (which selects the brand colors).
* @default "system"
*/
theme?: "light" | "dark" | "system";
/**
* Brand palette (distinct from `theme`, which is light/dark).
* - Preset id or arbitrary string → forces [data-palette] selector
* - CustomPalette object → forces palette via inline CSS vars
* - Omit to defer: uses persisted preference if any, otherwise baseline
*/
palette?: Palette;
/**
* Surface style.
* - StyleVariant → forces [data-style]
* - Omit to defer: uses persisted preference if any, otherwise "flat"
*/
surface?: Surface;
/**
* Radius preset (geometry axis — orthogonal to surface).
* - Radius → forces [data-radius]
* - Omit to defer: uses persisted preference if any, otherwise "rounded"
*/
radius?: RadiusProp;
/**
* Default icon weight for component-rendered Phosphor icons.
* - IconWeight ("regular" | "bold" | "fill" | "duotone") → forces the value
* - Omit to defer: uses persisted preference if any, otherwise "regular"
*/
iconWeight?: IconWeight;
/**
* Global animation kill switch.
* - boolean → forces the value
* - Omit to defer: uses persisted preference if any, otherwise `true`
*/
animated?: boolean;
/** Enable smooth scrolling site-wide. @default true */
smoothScrolling?: boolean;
/**
* Skip rendering the pre-hydration FOUT-prevention script.
* Set this to true if you are placing `` manually
* inside `` (e.g. for a strict CSP setup).
* @default false
*/
disableScript?: boolean;
/** CSP nonce forwarded to the pre-hydration script. */
scriptNonce?: string;
/**
* localStorage key for Saasflare prefs (palette, surface, radius, animated).
* Change this to namespace your app ("acme-ui-prefs"), to isolate tenants,
* or to avoid collisions. If you render `` manually in
* ``, pass the same value to its `storageKey` prop.
*
* Changing this key after users have persisted preferences orphans the
* old data — users will see defaults until they re-pick their preferences.
*
* @default "sf-ui-prefs"
*/
storageKey?: string;
/**
* localStorage key forwarded to next-themes for the light/dark mode
* preference. Change alongside `storageKey` when namespacing.
*
* @default "theme"
*/
themeStorageKey?: string;
}
/**
* Unified Saasflare provider.
*
* Manages light/dark mode (via next-themes), brand palette, surface style,
* radius preset, and a global animation kill switch in a single component.
*
* @component
* @package ui
*/
export declare function SaasflareProvider({ children, theme, palette, surface, radius, iconWeight, animated, smoothScrolling, disableScript, scriptNonce, storageKey, themeStorageKey, }: SaasflareProviderProps): import("react/jsx-runtime").JSX.Element;
export {};