glintly-ui 1.0.3 → 1.0.4

package/dist/glintly-ui.d.ts

@@ -79,6 +79,16 @@ declare type AvatarTheme = 'default' | 'gradient-blue' | 'gradient-purple' | 'gr
 
 declare type AvatarVariant = 'circle' | 'square';
 
+/**
+ * Background colors for different surface levels
+ */
+export declare interface BackgroundColors {
+    base: string;
+    surface: string;
+    elevated: string;
+    overlay: string;
+}
+
 export declare const Badge: default_2.FC<BadgeProps_2>;
 
 export declare const BadgeGroup: default_2.FC<BadgeGroupProps>;
@@ -123,23 +133,85 @@ declare type BadgeSize = 'xs' | 'sm' | 'md' | 'lg';
 
 declare type BadgeVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'gray';
 
-declare interface BorderRadius {
+/**
+ * Border colors
+ */
+export declare interface BorderColors {
+    default: string;
+    hover: string;
+    focus: string;
+    disabled: string;
+}
+
+export declare interface BorderRadius {
+    none: string;
+    sm: string;
+    base: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    '3xl': string;
+    full: string;
+    [key: string]: string;
+}
+
+export declare interface BorderWidth {
+    0: string;
+    1: string;
+    2: string;
+    4: string;
+    8: string;
     [key: string]: string;
 }
 
-export declare const BoxIcon: default_2.FC<{
+export declare const BoxIcon: default_2.FC<BoxIconProps>;
+
+/**
+ * BoxIcon
+ *
+ * Public, framework-agnostic icon component (similar to react-icons).
+ *
+ * - If `name` matches a built-in SVG icon key, it renders the inline SVG.
+ * - Otherwise, it falls back to the `<box-icon>` web component (Boxicons).
+ *
+ * **Color Inheritance (like react-icons):**
+ * - If no `color` prop is provided, icons use `currentColor` and inherit color from CSS.
+ * - If `color` prop is provided, it overrides the inherited color.
+ *
+ * You can use either:
+ * - `name="home"` (preferred for public usage)
+ * - `name="lib-home"` (backwards-compatible alias, still supported)
+ */
+declare interface BoxIconProps {
+    /** Icon name. Matches built-in SVG keys or Boxicons names. */
     name: string;
+    /**
+     * Optional color applied to SVG fill or Boxicon color.
+     * If not provided, icon will use `currentColor` and inherit from parent CSS.
+     */
     color?: string;
+    /** Boxicons type (e.g., 'solid', 'regular', 'logo') for web component fallback. */
     type?: string;
+    /** Explicit height for the icon (e.g., '20', '20px'). */
     height?: string;
+    /** Explicit width for the icon (e.g., '20', '20px'). */
     width?: string;
+    /** Additional inline styles applied to the wrapper / SVG. */
     style?: default_2.CSSProperties;
+    /** Optional CSS class for the wrapper. */
     className?: string;
-}>;
+}
 
 declare type BreakpointKey = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
 
-declare interface Breakpoints {
+export declare interface Breakpoints {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
     [key: string]: string;
 }
 
@@ -150,7 +222,12 @@ export declare interface ButtonProps extends Omit<default_2.ButtonHTMLAttributes
     variant?: ButtonVariant;
     size?: ButtonSize;
     shade?: ShadeKey;
-    icon?: IconProp_2;
+    /** Optional icon rendered before the children */
+    startIcon?: default_2.ReactNode;
+    /** Optional icon rendered after the children */
+    endIcon?: default_2.ReactNode;
+    /** When true, button renders only the icon (no text padding) */
+    iconOnly?: boolean;
     shadow?: ButtonShadow;
     border?: boolean;
     fullWidth?: boolean;
@@ -217,6 +294,19 @@ declare interface CarouselSlide {
     alt?: string;
 }
 
+/**
+ * Check if a color meets WCAG contrast requirements
+ *
+ * @param foreground - Foreground color (hex)
+ * @param background - Background color (hex)
+ * @param level - WCAG level ('AA' or 'AAA')
+ * @param size - 'normal' or 'large' text
+ */
+export declare function checkContrast(foreground: string, background: string, level?: 'AA' | 'AAA', size?: 'normal' | 'large'): {
+    pass: boolean;
+    ratio: number;
+};
+
 export declare const CodeViewer: default_2.FC<CodeViewerProps>;
 
 declare interface CodeViewerProps {
@@ -235,13 +325,27 @@ declare interface CodeViewerProps {
 
 export declare const Col: default_2.FC<ColProps>;
 
-declare interface Colors {
-    light: ColorVariant;
-    dark: ColorVariant;
-}
-
-declare type ColorScale = {
-    25?: string;
+/**
+ * Complete color palette for a theme
+ */
+export declare interface Colors {
+    semantic: SemanticColors;
+    neutral: NeutralColors;
+    background: BackgroundColors;
+    text: TextColors;
+    border: BorderColors;
+    [key: string]: any;
+}
+
+/**
+ * Glintly UI Theme System
+ * A flexible, type-safe theme system for React applications
+ */
+/**
+ * Color scale with semantic intensity levels
+ * Common pattern: 50 (lightest) to 900 (darkest)
+ */
+export declare interface ColorScale {
     50?: string;
     100?: string;
     200?: string;
@@ -252,25 +356,6 @@ declare type ColorScale = {
     700?: string;
     800?: string;
     900?: string;
-};
-
-declare interface ColorVariant {
-    primary: ColorScale;
-    secondary: ColorScale;
-    background: string;
-    surface: string;
-    text: {
-        primary: string;
-        secondary: string;
-        disabled: string;
-    };
-    error: ColorScale;
-    success: ColorScale;
-    warning: ColorScale;
-    gray: ColorScale;
-    yellow: ColorScale;
-    iconButton: ColorScale;
-    info: ColorScale;
 }
 
 declare type ColProps = {
@@ -313,6 +398,39 @@ declare interface ContainerProps extends default_2.HTMLAttributes<HTMLDivElement
     children?: default_2.ReactNode;
 }
 
+/**
+ * Create a color scale from a single base color
+ * Generates lighter and darker shades
+ *
+ * @param baseColor - The base color in hex format
+ * @param adjustments - Optional custom adjustments for each shade
+ */
+export declare function createColorScale(baseColor: string, adjustments?: Partial<ColorScale>): ColorScale;
+
+/**
+ * Create a custom theme from scratch
+ *
+ * @example
+ * ```ts
+ * import { createTheme } from 'glintly-ui/themes';
+ *
+ * const myTheme = createTheme({
+ *   colors: {
+ *     semantic: {
+ *       primary: createColorScale('#ff0000'),
+ *       // ... other colors
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function createTheme(config: Partial<Theme>, baseTheme?: Theme): Theme;
+
+/**
+ * Cyan theme - Cyan & Blue
+ */
+export declare const cyanTheme: ThemeSet;
+
 declare interface Data {
     title?: string;
     subTitle?: string;
@@ -410,6 +528,11 @@ declare const defaultFontSizes: {
 
 declare const defaultLineHeights: Record<string, string>;
 
+/**
+ * Default theme - Blue & Purple
+ */
+export declare const defaultTheme: ThemeSet;
+
 export { Dropdown }
 
 export { DropdownDivider }
@@ -428,6 +551,20 @@ export { DropdownText }
 
 export { DropdownToggle }
 
+export declare interface Effects {
+    blur: {
+        [key: string]: string;
+    };
+    opacity: {
+        [key: string]: string;
+    };
+}
+
+/**
+ * Emerald theme - Green & Teal
+ */
+export declare const emeraldTheme: ThemeSet;
+
 export declare const ErrorPage: default_2.FC<ErrorPageProps>;
 
 declare interface ErrorPageProps extends EyesVariantProps, ConnectionVariantsProp, ComingSoonProps, ConnectionErrorProps {
@@ -468,6 +605,68 @@ declare interface FilterField {
     placeholder?: string;
 }
 
+export declare interface FontSizes {
+    xs: string;
+    sm: string;
+    base: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    '3xl': string;
+    '4xl': string;
+    '5xl': string;
+    [key: string]: string;
+}
+
+export declare interface FontWeights {
+    thin: number;
+    extralight: number;
+    light: number;
+    normal: number;
+    medium: number;
+    semibold: number;
+    bold: number;
+    extrabold: number;
+    black: number;
+    [key: string]: number;
+}
+
+/**
+ * Generate CSS string from theme variables
+ *
+ * @example
+ * ```ts
+ * import { generateCSSString, getTheme } from 'glintly-ui/themes';
+ *
+ * const theme = getTheme('default', 'light');
+ * const cssString = generateCSSString(theme);
+ * // Inject into <style> tag or write to file
+ * ```
+ */
+export declare function generateCSSString(theme: Theme, selector?: string, prefix?: string): string;
+
+/**
+ * Get a color from the theme with fallback
+ *
+ * @example
+ * ```ts
+ * import { getColor } from 'glintly-ui/themes';
+ *
+ * const primaryColor = getColor(theme, 'semantic.primary.500', '#3b82f6');
+ * ```
+ */
+export declare function getColor(theme: Theme, path: string, fallback?: string): string;
+
+/**
+ * Get the default theme
+ */
+export declare function getDefaultTheme(mode?: 'light' | 'dark'): Theme;
+
+/**
+ * Get a theme by name and mode
+ */
+export declare function getTheme(themeName: string, mode: 'light' | 'dark'): Theme;
+
 declare type IconPosition = 'left' | 'right' | 'both' | "onlyIcon";
 
 declare type IconPosition_2 = 'left' | 'right' | 'both' | "onlyIcon";
@@ -564,6 +763,16 @@ declare type InternalStepProps = StepProps & {
     last?: boolean;
 };
 
+export declare interface LineHeights {
+    none: string;
+    tight: string;
+    snug: string;
+    normal: string;
+    relaxed: string;
+    loose: string;
+    [key: string]: string;
+}
+
 export { List }
 
 export { ListDivider }
@@ -572,7 +781,63 @@ export { ListItem }
 
 export { ListSectionHeader }
 
-export declare const Modal: default_2.FC<ModalProps>;
+/**
+ * Merge a custom theme with a base theme
+ *
+ * @example
+ * ```ts
+ * import { mergeTheme, getTheme } from 'glintly-ui/themes';
+ *
+ * const customTheme = mergeTheme(
+ *   getTheme('default', 'light'),
+ *   {
+ *     colors: {
+ *       semantic: {
+ *         primary: {
+ *           500: '#ff0000',
+ *         },
+ *       },
+ *     },
+ *   }
+ * );
+ * ```
+ */
+export declare function mergeTheme(baseTheme: Theme, customTheme: Partial<Theme>): Theme;
+
+/**
+ * Merge a theme set (light and dark variants)
+ *
+ * @example
+ * ```ts
+ * import { mergeThemeSet, themes } from 'glintly-ui/themes';
+ *
+ * const customThemeSet = mergeThemeSet(themes.default, {
+ *   light: {
+ *     colors: {
+ *       semantic: {
+ *         primary: myCustomColorScale,
+ *       },
+ *     },
+ *   },
+ *   dark: {
+ *     colors: {
+ *       semantic: {
+ *         primary: myCustomColorScale,
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function mergeThemeSet(baseThemeSet: ThemeSet, customThemeSet: Partial<ThemeSet>): ThemeSet;
+
+export declare const Modal: ModalCompound;
+
+declare interface ModalCompound extends default_2.FC<ModalProps> {
+    Header: default_2.FC<ModalSectionProps>;
+    Body: default_2.FC<ModalSectionProps>;
+    Footer: default_2.FC<ModalSectionProps>;
+}
 
 export declare interface ModalProps {
     /** Whether the modal is open */
@@ -625,40 +890,97 @@ export declare interface ModalProps {
     animationDuration?: number;
 }
 
-declare type ModeType = 'light' | 'dark';
+declare interface ModalSectionProps {
+    children: default_2.ReactNode;
+    className?: string;
+    style?: default_2.CSSProperties;
+}
 
 export declare const Navbar: default_2.FC<NavbarProps>;
 
+/**
+ * Navigation link item configuration
+ */
 declare interface NavbarLinkItem {
+    /** Link label text */
     label: string;
+    /** URL for anchor links (if provided, renders as <a>) */
     href?: string;
-    icon?: string;
+    /** Icon name (uses BoxIcon) or React node for custom icon */
+    icon?: string | default_2.ReactNode;
+    /** Whether this link is currently active */
     active?: boolean;
+    /** Whether this link is disabled */
     disabled?: boolean;
+    /** Click handler (used when href is not provided) */
     onClick?: (e: default_2.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => void;
+    /** Additional CSS class */
+    className?: string;
+    /** Additional inline styles */
+    style?: default_2.CSSProperties;
 }
 
 declare type NavbarPosition = "static" | "sticky" | "fixed";
 
+/**
+ * Navbar component props
+ *
+ * A flexible, responsive navigation bar component with support for:
+ * - Multiple variants (solid, transparent, elevated)
+ * - Responsive collapse to hamburger menu
+ * - Custom branding (logo and/or text)
+ * - Navigation links with icons
+ * - Action buttons/items
+ * - Full theme integration
+ */
 declare interface NavbarProps {
+    /** Brand title text */
     title?: string;
+    /** Brand logo image source */
     logoSrc?: string;
+    /** Custom brand content (overrides title/logoSrc) */
+    brand?: default_2.ReactNode;
+    /** Click handler for brand area */
     onBrandClick?: () => void;
+    /** Array of navigation link items */
     links?: NavbarLinkItem[];
+    /** Action buttons or other content (rendered on the right side) */
     actions?: default_2.ReactNode;
+    /** Alignment of navigation links */
     align?: "left" | "center" | "right";
+    /** Whether navbar should span full width */
     fullWidth?: boolean;
+    /** Visual variant */
     variant?: NavbarVariant;
+    /** Position behavior */
     position?: NavbarPosition;
+    /** Size preset */
     size?: NavbarSize;
+    /** Breakpoint in pixels for collapsing into hamburger menu */
     collapseAt?: number;
+    /** Custom CSS class */
     className?: string;
+    /** Custom inline styles */
+    style?: default_2.CSSProperties;
+    /** Custom icon for menu toggle (open state) */
+    menuOpenIcon?: string | default_2.ReactNode;
+    /** Custom icon for menu toggle (closed state) */
+    menuCloseIcon?: string | default_2.ReactNode;
 }
 
 declare type NavbarSize = "sm" | "md" | "lg";
 
 declare type NavbarVariant = "solid" | "transparent" | "elevated";
 
+/**
+ * Neutral/gray color palette
+ */
+export declare interface NeutralColors {
+    gray: ColorScale;
+    slate?: ColorScale;
+    zinc?: ColorScale;
+}
+
 export declare const Offcanvas: default_2.FC<OffcanvasProps>;
 
 declare interface OffcanvasProps {
@@ -677,8 +999,18 @@ declare type Option_2 = {
     value: string | number;
 };
 
+/**
+ * Orange theme - Orange & Red
+ */
+export declare const orangeTheme: ThemeSet;
+
 export { Pagination }
 
+/**
+ * Purple theme - Purple & Pink
+ */
+export declare const purpleTheme: ThemeSet;
+
 export declare const Row: default_2.FC<RowProps>;
 
 declare type RowProps = {
@@ -702,8 +1034,34 @@ declare interface SearchBarProps {
     onChange?: (value: string) => void;
 }
 
+/**
+ * Semantic color palette
+ * Provides meaning through color (success, error, warning, etc.)
+ */
+export declare interface SemanticColors {
+    primary: ColorScale;
+    secondary?: ColorScale;
+    accent?: ColorScale;
+    success: ColorScale;
+    warning: ColorScale;
+    error: ColorScale;
+    info: ColorScale;
+}
+
 declare type ShadeKey = keyof ColorScale;
 
+export declare interface Shadows {
+    none: string;
+    sm: string;
+    base: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    inner: string;
+    [key: string]: string;
+}
+
 export declare const Sidebar: SidebarCompound;
 
 declare interface SidebarCompound extends default_2.FC<SidebarProps> {
@@ -797,7 +1155,42 @@ declare interface SortState {
     direction: "asc" | "desc";
 }
 
-declare interface Spacing {
+export declare interface Spacing {
+    0: string;
+    px: string;
+    0.5: string;
+    1: string;
+    1.5: string;
+    2: string;
+    2.5: string;
+    3: string;
+    3.5: string;
+    4: string;
+    5: string;
+    6: string;
+    7: string;
+    8: string;
+    9: string;
+    10: string;
+    11: string;
+    12: string;
+    14: string;
+    16: string;
+    20: string;
+    24: string;
+    28: string;
+    32: string;
+    36: string;
+    40: string;
+    44: string;
+    48: string;
+    52: string;
+    56: string;
+    60: string;
+    64: string;
+    72: string;
+    80: string;
+    96: string;
     [key: string]: string;
 }
 
@@ -934,42 +1327,123 @@ declare interface TabsProps {
 
 declare type TabVariant = 'default' | 'button' | 'shadow' | 'underline' | 'pills';
 
-declare interface Theme extends Omit<ThemeSet, 'colors' | 'shadows'> {
-    colors: ColorVariant;
-    shadows: {
-        [key: string]: string;
-    };
-}
-
-declare interface ThemeContextType {
+/**
+ * Text colors for different emphasis levels
+ */
+export declare interface TextColors {
+    primary: string;
+    secondary: string;
+    tertiary: string;
+    disabled: string;
+    inverse: string;
+}
+
+/**
+ * Complete theme configuration
+ */
+export declare interface Theme {
+    colors: Colors;
+    typography: TypographyType;
+    spacing: Spacing;
+    borderRadius: BorderRadius;
+    borderWidth: BorderWidth;
+    shadows: Shadows;
+    effects?: Effects;
+    breakpoints: Breakpoints;
+    transitions: Transitions;
+    zIndex: ZIndex;
+    [key: string]: any;
+}
+
+/**
+ * Theme configuration options
+ */
+export declare interface ThemeConfig {
+    defaultTheme?: ThemeName;
+    defaultMode?: ThemeMode;
+    themes: Record<ThemeName, ThemeSet>;
+    storageKey?: string;
+    enableSystem?: boolean;
+}
+
+/**
+ * Theme context type for React Context
+ */
+export declare interface ThemeContextType {
     theme: Theme;
-    mode: ModeType;
+    themeName: ThemeName;
+    mode: ThemeMode;
+    resolvedMode: 'light' | 'dark';
+    setTheme: (name: ThemeName) => void;
+    setMode: (mode: ThemeMode) => void;
     toggleMode: () => void;
-    setCustomTheme: (theme: Partial<ThemeSet>) => void;
-}
-
+    availableThemes: ThemeName[];
+}
+
+/**
+ * Theme mode
+ */
+export declare type ThemeMode = 'light' | 'dark' | 'system';
+
+/**
+ * Theme name identifier
+ */
+export declare type ThemeName = string;
+
+/**
+ * Theme Provider Component
+ *
+ * @example
+ * ```tsx
+ * import { ThemeProvider } from 'glintly-ui/themes';
+ *
+ * function App() {
+ *   return (
+ *     <ThemeProvider config={{
+ *       defaultTheme: 'emerald',
+ *       defaultMode: 'dark',
+ *       enableSystem: true
+ *     }}>
+ *       <YourApp />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
+ */
 export declare const ThemeProvider: default_2.FC<ThemeProviderProps>;
 
 declare interface ThemeProviderProps {
     children: ReactNode;
-    theme?: Partial<ThemeSet>;
-}
-
-declare interface ThemeSet {
-    colors: Colors;
-    typography: Typography_2;
-    spacing: Spacing;
-    borderRadius: BorderRadius;
-    breakpoints: Breakpoints;
-    shadows: {
-        light: {
-            [key: string]: string;
-        };
-        dark: {
-            [key: string]: string;
-        };
-    };
-}
+    config?: Partial<ThemeConfig>;
+}
+
+/**
+ * All available themes
+ */
+export declare const themes: Record<string, ThemeSet>;
+
+/**
+ * Theme with light and dark mode variants
+ */
+export declare interface ThemeSet {
+    light: Theme;
+    dark: Theme;
+}
+
+/**
+ * Convert theme to CSS variables
+ * Useful for integrating with CSS-in-JS or generating CSS files
+ *
+ * @example
+ * ```ts
+ * import { themeToCSSVariables, getTheme } from 'glintly-ui/themes';
+ *
+ * const theme = getTheme('default', 'light');
+ * const cssVars = themeToCSSVariables(theme, 'my-prefix');
+ * // Output: { '--my-prefix-primary-500': '#3b82f6', ... }
+ * ```
+ */
+export declare function themeToCSSVariables(theme: Theme, prefix?: string): Record<string, string>;
 
 export declare const toast: ((content: ReactNode, options?: ToastOptions) => string) & {
     success: (content: ReactNode, options?: ToastOptions) => string;
@@ -1033,21 +1507,26 @@ declare interface TooltipProps {
     style?: default_2.CSSProperties;
 }
 
-export declare const Typography: default_2.FC<TypographyProps>;
-
-declare interface Typography_2 {
-    fontFamily: string;
-    fontSize: {
+export declare interface Transitions {
+    duration: {
+        fast: string;
+        base: string;
+        slow: string;
+        slower: string;
         [key: string]: string;
     };
-    fontWeight: {
-        [key: string]: number;
-    };
-    lineHeight?: {
+    timing: {
+        linear: string;
+        ease: string;
+        easeIn: string;
+        easeOut: string;
+        easeInOut: string;
         [key: string]: string;
     };
 }
 
+export declare const Typography: default_2.FC<TypographyProps>;
+
 declare type TypographyAlign = 'left' | 'center' | 'right' | 'justify';
 
 declare interface TypographyProps extends default_2.HTMLAttributes<HTMLElement> {
@@ -1062,10 +1541,64 @@ declare interface TypographyProps extends default_2.HTMLAttributes<HTMLElement>
     style?: default_2.CSSProperties;
 }
 
+export declare interface TypographyType {
+    fontFamily: {
+        sans: string;
+        serif: string;
+        mono: string;
+    };
+    fontSize: FontSizes;
+    fontWeight: FontWeights;
+    lineHeight: LineHeights;
+    letterSpacing?: {
+        [key: string]: string;
+    };
+}
+
 declare type TypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'caption' | 'overline';
 
+/**
+ * Hook to use theme context
+ *
+ * @example
+ * ```tsx
+ * import { useTheme } from 'glintly-ui/themes';
+ *
+ * function MyComponent() {
+ *   const { theme, mode, setMode } = useTheme();
+ *
+ *   return (
+ *     <button
+ *       style={{
+ *         backgroundColor: theme.colors.semantic.primary[500],
+ *         color: theme.colors.text.inverse,
+ *         padding: theme.spacing[4],
+ *         borderRadius: theme.borderRadius.md,
+ *       }}
+ *       onClick={() => setMode(mode === 'light' ? 'dark' : 'light')}
+ *     >
+ *       Toggle Theme
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export declare const useTheme: () => ThemeContextType;
 
+export declare interface ZIndex {
+    hide: number;
+    base: number;
+    dropdown: number;
+    sticky: number;
+    fixed: number;
+    modalBackdrop: number;
+    modal: number;
+    popover: number;
+    tooltip: number;
+    toast: number;
+    [key: string]: number;
+}
+
 export { }