lucent-ui 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -283,8 +283,9 @@ export declare interface ComponentManifest {
  * - block:    Page-section-level composition (PageHeader, SidebarNav…)
  * - flow:     Multi-step or stateful sequences (Wizard, Onboarding…)
  * - overlay:  Layers above page content (Modal, Drawer, Tooltip…)
+ * - provider: Root configuration wrapper (LucentProvider…)
  */
-export declare type ComponentTier = 'atom' | 'molecule' | 'block' | 'flow' | 'overlay';
+export declare type ComponentTier = 'atom' | 'molecule' | 'block' | 'flow' | 'overlay' | 'provider';
 
 export declare interface CompositionNode {
     /** Component id this node refers to */
@@ -297,6 +298,35 @@ export declare interface CompositionNode {
     required: boolean;
 }
 
+/**
+ * Build a complete `LucentTokens` object from a minimal set of anchor colors.
+ *
+ * Variant tokens (hover, active, subtle, text, border, etc.) are derived
+ * automatically — you only need to specify the 9 anchor colors. The result
+ * can be passed directly to `<LucentProvider tokens={...}>`, or use the
+ * `anchors` prop shorthand to skip this call entirely.
+ *
+ * @param anchors - The 9 brand/semantic anchor colors.
+ * @param theme   - Target theme; defaults to `'light'`.
+ * @returns A fully-resolved `LucentTokens` ready for `LucentProvider`.
+ *
+ * @example
+ * const tokens = createTheme({
+ *   bgBase:         '#ffffff',
+ *   surface:        '#f9fafb',
+ *   borderDefault:  '#e5e7eb',
+ *   textPrimary:    '#111827',
+ *   accentDefault:  '#6366f1',
+ *   successDefault: '#22c55e',
+ *   warningDefault: '#f59e0b',
+ *   dangerDefault:  '#ef4444',
+ *   infoDefault:    '#3b82f6',
+ * });
+ *
+ * // <LucentProvider tokens={tokens}>...</LucentProvider>
+ */
+export declare function createTheme(anchors: ThemeAnchors, theme?: Theme): LucentTokens;
+
 export declare const darkTokens: LucentTokens;
 
 export declare const DATA_TABLE_MANIFEST: ComponentManifest;
@@ -368,6 +398,43 @@ export declare interface DateRangePickerProps {
     style?: CSSProperties;
 }
 
+/**
+ * Derives a complete dark-mode token set from a light-mode token set.
+ *
+ * Non-color tokens (typography, spacing, radius, motion) are inherited
+ * unchanged. Each semantic color group is mapped with a calibrated
+ * lightness inversion so the result is visually consistent with a
+ * hand-crafted dark theme.
+ *
+ * @example
+ * // Replacing the hardcoded dark.ts:
+ * export const darkTokens = deriveDarkFromLight(lightTokens);
+ *
+ * // Generating a dark theme from any custom light palette:
+ * const myDark = deriveDarkFromLight({ ...lightTokens, bgBase: '#f0f4ff' });
+ */
+export declare function deriveDarkFromLight(light: LucentTokens): LucentTokens;
+
+/**
+ * Derive variant tokens from anchor overrides.
+ *
+ * When the user provides an anchor token (e.g. `borderDefault`) without
+ * providing its variants (e.g. `borderSubtle`, `borderStrong`), this
+ * function computes those variants automatically using theme-calibrated
+ * lightness deltas.
+ *
+ * Rules:
+ * - Derivation only runs when the anchor is present in `overrides`.
+ * - A variant is only filled when it is absent from `overrides`.
+ * - Uses `'key' in overrides` (not truthiness) to respect
+ *   `exactOptionalPropertyTypes: true`.
+ *
+ * @param overrides - Raw `tokens` prop from the consumer.
+ * @param merged    - Base theme tokens already merged with overrides.
+ * @param theme     - Current theme; determines lightness delta direction.
+ */
+export declare function deriveTokens(overrides: Partial<LucentTokens>, merged: LucentTokens, theme: Theme): Partial<LucentTokens>;
+
 export declare function Divider({ orientation, label, spacing, style }: DividerProps): JSX_2.Element;
 
 export declare const DividerManifest: ComponentManifest;
@@ -486,15 +553,34 @@ declare interface LucentContextValue {
  * styles are applied synchronously before first paint.
  *
  * @example
- * <LucentProvider theme="dark">
+ * // Minimal: 9 anchor colors → full theme
+ * <LucentProvider anchors={{ bgBase: '#fff', accentDefault: '#6366f1', ... }}>
+ *   <App />
+ * </LucentProvider>
+ *
+ * @example
+ * // Full control via partial overrides
+ * <LucentProvider theme="dark" tokens={{ accentDefault: '#f59e0b' }}>
  *   <App />
  * </LucentProvider>
  */
-export declare function LucentProvider({ theme, tokens: tokenOverrides, children, }: LucentProviderProps): JSX_2.Element;
+export declare function LucentProvider({ theme, tokens: tokenOverrides, anchors, children, }: LucentProviderProps): JSX_2.Element;
+
+export declare const LucentProviderManifest: ComponentManifest;
 
 export declare interface LucentProviderProps {
     theme?: Theme;
+    /**
+     * Full or partial token overrides. Individual tokens can be set here and
+     * any missing variant tokens will be derived automatically.
+     */
     tokens?: Partial<LucentTokens>;
+    /**
+     * Shorthand for specifying only the 9 anchor colors and letting the library
+     * derive the full token set automatically. When provided, `tokens` is ignored.
+     * Equivalent to passing `tokens={createTheme(anchors, theme)}`.
+     */
+    anchors?: ThemeAnchors;
     children: ReactNode;
 }
 
@@ -689,9 +775,9 @@ export declare type SelectSize = 'sm' | 'md' | 'lg';
 declare interface SemanticColorTokens {
     bgBase: string;
     bgSubtle: string;
-    bgMuted: string;
     bgOverlay: string;
-    surfaceDefault: string;
+    surface: string;
+    surfaceSecondary: string;
     surfaceRaised: string;
     surfaceOverlay: string;
     borderDefault: string;
@@ -903,6 +989,44 @@ export declare type TextWeight = 'regular' | 'medium' | 'semibold' | 'bold';
 
 export declare type Theme = 'light' | 'dark';
 
+/**
+ * The minimal set of color tokens needed to produce a complete theme.
+ * Pass these to `createTheme()` or `<LucentProvider anchors={...}>` and
+ * all variant tokens (hover, active, subtle, text, etc.) are derived
+ * automatically.
+ *
+ * @example
+ * const myTheme = createTheme({
+ *   bgBase:          '#ffffff',
+ *   surface:         '#f9fafb',
+ *   borderDefault:   '#e5e7eb',
+ *   textPrimary:     '#111827',
+ *   accentDefault:   '#6366f1',
+ *   successDefault:  '#22c55e',
+ *   warningDefault:  '#f59e0b',
+ *   dangerDefault:   '#ef4444',
+ *   infoDefault:     '#3b82f6',
+ * });
+ */
+export declare type ThemeAnchors = Pick<LucentTokens, 'bgBase' | 'surface' | 'borderDefault' | 'textPrimary' | 'accentDefault' | 'successDefault' | 'warningDefault' | 'dangerDefault' | 'infoDefault'>;
+
+/**
+ * Semantic guidance for each ThemeAnchors key.
+ *
+ * An LLM reading this can translate a brand brief or hex palette directly
+ * into a valid ThemeAnchors object without needing to know internal token
+ * names or the derivation system. Each entry describes:
+ *   - what the token controls visually
+ *   - what range of colors is appropriate
+ *   - which variant tokens are automatically derived from it
+ */
+export declare const ThemeAnchorsSpec: Record<keyof ThemeAnchors, {
+    description: string;
+    lightGuidance: string;
+    darkGuidance: string;
+    derives: string[];
+}>;
+
 export declare function Timeline({ items, style }: TimelineProps): JSX_2.Element;
 
 export declare const TIMELINE_MANIFEST: ComponentManifest;