@jmruthers/pace-core 0.2.4

package/docs/api-reference/components.md

@@ -0,0 +1,1623 @@
+# Components API Reference
+
+> **📚 Complete API Reference** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+
+This section provides detailed API documentation for all UI components in `@jmruthers/pace-core`.
+
+## Button
+
+A versatile button component with multiple variants and states.
+
+### Props
+
+```typescript
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
+  size?: 'default' | 'sm' | 'lg' | 'icon';
+  asChild?: boolean;
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Button } from '@jmruthers/pace-core';
+
+// Default button
+<Button onClick={handleClick}>
+  Click me
+</Button>
+
+// Destructive button
+<Button variant="destructive" size="lg">
+  Delete
+</Button>
+
+// Button as child (composition)
+<Button asChild>
+  <Link href="/dashboard">Go to Dashboard</Link>
+</Button>
+
+// Icon button
+<Button size="icon" aria-label="Settings">
+  <Settings className="h-4 w-4" />
+</Button>
+```
+
+### Variants
+
+- **default**: Primary button with solid background
+- **destructive**: Red button for dangerous actions
+- **outline**: Bordered button with transparent background
+- **secondary**: Secondary button with muted styling
+- **ghost**: Minimal styling for subtle actions
+- **link**: Text button with underline on hover
+
+### Sizes
+
+- **default**: Standard button size (h-9 px-4 py-2)
+- **sm**: Small button (h-8 px-3 text-xs)
+- **lg**: Large button (h-10 px-8)
+- **icon**: Square icon button (h-8 w-8)
+
+## DataTable
+
+A comprehensive, enterprise-grade data table with advanced features and performance optimizations.
+
+### Props
+
+```typescript
+interface DataTableFeatureConfig {
+  // Search and filtering
+  search?: boolean;
+  filtering?: boolean;
+  
+  // Pagination and sorting
+  pagination?: boolean;
+  sorting?: boolean;
+  
+  // Row operations
+  selection?: boolean;
+  creation?: boolean;
+  editing?: boolean;
+  deletion?: boolean;
+  deleteSelected?: boolean;
+  
+  // Data operations
+  export?: boolean;
+  import?: boolean;
+  
+  // Advanced features
+  grouping?: boolean;
+  columnVisibility?: boolean;
+  columnReordering?: boolean;
+  autoColumnSizing?: boolean;
+}
+
+interface DataTableProps<TData extends DataRecord> {
+  // Core data
+  data: TData[];
+  columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
+  
+  // Display
+  title?: string;
+  description?: string;
+  variant?: 'default' | 'compact' | 'spacious';
+  className?: string;
+  
+  // Column ordering
+  columnOrder?: string[];
+  
+  // Feature configuration (required)
+  features: DataTableFeatureConfig;
+  
+  // Event handlers
+  onEditRow?: (row: TData, data: Partial<TData>) => void;
+  onDeleteRow?: (row: TData) => void;
+  onCreateRow?: (data: Partial<TData>) => void;
+  onImport?: (data: TData[]) => void | Promise<void>;
+  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+  
+  // Performance
+  performance?: PerformanceConfig;
+  serverSide?: ServerSideConfig<TData>;
+  isLoading?: boolean;
+  
+  // Utilities
+  getRowId?: GetRowId<TData>;
+  emptyState?: EmptyStateConfig;
+  
+  // Hierarchical configuration
+  hierarchical?: HierarchicalConfig;
+}
+```
+
+### HierarchicalConfig
+
+```typescript
+interface HierarchicalConfig {
+  /** Enable/disable hierarchical functionality */
+  enabled: boolean;
+  /** Initial expansion state - false = all collapsed, true = all expanded, string[] = specific IDs */
+  defaultExpanded?: boolean | string[];
+  /** Callback when expansion state changes */
+  onExpandedChange?: (expandedIds: string[]) => void;
+  /** Custom expand/collapse button component */
+  expandButton?: React.ComponentType<ExpandButtonProps>;
+  /** Indentation for child rows in pixels */
+  indentSize?: number;
+  /** CSS classes for parent rows */
+  parentRowClassName?: string;
+  /** CSS classes for child rows */
+  childRowClassName?: string;
+}
+```
+
+### DataTableColumn (Hierarchical Properties)
+
+```typescript
+interface DataTableColumn<TData> {
+  // ... standard column properties
+  
+  // Hierarchical-specific properties
+  /** Custom renderer for parent rows */
+  renderForParent?: (row: TData) => React.ReactNode;
+  /** Custom renderer for child rows */
+  renderForChild?: (row: TData) => React.ReactNode;
+  /** Hide this column for parent rows */
+  hideForParent?: boolean;
+  /** Hide this column for child rows */
+  hideForChild?: boolean;
+}
+```
+
+### DataTableAction
+
+```typescript
+interface DataTableAction<TData extends DataRecord> {
+  /** Display label for the action */
+  label: string;
+  /** Icon component */
+  icon?: React.ComponentType<{ className?: string }>;
+  /** Action handler */
+  onClick: (row: TData) => void;
+  /** Visual variant */
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost';
+  /** Whether action is disabled */
+  disabled?: (row: TData) => boolean;
+  /** Test ID for testing */
+  testId?: string;
+  /** Whether this action should only show for parent rows (hierarchical mode) */
+  showForParent?: boolean;
+  /** Whether this action should only show for child rows (hierarchical mode) */
+  showForChild?: boolean;
+  /** Icon component for parent rows (overrides icon when showForParent is true) */
+  parentIcon?: React.ComponentType<{ className?: string }>;
+  /** Icon component for child rows (overrides icon when showForChild is true) */
+  childIcon?: React.ComponentType<{ className?: string }>;
+  /** Label for parent rows (overrides label when showForParent is true) */
+  parentLabel?: string;
+  /** Label for child rows (overrides label when showForChild is true) */
+  childLabel?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { DataTable, type DataTableColumn } from '@jmruthers/pace-core';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: 'active' | 'inactive';
+}
+
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortable: true,
+    searchable: true,
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    sortable: true,
+    searchable: true,
+  },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    sortable: true,
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    sortable: true,
+    cell: ({ row }) => (
+      <span className={`px-2 py-1 rounded text-xs ${
+        row.original.status === 'active'
+          ? 'bg-main-100 text-main-800'
+          : 'bg-acc-100 text-acc-800'
+      }`}>
+        {row.original.status}
+      </span>
+    ),
+  },
+];
+
+<DataTable
+  data={users}
+  columns={columns}
+  title="Users"
+  description="Manage your users"
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true,
+    creation: true,
+    editing: true,
+    deletion: true,
+    autoColumnSizing: true,  // Enable automatic column width adjustment
+  }}
+  columnOrder={['name', 'email', 'role', 'status']} // Control column order
+  onEditRow={handleEdit}
+  onDeleteRow={handleDelete}
+  onCreateRow={handleCreate}
+/>
+```
+
+### Features
+
+- **🚀 Performance**: Virtual scrolling, smart pagination, memory optimization
+- **📊 Data Management**: Sorting, filtering, search, export/import
+- **🌳 Hierarchical Rows**: Parent/child relationships with expand/collapse all
+- **✏️ Editing**: Inline row editing, creation, and deletion
+- **🎯 Actions**: Custom row actions and toolbar buttons
+- **📈 Grouping**: Data grouping with aggregation functions
+- **📏 Auto Sizing**: Automatic column width adjustment based on content
+- **🎨 Customization**: Column visibility, responsive design
+- **♿ Accessibility**: WCAG 2.1 AA compliant with keyboard navigation
+- **🔧 TypeScript**: Full TypeScript support with strict typing
+
+## Form
+
+Form components with React Hook Form integration and Zod validation.
+
+### Props
+
+```typescript
+interface FormProps<TFieldValues extends FieldValues = FieldValues> {
+  schema?: z.ZodType<TFieldValues>;
+  defaultValues?: DefaultValues<TFieldValues>;
+  onSubmit: SubmitHandler<TFieldValues>;
+  onError?: SubmitErrorHandler<TFieldValues>;
+  mode?: "onSubmit" | "onChange" | "onBlur" | "onTouched" | "all";
+  children: React.ReactNode | ((methods: UseFormReturn<TFieldValues>) => React.ReactNode);
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Form, FormField, Button } from '@jmruthers/pace-core';
+import { z } from 'zod';
+
+const userSchema = z.object({
+  name: z.string().min(2, "Name must be at least 2 characters"),
+  email: z.string().email("Invalid email address"),
+  age: z.number().min(18, "Must be at least 18 years old")
+});
+
+<Form
+  schema={userSchema}
+  defaultValues={{ name: "", email: "", age: 0 }}
+  onSubmit={(data) => console.log(data)}
+  onError={(errors) => console.error(errors)}
+>
+  <FormField name="name" label="Name" />
+  <FormField name="email" label="Email" type="email" />
+  <FormField name="age" label="Age" type="number" />
+  <Button type="submit">Submit</Button>
+</Form>
+```
+
+### Form Components
+
+- **FormField**: Individual form fields with validation
+- **FormErrorSummary**: Error display for forms
+- **FormLiveRegion**: Live region for accessibility
+- **FormFieldset**: Grouped form fields
+
+## Dialog
+
+A comprehensive, accessible dialog component system with enhanced features for modern web applications. Built on Radix UI primitives with semantic HTML structure and smart height management.
+
+### Props
+
+```typescript
+interface DialogProps {
+  children: React.ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+interface DialogContentProps {
+  children: React.ReactNode;
+  className?: string;
+  /** Dialog size variant */
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'auto';
+  /** Whether to show the close button */
+  showCloseButton?: boolean;
+  /** Custom className for the overlay */
+  overlayClassName?: string;
+  /** Whether to prevent closing on escape key */
+  preventCloseOnEscape?: boolean;
+  /** Whether to prevent closing on outside click */
+  preventCloseOnOutsideClick?: boolean;
+  /** Maximum height as percentage of viewport height (0-100) */
+  maxHeightPercent?: number;
+  /** Maximum width as percentage of viewport width (0-100) */
+  maxWidthPercent?: number;
+  /** Enable smart scrolling with sticky header/footer */
+  enableScrolling?: boolean;
+  /** Custom max height in CSS units (overrides maxHeightPercent) */
+  maxHeight?: string;
+  /** Custom max width in CSS units (overrides maxWidthPercent and size) */
+  maxWidth?: string;
+  /** Minimum height in CSS units */
+  minHeight?: string;
+  /** Minimum width in CSS units */
+  minWidth?: string;
+}
+
+interface DialogHeaderProps {
+  children: React.ReactNode;
+  className?: string;
+  /** Whether this header should be sticky when scrolling is enabled */
+  sticky?: boolean;
+}
+
+interface DialogBodyProps {
+  children: React.ReactNode;
+  className?: string;
+  /** Custom max height for the scrollable area */
+  maxHeight?: string;
+  /** HTML content to render (will be sanitized for security) */
+  htmlContent?: string;
+  /** Whether to allow HTML content rendering (default: true) */
+  allowHtml?: boolean;
+  /** Whether to use strict HTML sanitization (default: true) */
+  strictSanitization?: boolean;
+  /** Whether to log HTML sanitization warnings to console (default: false) */
+  logWarnings?: boolean;
+}
+
+interface DialogFooterProps {
+  children: React.ReactNode;
+  className?: string;
+  /** Whether this footer should be sticky when scrolling is enabled */
+  sticky?: boolean;
+}
+
+interface DialogTriggerProps {
+  children: React.ReactNode;
+  asChild?: boolean;
+}
+
+interface DialogTitleProps {
+  children: React.ReactNode;
+  className?: string;
+  /** HTML content to render as title (will be sanitized for security) */
+  htmlContent?: string;
+  /** Whether to allow HTML content rendering (default: true) */
+  allowHtml?: boolean;
+}
+
+interface DialogDescriptionProps {
+  children: React.ReactNode;
+  className?: string;
+  /** HTML content to render as description (will be sanitized for security) */
+  htmlContent?: string;
+  /** Whether to allow HTML content rendering (default: true) */
+  allowHtml?: boolean;
+}
+```
+
+### Usage
+
+#### Basic Dialog
+
+```tsx
+import { 
+  Dialog, 
+  DialogTrigger, 
+  DialogContent, 
+  DialogHeader, 
+  DialogTitle, 
+  DialogDescription,
+  DialogBody,
+  DialogFooter,
+  Button 
+} from '@jmruthers/pace-core';
+
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Open Dialog</Button>
+  </DialogTrigger>
+  <DialogContent size="lg">
+    <DialogHeader>
+      <DialogTitle>Edit Profile</DialogTitle>
+      <DialogDescription>
+        Make changes to your profile here. Click save when you're done.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogBody>
+      <section className="space-y-4">
+        <p>Your content goes here...</p>
+      </section>
+    </DialogBody>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Save changes</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+#### Scrollable Dialog with Sticky Elements
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Scrollable Dialog</Button>
+  </DialogTrigger>
+  <DialogContent 
+    size="lg" 
+    enableScrolling={true}
+    maxHeightPercent={80}
+  >
+    <DialogHeader sticky={true}>
+      <DialogTitle>Large Content Dialog</DialogTitle>
+      <DialogDescription>
+        This dialog has lots of content and will scroll if needed.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogBody>
+      <section className="space-y-4">
+        {Array.from({ length: 50 }, (_, i) => (
+          <article key={i}>
+            <h4>Content Item {i + 1}</h4>
+            <p>This is semantic content within the dialog body.</p>
+          </article>
+        ))}
+      </section>
+    </DialogBody>
+    <DialogFooter sticky={true}>
+      <Button>Save</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+#### Auto-Sizing Dialog
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Auto Size Dialog</Button>
+  </DialogTrigger>
+  <DialogContent size="auto">
+    <DialogHeader>
+      <DialogTitle>Auto-Sized Dialog</DialogTitle>
+      <DialogDescription>
+        This dialog automatically adjusts its width to fit the content.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogBody>
+      <section>
+        <p>Content that determines the dialog width...</p>
+      </section>
+    </DialogBody>
+  </DialogContent>
+</Dialog>
+```
+
+#### HTML Content Dialog
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Import Instructions</Button>
+  </DialogTrigger>
+  <DialogContent size="lg">
+    <DialogHeader>
+      <DialogTitle htmlContent="Import Dishes or Recipes" />
+      <DialogDescription htmlContent="Follow the <strong>instructions below</strong> to upload your CSV file." />
+    </DialogHeader>
+    <DialogBody 
+      htmlContent="<h2>Required Columns</h2><ul><li><code>dish_code</code></li><li><code>dish_name</code></li><li><code>mealtype_name</code></li></ul><p><strong>Note:</strong> All HTML content is automatically sanitized for security.</p>"
+      allowHtml={true}
+      strictSanitization={true}
+    />
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Upload File</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Features
+
+#### Core Features
+- **Semantic HTML Structure**: Uses native `<dialog>` element with proper header, main, footer elements
+- **Accessibility First**: WCAG 2.1 AA compliant with full screen reader support
+- **Focus Management**: Automatic focus trapping and restoration
+- **Keyboard Navigation**: Escape to close, Tab for focus management
+- **Responsive Design**: Adapts to all screen sizes with smart constraints
+
+#### Advanced Features
+- **Smart Height Management**: Automatic viewport-based height constraints
+- **Scrollable Content**: Long content scrolls while keeping headers/footers visible
+- **Sticky Headers/Footers**: Important UI elements remain accessible during scrolling
+- **HTML Content Rendering**: Safe HTML content with automatic sanitization
+- **Multiple Size Variants**: sm, md, lg, xl, full, auto sizing options
+- **Custom Dimensions**: Fine-grained control over width and height
+- **Configurable Close Behavior**: Control escape key and outside click behavior
+- **Smooth Animations**: Polished transitions and micro-interactions
+
+### Size Variants
+
+| Size | Max Width | Use Case |
+|------|-----------|----------|
+| `sm` | 384px | Simple confirmations, alerts |
+| `md` | 448px | Standard forms, basic content |
+| `lg` | 512px | Complex forms, detailed content |
+| `xl` | 576px | Large forms, data tables |
+| `full` | 100% | Full screen experiences |
+| `auto` | Content-based | Dynamic content sizing |
+
+## Select
+
+A dropdown select component with search functionality and keyboard navigation.
+
+### Props
+
+```typescript
+interface SelectProps {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  children: React.ReactNode;
+}
+
+interface SelectTriggerProps extends Omit<ButtonProps, 'onClick' | 'onKeyDown'> {
+  children: React.ReactNode;
+}
+
+interface SelectContentProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+interface SelectItemProps {
+  value: string;
+  children: React.ReactNode;
+  disabled?: boolean;
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { 
+  Select, 
+  SelectTrigger, 
+  SelectContent, 
+  SelectItem, 
+  SelectValue 
+} from '@jmruthers/pace-core';
+
+<Select value={selectedValue} onValueChange={setSelectedValue}>
+  <SelectTrigger>
+    <SelectValue placeholder="Select an option" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="option1">Option 1</SelectItem>
+    <SelectItem value="option2">Option 2</SelectItem>
+    <SelectItem value="option3">Option 3</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+### Features
+
+- **Search**: Built-in search functionality with fuzzy matching
+- **Keyboard Navigation**: Full keyboard support with arrow keys
+- **Accessibility**: ARIA attributes and screen reader support
+- **Custom Styling**: Consistent with @jmruthers/pace-core design system
+- **Composition**: Flexible component composition
+
+## Alert
+
+A flexible and accessible alert component for displaying important messages.
+
+### Props
+
+```typescript
+interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: 'default' | 'destructive' | 'inline';
+  className?: string;
+}
+
+interface AlertTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  className?: string;
+}
+
+interface AlertDescriptionProps extends React.HTMLAttributes<HTMLDivElement> {
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
+
+// Basic alert
+<Alert>
+  <AlertTitle>Success</AlertTitle>
+  <AlertDescription>Your changes have been saved.</AlertDescription>
+</Alert>
+
+// Destructive alert
+<Alert variant="destructive">
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>Something went wrong.</AlertDescription>
+</Alert>
+
+// Inline alert (renders as fragment)
+<Alert variant="inline">
+  <AlertTitle>Note:</AlertTitle>
+  <AlertDescription>This is an inline message.</AlertDescription>
+</Alert>
+```
+
+### Variants
+
+- **default**: Standard alert with background and border
+- **destructive**: Red alert for errors and warnings
+- **inline**: Lightweight text formatting without background
+
+## Card
+
+A flexible card component suite for displaying content with consistent styling and semantic HTML structure.
+
+### Props
+
+```typescript
+interface CardProps extends React.HTMLAttributes<HTMLElement> {
+  className?: string;
+}
+
+interface CardHeaderProps extends React.HTMLAttributes<HTMLElement> {
+  className?: string;
+}
+
+interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  className?: string;
+}
+
+interface CardDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  className?: string;
+}
+
+interface CardContentProps extends React.HTMLAttributes<HTMLElement> {
+  className?: string;
+}
+
+interface CardFooterProps extends React.HTMLAttributes<HTMLElement> {
+  className?: string;
+}
+
+interface CardActionsProps extends React.HTMLAttributes<HTMLElement> {
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { 
+  Card, 
+  CardHeader, 
+  CardTitle, 
+  CardDescription, 
+  CardContent, 
+  CardFooter, 
+  CardActions 
+} from '@jmruthers/pace-core';
+
+<Card>
+  <CardHeader>
+    <CardTitle>Article Title</CardTitle>
+    <CardDescription>Brief description of the article content</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Main content goes here with proper semantic structure.</p>
+    <p>Additional paragraphs and content.</p>
+  </CardContent>
+  <CardFooter>
+    <CardActions>
+      <Button>Primary Action</Button>
+      <Button variant="outline">Secondary Action</Button>
+    </CardActions>
+  </CardFooter>
+</Card>
+```
+
+### Semantic Structure
+
+- **Card**: `<article>` element for self-contained content
+- **CardHeader**: `<header>` element for card heading area
+- **CardContent**: `<div>` element for primary card content
+- **CardFooter**: `<footer>` element for card footer area
+- **CardActions**: `<nav>` element for action buttons
+
+## LoadingSpinner
+
+A simple, accessible loading spinner component for indicating loading states.
+
+### Props
+
+```typescript
+interface LoadingSpinnerProps {
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { LoadingSpinner } from '@jmruthers/pace-core';
+
+// Basic loading spinner
+<LoadingSpinner />
+
+// Different sizes
+<LoadingSpinner size="sm" />
+<LoadingSpinner size="md" />
+<LoadingSpinner size="lg" />
+
+// With custom styling
+<LoadingSpinner 
+  size="lg" 
+  className="text-main-500" 
+/>
+
+// In a button
+<Button disabled>
+  <LoadingSpinner size="sm" className="mr-2" />
+  Loading...
+</Button>
+```
+
+### Features
+
+- **Accessibility**: WCAG 2.1 AA compliant with proper ARIA attributes
+- **Reduced Motion**: Supports users with vestibular disorders
+- **Screen Reader**: Announces "Loading..." to screen readers
+- **Performance**: CSS-only animations for optimal performance
+
+## Toast
+
+A comprehensive toast notification system with accessible, customizable notifications.
+
+### Props
+
+```typescript
+interface ToastProps extends React.ComponentPropsWithoutRef<typeof ToastPrimitives.Root> {
+  className?: string;
+}
+
+interface ToastActionElement extends React.ReactElement<typeof ToastAction> {}
+
+// useToast hook
+interface ToastOptions {
+  title?: string;
+  description?: string;
+  variant?: 'default' | 'destructive' | 'success' | 'warning' | 'info';
+  action?: ToastActionElement;
+  duration?: number;
+}
+```
+
+### Usage
+
+```tsx
+import { useToast, Toast, ToastTitle, ToastDescription, ToastAction } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { toast } = useToast();
+
+  const handleSuccess = () => {
+    toast({
+      title: "Success!",
+      description: "Your changes have been saved.",
+      variant: "success"
+    });
+  };
+
+  const handleError = () => {
+    toast({
+      title: "Error",
+      description: "Something went wrong.",
+      variant: "destructive",
+      action: <ToastAction altText="Retry">Retry</ToastAction>
+    });
+  };
+
+  return (
+    <div>
+      <Button onClick={handleSuccess}>Save Changes</Button>
+      <Button onClick={handleError}>Trigger Error</Button>
+    </div>
+  );
+}
+
+// Custom toast component
+<Toast>
+  <ToastTitle>Custom Toast</ToastTitle>
+  <ToastDescription>This is a custom toast message.</ToastDescription>
+  <ToastAction altText="Close">Close</ToastAction>
+</Toast>
+```
+
+### Features
+
+- **Multiple Variants**: Success, error, warning, info, and default
+- **Action Buttons**: Add custom actions to toasts
+- **Auto-dismiss**: Configurable duration with auto-dismiss
+- **Swipe Gestures**: Swipe to dismiss on mobile
+- **Keyboard Navigation**: Full keyboard support
+- **Accessibility**: WCAG 2.1 AA compliant
+
+## Tooltip
+
+A comprehensive tooltip component system with accessible, customizable tooltips.
+
+### Props
+
+```typescript
+interface TooltipProps {
+  children: React.ReactNode;
+  content: React.ReactNode;
+  delayDuration?: number;
+}
+
+interface TooltipContentProps {
+  children: React.ReactNode;
+  className?: string;
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+}
+
+interface TooltipTriggerProps {
+  children: React.ReactNode;
+  asChild?: boolean;
+}
+```
+
+### Usage
+
+```tsx
+import { 
+  Tooltip, 
+  TooltipProvider, 
+  TooltipRoot, 
+  TooltipTrigger, 
+  TooltipContent 
+} from '@jmruthers/pace-core';
+
+// Basic tooltip
+<Tooltip content="This is a helpful tooltip">
+  <Button>Hover me</Button>
+</Tooltip>
+
+// Tooltip with custom delay
+<Tooltip content="Custom delay" delayDuration={500}>
+  <IconButton icon={<Info />} />
+</Tooltip>
+
+// Advanced tooltip with custom content
+<TooltipProvider>
+  <TooltipRoot>
+    <TooltipTrigger asChild>
+      <Button>Advanced Tooltip</Button>
+    </TooltipTrigger>
+    <TooltipContent side="top" className="bg-main-500 text-main-50">
+      <div className="space-y-1">
+        <p className="font-semibold">Advanced Tooltip</p>
+        <p className="text-xs">With custom styling</p>
+      </div>
+    </TooltipContent>
+  </TooltipRoot>
+</TooltipProvider>
+```
+
+### Features
+
+- **Multiple Positioning**: Top, bottom, left, right positioning
+- **Custom Delay**: Configurable delay duration
+- **Smooth Animations**: CSS transitions and animations
+- **Keyboard Support**: Full keyboard navigation
+- **Screen Reader**: Proper ARIA attributes
+- **Responsive**: Adapts to screen size
+
+## Dynamic Theming
+
+### Runtime Theming API
+
+For dynamic theming with organisation/event colors, use the runtime theming API:
+
+```tsx
+import { applyPalette, clearPalette } from '@jmruthers/pace-core/theming/runtime';
+
+// Apply organisation colors
+applyPalette({
+  main: orgData.colors.main,
+  sec: orgData.colors.sec,
+  acc: orgData.colors.acc
+});
+
+// Clear dynamic theming (return to app defaults)
+clearPalette();
+```
+
+
+## Layout Components
+
+### PaceAppLayout
+
+A complete application layout with header, navigation, and content area.
+
+```tsx
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+<PaceAppLayout>
+  <div>Your app content</div>
+</PaceAppLayout>
+```
+
+### Header
+
+Application header with navigation and user menu.
+
+```tsx
+import { Header } from '@jmruthers/pace-core';
+
+<Header
+  title="My App"
+  user={currentUser}
+  onLogout={handleLogout}
+/>
+```
+
+### Footer
+
+Application footer component.
+
+```tsx
+import { Footer } from '@jmruthers/pace-core';
+
+<Footer>
+  <p>&copy; 2024 My App. All rights reserved.</p>
+</Footer>
+```
+
+## Navigation Components
+
+### NavigationMenu
+
+A flexible navigation menu component that supports both dropdown and hierarchical modes with built-in authentication and permission filtering.
+
+```typescript
+interface NavigationMenuProps {
+  items: NavigationItem[];
+  mode?: 'dropdown' | 'hierarchical';
+  currentPath?: string;
+  onNavigate?: (item: NavigationItem) => void;
+  className?: string;
+  disabled?: boolean;
+  buttonText?: string;
+  showIcons?: boolean;
+  navigationLabel?: string;
+  strictMode?: boolean;
+  auditLog?: boolean;
+  onNavigationAccessDenied?: (itemId: string, reason: string) => void;
+  onStrictModeViolation?: (itemId: string, reason: string) => void;
+  filterByPermissions?: boolean;
+}
+
+interface NavigationItem {
+  id: string;
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavigationItem[];
+  isActive?: boolean;
+  permissions?: string[];
+  roles?: string[];
+  accessLevel?: string;
+  pageId?: string;
+  strictMode?: boolean;
+  meta?: {
+    title?: string;
+    description?: string;
+    hidden?: boolean;
+    order?: number;
+  };
+}
+```
+
+#### Usage
+
+**Basic Usage:**
+```tsx
+import { NavigationMenu } from '@jmruthers/pace-core';
+
+const navItems = [
+  { id: 'home', label: 'Home', href: '/', icon: 'Home' },
+  { id: 'dashboard', label: 'Dashboard', href: '/dashboard', icon: 'LayoutDashboard' },
+  { id: 'settings', label: 'Settings', href: '/settings', icon: 'Settings' }
+];
+
+<NavigationMenu 
+  items={navItems}
+  mode="dropdown"
+  currentPath={location.pathname}
+  onNavigate={(item) => navigate(item.href)}
+  buttonText="Menu"
+  showIcons={true}
+/>
+```
+
+**With Authentication and Permissions:**
+```tsx
+import { NavigationMenu } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function AuthenticatedNavigation() {
+  const { hasPermission, hasRole } = useUnifiedAuth();
+
+  const navItems = [
+    { 
+      id: 'dashboard', 
+      label: 'Dashboard', 
+      href: '/dashboard', 
+      icon: 'LayoutDashboard',
+      permissions: ['dashboard:read']
+    },
+    { 
+      id: 'meals', 
+      label: 'Meals', 
+      href: '/meals', 
+      icon: 'UtensilsCrossed',
+      permissions: ['meals:read']
+    },
+    { 
+      id: 'admin', 
+      label: 'Admin Panel', 
+      href: '/admin', 
+      icon: 'Shield',
+      roles: ['admin', 'super_admin']
+    },
+    { 
+      id: 'profile', 
+      label: 'Profile', 
+      href: '/profile', 
+      icon: 'User'
+    }
+  ];
+
+  return (
+    <NavigationMenu 
+      items={navItems}
+      mode="dropdown"
+      currentPath={location.pathname}
+      onNavigate={(item) => navigate(item.href)}
+      buttonText="Navigation"
+      filterByPermissions={true}
+      auditLog={true}
+    />
+  );
+}
+```
+
+### UserMenu
+
+A user menu component with profile and logout options.
+
+```tsx
+import { UserMenu } from '@jmruthers/pace-core';
+
+<UserMenu
+  user={currentUser}
+  onLogout={handleLogout}
+  onProfile={handleProfile}
+/>
+```
+
+## Form Components
+
+### Input
+
+Text input component with validation.
+
+```tsx
+import { Input } from '@jmruthers/pace-core';
+
+<Input
+  name="email"
+  label="Email"
+  type="email"
+  placeholder="Enter your email"
+  required
+/>
+```
+
+### Checkbox
+
+Checkbox component for boolean inputs.
+
+```tsx
+import { Checkbox } from '@jmruthers/pace-core';
+
+<Checkbox
+  name="terms"
+  label="I agree to the terms and conditions"
+  required
+/>
+```
+
+### Label
+
+Form label component.
+
+```tsx
+import { Label } from '@jmruthers/pace-core';
+
+<Label htmlFor="email">Email Address</Label>
+```
+
+## Security Components
+
+### SuperAdminGuard
+
+Conditionally renders content based on super admin status.
+
+```tsx
+import { SuperAdminGuard, SuperAdminBadge, SuperAdminDebugPanel } from '@jmruthers/pace-core';
+
+// Guard content for super admins only
+<SuperAdminGuard fallback={<div>Access denied</div>}>
+  <AdminPanel />
+</SuperAdminGuard>
+
+// Show super admin badge
+<SuperAdminBadge />
+
+// Debug panel (development only)
+<SuperAdminDebugPanel />
+```
+
+### PasswordChangeForm
+
+Form component for changing user passwords.
+
+```tsx
+import { PasswordChangeForm } from '@jmruthers/pace-core';
+
+<PasswordChangeForm 
+  onSubmit={(values) => {
+    // Handle password change
+    console.log('New password:', values.newPassword);
+  }}
+/>
+```
+
+## Print Components
+
+PACE Core includes a comprehensive set of print-optimized components for creating reports and documents.
+
+### PrintLayout
+
+The main container for print documents with A4 optimization.
+
+```typescript
+interface PrintLayoutProps {
+  children: React.ReactNode;
+  orientation?: 'portrait' | 'landscape';
+  pageSize?: 'A4' | 'A3' | 'Letter';
+  className?: string;
+}
+```
+
+### PrintHeader
+
+Document header with title and branding.
+
+```typescript
+interface PrintHeaderProps {
+  title: string;
+  subtitle?: string;
+  branding?: {
+    companyName: string;
+    projectName?: string;
+    logo?: string;
+  };
+  className?: string;
+}
+```
+
+### PrintDataTable
+
+Print-optimized data table with pagination and styling.
+
+```typescript
+interface PrintDataTableProps<TData> {
+  data: TData[];
+  columns: PrintColumn<TData>[];
+  title?: string;
+  showPagination?: boolean;
+  pageSize?: number;
+  className?: string;
+}
+```
+
+### PrintCard
+
+Print-optimized card component.
+
+```typescript
+interface PrintCardProps {
+  children: React.ReactNode;
+  title?: string;
+  className?: string;
+}
+```
+
+### PrintSection
+
+Section divider for print documents.
+
+```typescript
+interface PrintSectionProps {
+  children: React.ReactNode;
+  title?: string;
+  level?: 1 | 2 | 3;
+  className?: string;
+}
+```
+
+### PrintGrid
+
+Grid layout for print documents.
+
+```typescript
+interface PrintGridProps {
+  children: React.ReactNode;
+  columns?: 1 | 2 | 3 | 4;
+  gap?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+```
+
+### PrintButton
+
+Print-optimized button (appears as text in print).
+
+```typescript
+interface PrintButtonProps {
+  children: React.ReactNode;
+  onClick?: () => void;
+  className?: string;
+}
+```
+
+### PrintPageBreak
+
+Forces a page break in print documents.
+
+```tsx
+<PrintPageBreak />
+```
+
+### PrintDivider
+
+Visual divider for print documents.
+
+```tsx
+<PrintDivider />
+```
+
+### Print Usage Example
+
+```tsx
+import {
+  PrintLayout,
+  PrintHeader,
+  PrintDataTable,
+  PrintCard,
+  PrintSection,
+  PrintPageBreak
+} from '@jmruthers/pace-core';
+
+function ReportPage() {
+  return (
+    <PrintLayout orientation="portrait" pageSize="A4">
+      <PrintHeader
+        title="Monthly Report"
+        subtitle="Q4 2024"
+        branding={{
+          companyName: "Your Company",
+          projectName: "Analytics Dashboard"
+        }}
+      />
+      
+      <PrintSection title="Executive Summary" level={1}>
+        <PrintCard title="Key Metrics">
+          <p>Total revenue: $1,234,567</p>
+          <p>Growth rate: 15.3%</p>
+        </PrintCard>
+      </PrintSection>
+      
+      <PrintPageBreak />
+      
+      <PrintSection title="Detailed Data" level={1}>
+        <PrintDataTable
+          data={reportData}
+          columns={columns}
+          title="Revenue by Region"
+          showPagination={true}
+          pageSize={20}
+        />
+      </PrintSection>
+    </PrintLayout>
+  );
+}
+```
+
+For detailed print component usage, see [Print Components Guide](../print-components/README.md).
+
+## Public Page Components
+
+PACE Core includes a complete set of components for creating public pages that work independently of your main application's authentication context.
+
+### PublicPageProvider
+
+**Required wrapper for all public pages.** Provides environment variables and context without authentication.
+
+```typescript
+interface PublicPageProviderProps {
+  children: React.ReactNode;
+  environment?: {
+    supabaseUrl?: string;
+    supabaseKey?: string;
+  };
+}
+```
+
+### PublicPageLayout
+
+**Main layout component for public pages.** Handles event data and provides consistent styling.
+
+```typescript
+interface PublicPageLayoutProps {
+  eventCode: string;
+  children: React.ReactNode;
+  event?: Event | null;
+  showFooter?: boolean;
+  className?: string;
+  errorFallback?: React.ComponentType<{ error: Error; resetError: () => void }>;
+  loadingFallback?: React.ComponentType;
+  customHeader?: React.ReactNode;
+  customFooter?: React.ReactNode;
+  showValidationErrors?: boolean;
+}
+```
+
+### PublicPageHeader
+
+**Header component with event branding and information.**
+
+```typescript
+interface PublicPageHeaderProps {
+  event: Event;
+  eventCode: string;
+  title?: string;
+  description?: string;
+  showEventLogo?: boolean;
+  showAppLogo?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+  customAppLogo?: React.ReactNode;
+  customEventLogo?: React.ReactNode;
+}
+```
+
+### PublicPageFooter
+
+**Footer component with event and app information.**
+
+```typescript
+interface PublicPageFooterProps {
+  event: Event;
+  showEventInfo?: boolean;
+  showCopyright?: boolean;
+  showAppBranding?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+  customCopyright?: string;
+  customAppName?: string;
+}
+```
+
+### PublicLoadingSpinner
+
+**Loading spinner component for public pages.**
+
+```typescript
+interface PublicLoadingSpinnerProps {
+  message?: string;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+```
+
+### PublicErrorBoundary
+
+**Error boundary component for public pages.**
+
+```typescript
+interface PublicErrorBoundaryProps {
+  children: React.ReactNode;
+  fallback?: React.ComponentType<{ error: Error; resetError: () => void }>;
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+```
+
+### Public Page Usage Example
+
+```tsx
+import {
+  PublicPageProvider,
+  PublicPageLayout,
+  PublicPageHeader,
+  PublicPageFooter,
+  usePublicEvent,
+  usePublicRouteParams,
+  PublicLoadingSpinner
+} from '@jmruthers/pace-core';
+
+function PublicPageApp() {
+  return (
+    <PublicPageProvider>
+      <Routes>
+        <Route path="/events/:eventCode" element={<PublicEventPage />} />
+      </Routes>
+    </PublicPageProvider>
+  );
+}
+
+function PublicEventPage() {
+  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
+  const { event, isLoading, error } = usePublicEvent(eventCode || '');
+  
+  if (isLoading) {
+    return <PublicLoadingSpinner message="Loading event..." />;
+  }
+  
+  if (error || !event) {
+    return <div>Event not found</div>;
+  }
+  
+  return (
+    <PublicPageLayout eventCode={eventCode || ''} event={event}>
+      <PublicPageHeader 
+        event={event}
+        eventCode={eventCode || ''}
+        title="Event Details"
+        description="Public information about this event"
+      />
+      
+      <main>
+        {/* Your public page content */}
+      </main>
+      
+      <PublicPageFooter event={event} />
+    </PublicPageLayout>
+  );
+}
+```
+
+For detailed public page implementation, see [Public Pages Guide](../implementation-guides/public-pages.md).
+
+## Utility Components
+
+### ErrorBoundary
+
+Catches and displays React errors gracefully.
+
+```tsx
+import { ErrorBoundary } from '@jmruthers/pace-core';
+
+<ErrorBoundary fallback={<ErrorComponent />}>
+  <ComponentThatMightError />
+</ErrorBoundary>
+```
+
+
+## Component Styling
+
+All components use Tailwind CSS for styling and support:
+
+- **Responsive Design**: Mobile-first approach
+- **Accessibility**: WCAG 2.1 AA compliant
+- **Customization**: Extensible with className prop
+- **Consistent Spacing**: Design system spacing
+- **Typography**: Consistent font hierarchy
+
+## Component Testing
+
+All components include:
+
+- **Unit Tests**: Component behavior testing
+- **Integration Tests**: Component interaction testing
+- **Accessibility Tests**: Screen reader compatibility
+- **Visual Tests**: Visual regression testing
+- **Performance Tests**: Rendering performance
+
+For more information about testing components, see the [Testing Guide](../best-practices/testing.md).
+
+## 🔗 Related Documentation
+
+### Component Usage
+- **[Data Tables Implementation](../implementation-guides/data-tables.md)** - Complete data table guide
+- **[Forms Implementation](../implementation-guides/forms.md)** - Form handling patterns
+- **[App Layout Implementation](../implementation-guides/app-layout.md)** - Layout patterns
+- **[Navigation Implementation](../implementation-guides/navigation.md)** - Navigation systems
+
+### Styling & Theming
+- **[Styling Overview](../styles/README.md)** - Design system and theming
+- **[Component Styling](../styles/component-styling.md)** - How components are styled
+- **[Custom Themes](../styles/custom-themes.md)** - Creating custom themes
+
+### Best Practices
+- **[Component Best Practices](../best-practices/README.md#component-usage)** - Component usage guidelines
+- **[Performance Best Practices](../best-practices/performance.md)** - Performance optimization
+- **[Accessibility Guidelines](../best-practices/README.md#accessibility)** - Accessibility best practices
+
+### Troubleshooting
+- **[Common Issues](../troubleshooting/common-issues.md)** - Component-related problems
+- **[Styling Issues](../troubleshooting/styling-issues.md)** - Styling problems
+- **[Debugging Guide](../troubleshooting/debugging.md)** - Debugging techniques
+
+### Examples
+- **[Basic Auth App](../getting-started/examples/basic-auth-app.md)** - Simple component usage
+- **[Full-Featured App](../getting-started/examples/full-featured-app.md)** - Advanced patterns
+- **[Component Examples](../getting-started/examples/)** - Complete working examples