@raxrai/stylelab-ui 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -57,6 +57,10 @@ declare const Badge: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElem
 } & class_variance_authority_types.ClassProp) | undefined) => string> & {
     dot?: boolean;
     theme?: StyleLabTheme;
+    /** Override background (e.g. hex) when you need a specific color. */
+    bgOverride?: string;
+    /** Override text color (e.g. hex). */
+    textOverride?: string;
 } & react.RefAttributes<HTMLSpanElement>>;
 
 declare function BentoGrid({ children, className, style, }: {
@@ -108,6 +112,22 @@ type CalendarProps = {
 };
 declare function Calendar({ value: controlledValue, defaultValue, onSelect, min, max, className, theme: themeProp, }: CalendarProps): react.JSX.Element;
 
+declare const cardVariants: (props?: ({
+    padding?: "none" | "sm" | "md" | null | undefined;
+    isHoverable?: boolean | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type CardClassNames = {
+    root?: string;
+    header?: string;
+    body?: string;
+    footer?: string;
+};
+type CardProps = HTMLAttributes<HTMLDivElement> & VariantProps<typeof cardVariants> & {
+    header?: ReactNode;
+    footer?: ReactNode;
+    theme?: StyleLabTheme;
+    classNames?: CardClassNames;
+};
 declare const Card: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
     padding?: "none" | "sm" | "md" | null | undefined;
     isHoverable?: boolean | null | undefined;
@@ -115,6 +135,7 @@ declare const Card: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElemen
     header?: ReactNode;
     footer?: ReactNode;
     theme?: StyleLabTheme;
+    classNames?: CardClassNames;
 } & react.RefAttributes<HTMLDivElement>>;
 
 type DashboardNavItem = {
@@ -182,8 +203,16 @@ type DropdownItem = {
     label: ReactNode;
     disabled?: boolean;
 };
+type DropdownClassNames = {
+    trigger?: string;
+    popover?: string;
+    item?: string;
+};
 type DropdownProps = {
-    trigger: ReactNode;
+    /** Custom trigger node. If omitted, a default button is shown using placeholder or selected label. */
+    trigger?: ReactNode;
+    /** Placeholder when no value is selected (used with default trigger). */
+    placeholder?: string;
     items: DropdownItem[];
     value?: string;
     defaultValue?: string;
@@ -191,8 +220,10 @@ type DropdownProps = {
     className?: string;
     style?: React.CSSProperties;
     theme?: StyleLabTheme;
+    /** Slot classNames for trigger, popover, and item. */
+    classNames?: DropdownClassNames;
 };
-declare function Dropdown({ trigger, items, value: controlledValue, defaultValue, onValueChange, className, style, theme: themeProp, }: DropdownProps): react.JSX.Element;
+declare function Dropdown({ trigger: triggerProp, placeholder, items, value: controlledValue, defaultValue, onValueChange, className, style, theme: themeProp, classNames, }: DropdownProps): react.JSX.Element;
 
 type FlashcardProps = {
     question: string;
@@ -231,11 +262,23 @@ type ModalProps = VariantProps<typeof modalVariants> & {
 };
 declare function Modal({ open, onClose, title, size, className, style, children, theme: themeProp, }: ModalProps): react.JSX.Element | null;
 
-declare function Navbar({ children, className, style, }: {
-    children: React.ReactNode;
+type NavbarItem = {
+    href: string;
+    label: ReactNode;
+};
+type NavbarProps = {
+    /** Main content when using custom layout (no logo/items). */
+    children?: ReactNode;
+    /** Logo/brand node (left side). Used when `items` is provided. */
+    logo?: ReactNode;
+    /** Nav links. When provided, desktop shows horizontal links; mobile shows hamburger that toggles a menu. */
+    items?: NavbarItem[];
+    /** Optional slot for right side (e.g. theme switcher, user menu). Shown after nav items on desktop, in header row on mobile. */
+    right?: ReactNode;
     className?: string;
     style?: React.CSSProperties;
-}): react.JSX.Element;
+};
+declare function Navbar({ children, logo, items, right, className, style, }: NavbarProps): react.JSX.Element;
 
 type Tier = {
     name: string;
@@ -252,14 +295,18 @@ declare function PricingCard({ tier, onSelect, className, style, }: {
     style?: React.CSSProperties;
 }): react.JSX.Element;
 
-type Props = {
+type ProgressBarProps = {
     value: number;
     max?: number;
     segmented?: boolean;
     className?: string;
     style?: React.CSSProperties;
+    /** Override track background (e.g. hex). */
+    trackColor?: string;
+    /** Override fill/active bar color (e.g. hex). */
+    activeColor?: string;
 };
-declare function ProgressBar({ value, max, segmented, className, style, }: Props): react.JSX.Element;
+declare function ProgressBar({ value, max, segmented, className, style, trackColor, activeColor, }: ProgressBarProps): react.JSX.Element;
 
 declare function SectionHeader({ title, subtitle, className, style, }: {
     title: string;
@@ -368,12 +415,39 @@ type ThemeContextValue = {
     theme: StyleLabTheme;
     setTheme: (theme: StyleLabTheme) => void;
 };
-declare function ThemeProvider({ children, defaultTheme, }: {
+declare function ThemeProvider({ children, defaultTheme, storageKey, }: {
     children: ReactNode;
     defaultTheme?: StyleLabTheme;
+    /** localStorage key for persisting theme. Defaults to "stylelab-theme". */
+    storageKey?: string;
 }): react.JSX.Element;
 declare function useTheme(): ThemeContextValue;
 
+/**
+ * Background and UI color recommendations per theme.
+ * Use these as guidelines when laying out pages so components look correct.
+ */
+
+type ThemeRecommendation = {
+    /** Recommended page or main wrapper background (matches gallery). */
+    background: string;
+    /** Recommended surface for cards, modals, panels. */
+    surface: string;
+    /** Recommended body/text color (matches gallery). */
+    text: string;
+    /** Primary accent color for CTAs and highlights. */
+    accent: string;
+    /** Recommended navbar styling (from theme-resolver navbar default). */
+    navbar: string;
+    /** Optional short guideline. */
+    notes?: string;
+};
+/** Background + text classes used in the gallery for each theme. Use these for page layout. */
+declare const THEME_BACKGROUNDS: Record<StyleLabTheme, string>;
+/** Navbar default class per theme (from theme-resolver). */
+declare const THEME_NAVBAR: Record<StyleLabTheme, string>;
+declare const THEME_RECOMMENDATIONS: Record<StyleLabTheme, ThemeRecommendation>;
+
 /**
  * Merges class names with Tailwind-aware deduplication.
  * Use for all component className composition.
@@ -415,4 +489,4 @@ declare function useKeyboardNavigation(options: {
  */
 declare function getNextListIndex(current: number, direction: "up" | "down", length: number): number;
 
-export { Accordion, Alert, Avatar, AvatarGroup, Badge, BentoGrid, Breadcrumbs, Button, Calendar, Card, CommandPalette, type ComponentName, DashboardShell, DataTable, DocumentAccordion, Dropdown, Flashcard, GraphicCard, Input, Modal, Navbar, PricingCard, ProgressBar, SectionHeader, Sidebar, Skeleton, Slider, StatsCard, type StyleLabTheme, THEMES, Tabs, Terminal, ThemeProvider, Timeline, Toast, Toggle, Tooltip, cn, getNextListIndex, getThemeClass, useClickOutside, useFocusTrap, useKeyboardNavigation, useTheme };
+export { Accordion, Alert, Avatar, AvatarGroup, Badge, BentoGrid, Breadcrumbs, Button, Calendar, Card, type CardClassNames, type CardProps, CommandPalette, type ComponentName, DashboardShell, DataTable, DocumentAccordion, Dropdown, type DropdownClassNames, type DropdownItem, type DropdownProps, Flashcard, GraphicCard, Input, Modal, Navbar, type NavbarItem, type NavbarProps, PricingCard, ProgressBar, SectionHeader, Sidebar, Skeleton, Slider, StatsCard, type StyleLabTheme, THEMES, THEME_BACKGROUNDS, THEME_NAVBAR, THEME_RECOMMENDATIONS, Tabs, Terminal, ThemeProvider, type ThemeRecommendation, Timeline, Toast, Toggle, Tooltip, cn, getNextListIndex, getThemeClass, useClickOutside, useFocusTrap, useKeyboardNavigation, useTheme };

package/dist/index.d.ts

@@ -57,6 +57,10 @@ declare const Badge: react.ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElem
 } & class_variance_authority_types.ClassProp) | undefined) => string> & {
     dot?: boolean;
     theme?: StyleLabTheme;
+    /** Override background (e.g. hex) when you need a specific color. */
+    bgOverride?: string;
+    /** Override text color (e.g. hex). */
+    textOverride?: string;
 } & react.RefAttributes<HTMLSpanElement>>;
 
 declare function BentoGrid({ children, className, style, }: {
@@ -108,6 +112,22 @@ type CalendarProps = {
 };
 declare function Calendar({ value: controlledValue, defaultValue, onSelect, min, max, className, theme: themeProp, }: CalendarProps): react.JSX.Element;
 
+declare const cardVariants: (props?: ({
+    padding?: "none" | "sm" | "md" | null | undefined;
+    isHoverable?: boolean | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type CardClassNames = {
+    root?: string;
+    header?: string;
+    body?: string;
+    footer?: string;
+};
+type CardProps = HTMLAttributes<HTMLDivElement> & VariantProps<typeof cardVariants> & {
+    header?: ReactNode;
+    footer?: ReactNode;
+    theme?: StyleLabTheme;
+    classNames?: CardClassNames;
+};
 declare const Card: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
     padding?: "none" | "sm" | "md" | null | undefined;
     isHoverable?: boolean | null | undefined;
@@ -115,6 +135,7 @@ declare const Card: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElemen
     header?: ReactNode;
     footer?: ReactNode;
     theme?: StyleLabTheme;
+    classNames?: CardClassNames;
 } & react.RefAttributes<HTMLDivElement>>;
 
 type DashboardNavItem = {
@@ -182,8 +203,16 @@ type DropdownItem = {
     label: ReactNode;
     disabled?: boolean;
 };
+type DropdownClassNames = {
+    trigger?: string;
+    popover?: string;
+    item?: string;
+};
 type DropdownProps = {
-    trigger: ReactNode;
+    /** Custom trigger node. If omitted, a default button is shown using placeholder or selected label. */
+    trigger?: ReactNode;
+    /** Placeholder when no value is selected (used with default trigger). */
+    placeholder?: string;
     items: DropdownItem[];
     value?: string;
     defaultValue?: string;
@@ -191,8 +220,10 @@ type DropdownProps = {
     className?: string;
     style?: React.CSSProperties;
     theme?: StyleLabTheme;
+    /** Slot classNames for trigger, popover, and item. */
+    classNames?: DropdownClassNames;
 };
-declare function Dropdown({ trigger, items, value: controlledValue, defaultValue, onValueChange, className, style, theme: themeProp, }: DropdownProps): react.JSX.Element;
+declare function Dropdown({ trigger: triggerProp, placeholder, items, value: controlledValue, defaultValue, onValueChange, className, style, theme: themeProp, classNames, }: DropdownProps): react.JSX.Element;
 
 type FlashcardProps = {
     question: string;
@@ -231,11 +262,23 @@ type ModalProps = VariantProps<typeof modalVariants> & {
 };
 declare function Modal({ open, onClose, title, size, className, style, children, theme: themeProp, }: ModalProps): react.JSX.Element | null;
 
-declare function Navbar({ children, className, style, }: {
-    children: React.ReactNode;
+type NavbarItem = {
+    href: string;
+    label: ReactNode;
+};
+type NavbarProps = {
+    /** Main content when using custom layout (no logo/items). */
+    children?: ReactNode;
+    /** Logo/brand node (left side). Used when `items` is provided. */
+    logo?: ReactNode;
+    /** Nav links. When provided, desktop shows horizontal links; mobile shows hamburger that toggles a menu. */
+    items?: NavbarItem[];
+    /** Optional slot for right side (e.g. theme switcher, user menu). Shown after nav items on desktop, in header row on mobile. */
+    right?: ReactNode;
     className?: string;
     style?: React.CSSProperties;
-}): react.JSX.Element;
+};
+declare function Navbar({ children, logo, items, right, className, style, }: NavbarProps): react.JSX.Element;
 
 type Tier = {
     name: string;
@@ -252,14 +295,18 @@ declare function PricingCard({ tier, onSelect, className, style, }: {
     style?: React.CSSProperties;
 }): react.JSX.Element;
 
-type Props = {
+type ProgressBarProps = {
     value: number;
     max?: number;
     segmented?: boolean;
     className?: string;
     style?: React.CSSProperties;
+    /** Override track background (e.g. hex). */
+    trackColor?: string;
+    /** Override fill/active bar color (e.g. hex). */
+    activeColor?: string;
 };
-declare function ProgressBar({ value, max, segmented, className, style, }: Props): react.JSX.Element;
+declare function ProgressBar({ value, max, segmented, className, style, trackColor, activeColor, }: ProgressBarProps): react.JSX.Element;
 
 declare function SectionHeader({ title, subtitle, className, style, }: {
     title: string;
@@ -368,12 +415,39 @@ type ThemeContextValue = {
     theme: StyleLabTheme;
     setTheme: (theme: StyleLabTheme) => void;
 };
-declare function ThemeProvider({ children, defaultTheme, }: {
+declare function ThemeProvider({ children, defaultTheme, storageKey, }: {
     children: ReactNode;
     defaultTheme?: StyleLabTheme;
+    /** localStorage key for persisting theme. Defaults to "stylelab-theme". */
+    storageKey?: string;
 }): react.JSX.Element;
 declare function useTheme(): ThemeContextValue;
 
+/**
+ * Background and UI color recommendations per theme.
+ * Use these as guidelines when laying out pages so components look correct.
+ */
+
+type ThemeRecommendation = {
+    /** Recommended page or main wrapper background (matches gallery). */
+    background: string;
+    /** Recommended surface for cards, modals, panels. */
+    surface: string;
+    /** Recommended body/text color (matches gallery). */
+    text: string;
+    /** Primary accent color for CTAs and highlights. */
+    accent: string;
+    /** Recommended navbar styling (from theme-resolver navbar default). */
+    navbar: string;
+    /** Optional short guideline. */
+    notes?: string;
+};
+/** Background + text classes used in the gallery for each theme. Use these for page layout. */
+declare const THEME_BACKGROUNDS: Record<StyleLabTheme, string>;
+/** Navbar default class per theme (from theme-resolver). */
+declare const THEME_NAVBAR: Record<StyleLabTheme, string>;
+declare const THEME_RECOMMENDATIONS: Record<StyleLabTheme, ThemeRecommendation>;
+
 /**
  * Merges class names with Tailwind-aware deduplication.
  * Use for all component className composition.
@@ -415,4 +489,4 @@ declare function useKeyboardNavigation(options: {
  */
 declare function getNextListIndex(current: number, direction: "up" | "down", length: number): number;
 
-export { Accordion, Alert, Avatar, AvatarGroup, Badge, BentoGrid, Breadcrumbs, Button, Calendar, Card, CommandPalette, type ComponentName, DashboardShell, DataTable, DocumentAccordion, Dropdown, Flashcard, GraphicCard, Input, Modal, Navbar, PricingCard, ProgressBar, SectionHeader, Sidebar, Skeleton, Slider, StatsCard, type StyleLabTheme, THEMES, Tabs, Terminal, ThemeProvider, Timeline, Toast, Toggle, Tooltip, cn, getNextListIndex, getThemeClass, useClickOutside, useFocusTrap, useKeyboardNavigation, useTheme };
+export { Accordion, Alert, Avatar, AvatarGroup, Badge, BentoGrid, Breadcrumbs, Button, Calendar, Card, type CardClassNames, type CardProps, CommandPalette, type ComponentName, DashboardShell, DataTable, DocumentAccordion, Dropdown, type DropdownClassNames, type DropdownItem, type DropdownProps, Flashcard, GraphicCard, Input, Modal, Navbar, type NavbarItem, type NavbarProps, PricingCard, ProgressBar, SectionHeader, Sidebar, Skeleton, Slider, StatsCard, type StyleLabTheme, THEMES, THEME_BACKGROUNDS, THEME_NAVBAR, THEME_RECOMMENDATIONS, Tabs, Terminal, ThemeProvider, type ThemeRecommendation, Timeline, Toast, Toggle, Tooltip, cn, getNextListIndex, getThemeClass, useClickOutside, useFocusTrap, useKeyboardNavigation, useTheme };