API Reference

Complete reference documentation for all UI Lab components, hooks, and utilities.

Components

Core Components

Button

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  loading?: boolean;
  icon?: string;
  iconPosition?: 'left' | 'right';
  onClick?: (event: MouseEvent) => void;
  type?: 'button' | 'submit' | 'reset';
  children: React.ReactNode;
}

Card

interface CardProps {
  variant?: 'default' | 'elevated' | 'outlined';
  padding?: 'none' | 'small' | 'medium' | 'large';
  clickable?: boolean;
  hoverable?: boolean;
  onClick?: (event: MouseEvent) => void;
  className?: string;
  children: React.ReactNode;
}

Input

interface InputProps {
  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
  variant?: 'default' | 'filled' | 'outlined';
  size?: 'small' | 'medium' | 'large';
  label?: string;
  placeholder?: string;
  helperText?: string;
  error?: string;
  disabled?: boolean;
  required?: boolean;
  value?: string;
  onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
}

Layout Components

Container

interface ContainerProps {
  size?: 'small' | 'medium' | 'large' | 'full';
  centered?: boolean;
  className?: string;
  children: React.ReactNode;
}

Grid

interface GridProps {
  columns?: number | 'auto';
  gap?: 'small' | 'medium' | 'large';
  responsive?: boolean;
  className?: string;
  children: React.ReactNode;
}

Stack

interface StackProps {
  direction?: 'horizontal' | 'vertical';
  spacing?: 'small' | 'medium' | 'large';
  align?: 'start' | 'center' | 'end' | 'stretch';
  justify?: 'start' | 'center' | 'end' | 'between' | 'around';
  wrap?: boolean;
  className?: string;
  children: React.ReactNode;
}

Hooks

useTheme

interface ThemeContext {
  theme: 'light' | 'dark';
  toggleTheme: () => void;
  setTheme: (theme: 'light' | 'dark') => void;
}

const useTheme = (): ThemeContext;

useDisclosure

interface DisclosureReturn {
  isOpen: boolean;
  open: () => void;
  close: () => void;
  toggle: () => void;
}

const useDisclosure = (initialState?: boolean): DisclosureReturn;

useLocalStorage

const useLocalStorage = <T>(
  key: string,
  defaultValue: T
): [T, (value: T) => void];

Utilities

Theme Utilities

createTheme

interface ThemeConfig {
  colors?: Record<string, any>;
  typography?: Record<string, any>;
  spacing?: Record<string, any>;
  borderRadius?: Record<string, any>;
}

const createTheme = (config: ThemeConfig): Theme;

mergeThemes

const mergeThemes = (baseTheme: Theme, customTheme: Partial<Theme>): Theme;

Styling Utilities

cn (className utility)

const cn = (...classes: (string | undefined | null | false)[]): string;

cva (class variance authority)

interface VariantProps {
  [key: string]: Record<string, string>;
}

const cva = (
  base: string,
  config: {
    variants?: VariantProps;
    compoundVariants?: Array<{
      [key: string]: any;
      className: string;
    }>;
    defaultVariants?: Record<string, any>;
  }
) => (props?: Record<string, any>) => string;

Type Definitions

Common Types

// Size variants used across components
type Size = 'small' | 'medium' | 'large';

// Color variants for semantic meaning
type ColorVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error';

// Theme mode
type ThemeMode = 'light' | 'dark';

// Responsive breakpoints
type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';

Component Props Base

interface BaseComponentProps {
  className?: string;
  children?: React.ReactNode;
  'data-testid'?: string;
}

interface InteractiveComponentProps extends BaseComponentProps {
  disabled?: boolean;
  onClick?: (event: MouseEvent) => void;
  onKeyDown?: (event: KeyboardEvent) => void;
}

Events

Custom Events

UI Lab components emit custom events for complex interactions:

// Theme change event
interface ThemeChangeEvent extends CustomEvent {
  detail: {
    theme: 'light' | 'dark';
    previous: 'light' | 'dark';
  };
}

// Component state change
interface StateChangeEvent extends CustomEvent {
  detail: {
    component: string;
    state: any;
    previous: any;
  };
}

Configuration

Global Configuration

interface UILabConfig {
  theme?: ThemeConfig;
  prefix?: string;
  components?: Record<string, any>;
  breakpoints?: Record<string, string>;
  animations?: {
    duration?: Record<string, string>;
    easing?: Record<string, string>;
  };
}

// Configure UI Lab globally
const configure = (config: UILabConfig): void;

This reference covers all public APIs. For implementation details and advanced usage, see the individual component documentation.