lucent-ui 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -203,6 +203,46 @@ export declare interface CollapsibleProps {
     style?: CSSProperties;
 }
 
+export declare const COLOR_PICKER_MANIFEST: ComponentManifest;
+
+export declare const COLOR_SWATCH_MANIFEST: ComponentManifest;
+
+export declare function ColorPicker({ value, onChange, label, disabled, presetGroups, id, style, }: ColorPickerProps): JSX_2.Element;
+
+export declare namespace ColorPicker {
+    var displayName: string;
+}
+
+export declare interface ColorPickerProps {
+    value?: string;
+    onChange?: (hex: string) => void;
+    label?: string;
+    disabled?: boolean;
+    presetGroups?: ColorPresetGroup[];
+    id?: string;
+    style?: CSSProperties;
+}
+
+export declare interface ColorPresetGroup {
+    label: string;
+    colors: string[];
+}
+
+export declare const ColorSwatch: ForwardRefExoticComponent<ColorSwatchProps & RefAttributes<HTMLButtonElement>>;
+
+export declare interface ColorSwatchProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color'> {
+    color: string;
+    size?: ColorSwatchSize;
+    shape?: ColorSwatchShape;
+    /** Show a checkerboard underneath — use when color may have transparency */
+    showCheckerboard?: boolean;
+    selected?: boolean;
+}
+
+export declare type ColorSwatchShape = 'circle' | 'square';
+
+export declare type ColorSwatchSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
 export declare const COMMAND_PALETTE_MANIFEST: ComponentManifest;
 
 export declare interface CommandItem {
@@ -283,8 +323,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 +338,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 +438,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;
@@ -458,15 +565,24 @@ export declare const Input: ForwardRefExoticComponent<InputProps & RefAttributes
 
 export declare const InputManifest: ComponentManifest;
 
-export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'prefix'> {
     type?: InputType;
+    size?: InputSize;
     label?: string;
     helperText?: string;
     errorText?: string;
+    /** Icon/element floated inside the left edge — does not resize the field */
     leftElement?: ReactNode;
+    /** Icon/element floated inside the right edge — does not resize the field */
     rightElement?: ReactNode;
+    /** Inset label attached to the left of the field (e.g. "$", "https://") */
+    prefix?: ReactNode;
+    /** Inset label attached to the right of the field (e.g. "kg", ".com") */
+    suffix?: ReactNode;
 }
 
+declare type InputSize = 'sm' | 'md' | 'lg';
+
 export declare type InputType = 'text' | 'number' | 'password' | 'email' | 'tel' | 'url' | 'search' | 'color';
 
 export declare function isValidPropDescriptor(prop: unknown): prop is PropDescriptor;
@@ -486,15 +602,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;
 }
 
@@ -665,6 +800,38 @@ export declare interface SearchResult {
     label: string;
 }
 
+export declare const SEGMENTED_CONTROL_MANIFEST: ComponentManifest;
+
+export declare function SegmentedControl({ options, value, defaultValue, onChange, size, disabled, fullWidth, id, style, }: SegmentedControlProps): JSX_2.Element;
+
+export declare namespace SegmentedControl {
+    var displayName: string;
+}
+
+export declare interface SegmentedControlProps {
+    options: SegmentedOption[];
+    /** Controlled selected value */
+    value?: string;
+    /** Initial value for uncontrolled usage */
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    size?: SegmentedControlSize;
+    /** Disabled all options */
+    disabled?: boolean;
+    /** Stretch to fill available width */
+    fullWidth?: boolean;
+    id?: string;
+    style?: CSSProperties;
+}
+
+export declare type SegmentedControlSize = 'sm' | 'md' | 'lg';
+
+export declare interface SegmentedOption {
+    value: string;
+    label: ReactNode;
+    disabled?: boolean;
+}
+
 export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;
 
 export declare const SelectManifest: ComponentManifest;
@@ -689,9 +856,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 +1070,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;