@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/api-reference/components.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Components API Reference
 
 > **📚 Complete API Reference** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
@@ -1572,6 +1578,193 @@ All components include:
 
 For more information about testing components, see the [Testing Guide](../best-practices/testing.md).
 
+## Avatar
+
+Display user profile pictures with fallback initials or icons.
+
+### Props
+
+```typescript
+interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+  className?: string;
+}
+
+interface AvatarImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  src?: string;
+  alt?: string;
+  className?: string;
+}
+
+interface AvatarFallbackProps extends React.HTMLAttributes<HTMLDivElement> {
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from '@jmruthers/pace-core';
+
+// User avatar
+<Avatar>
+  <AvatarImage src="/user.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+
+// Avatar without image
+<Avatar>
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+```
+
+### Features
+
+- Automatic fallback to initials or icon
+- Responsive sizing
+- Accessible ARIA attributes
+- Integration with user profiles
+
+---
+
+## Switch
+
+Toggle switch component for boolean controls.
+
+### Props
+
+```typescript
+interface SwitchProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Switch } from '@jmruthers/pace-core';
+
+// Controlled switch
+<Switch checked={isEnabled} onCheckedChange={setIsEnabled} />
+
+// Uncontrolled switch
+<Switch defaultChecked={true} />
+
+// Disabled switch
+<Switch disabled={true} />
+```
+
+### Features
+
+- Keyboard accessible
+- Mouse and touch support
+- Customizable styling
+- Screen reader friendly
+
+---
+
+## Progress
+
+Progress indicator for loading states and task completion.
+
+### Props
+
+```typescript
+interface ProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+  value?: number;
+  max?: number;
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Progress } from '@jmruthers/pace-core';
+
+// Progress bar
+<Progress value={60} max={100} />
+
+// Indeterminate progress (no value)
+<Progress />
+```
+
+### Features
+
+- Determinate and indeterminate modes
+- Accessible progress announcements
+- Customizable appearance
+- Smooth animations
+
+---
+
+## Table (Basic)
+
+Semantic HTML table components for data display.
+
+### Props
+
+```typescript
+interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
+  className?: string;
+}
+```
+
+### Components
+
+```typescript
+Table               // Root table element
+TableHeader         // Table header section
+TableBody           // Table body section  
+TableFooter         // Table footer section
+TableHead           // Header cell
+TableCell           // Data cell
+TableRow            // Table row
+TableCaption        // Table caption
+```
+
+### Usage
+
+```tsx
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption
+} from '@jmruthers/pace-core';
+
+<Table>
+  <TableCaption>Monthly Sales Report</TableCaption>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Month</TableHead>
+      <TableHead>Sales</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>January</TableCell>
+      <TableCell>$10,000</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Features
+
+- Semantic HTML structure
+- Accessible table markup
+- Customizable styling
+- Responsive design support
+
+---
+
 ## 🔗 Related Documentation
 
 ### Component Usage

package/docs/api-reference/hooks.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Hooks API Reference
 
 > **🔗 React Hooks Reference** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
@@ -961,6 +967,265 @@ function AppSettings() {
 }
 ```
 
+---
+
+## UI Interaction Hooks
+
+### useFocusManagement
+
+Manage focus within a container for accessibility.
+
+```typescript
+interface FocusManagementOptions {
+  trapFocus?: boolean;
+  autoFocus?: boolean;
+  restoreFocus?: boolean;
+  onEscape?: () => void;
+  onFocusFirst?: () => void;
+  onFocusLast?: () => void;
+}
+
+function useFocusManagement(options?: FocusManagementOptions): FocusManagementReturn;
+```
+
+**Usage:**
+```tsx
+import { useFocusManagement } from '@jmruthers/pace-core';
+
+function Modal({ children, onClose }) {
+  const { containerRef, focusFirst, handleEscape } = useFocusManagement({
+    autoFocus: true,
+    restoreFocus: true,
+    onEscape: onClose
+  });
+
+  return (
+    <div ref={containerRef}>
+      {children}
+    </div>
+  );
+}
+```
+
+### useFocusTrap
+
+Create accessible focus traps for modals and overlays.
+
+```typescript
+interface FocusTrapOptions {
+  isActive?: boolean;
+  autoFocus?: boolean;
+  restoreFocus?: boolean;
+  onEscape?: () => void;
+  focusableSelector?: string;
+}
+
+function useFocusTrap(options?: FocusTrapOptions): FocusTrapReturn;
+```
+
+**Usage:**
+```tsx
+import { useFocusTrap } from '@jmruthers/pace-core';
+
+function Dialog({ isOpen, children, onClose }) {
+  const { containerRef, focusFirst } = useFocusTrap({
+    isActive: isOpen,
+    autoFocus: true,
+    restoreFocus: true,
+    onEscape: onClose
+  });
+
+  if (!isOpen) return null;
+
+  return (
+    <div ref={containerRef}>
+      {children}
+    </div>
+  );
+}
+```
+
+### useKeyboardShortcuts
+
+Register keyboard shortcuts with support for modifiers.
+
+```typescript
+interface KeyboardShortcut {
+  key: string;
+  handler: (event: KeyboardEvent) => void;
+  description?: string;
+  enabled?: boolean;
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+}
+
+function useKeyboardShortcuts(
+  shortcuts: KeyboardShortcut[],
+  options?: KeyboardShortcutsOptions
+): void;
+```
+
+**Usage:**
+```tsx
+import { useKeyboardShortcuts } from '@jmruthers/pace-core';
+
+function Editor({ onSave, onCancel }) {
+  useKeyboardShortcuts([
+    { key: 'ctrl+s', handler: onSave, description: 'Save file' },
+    { key: 'Escape', handler: onCancel, description: 'Cancel editing' },
+    { key: 'ctrl+a', handler: () => selectAll(), description: 'Select all' }
+  ]);
+
+  return <textarea />;
+}
+```
+
+### useIsMobile
+
+Detect mobile device for responsive behavior.
+
+```typescript
+function useIsMobile(): boolean;
+```
+
+**Usage:**
+```tsx
+import { useIsMobile } from '@jmruthers/pace-core';
+
+function ResponsiveLayout({ children }) {
+  const isMobile = useIsMobile();
+
+  return (
+    <div className={isMobile ? 'mobile' : 'desktop'}>
+      {children}
+    </div>
+  );
+}
+```
+
+### useDebounce
+
+Debounce values for delayed updates.
+
+```typescript
+function useDebounce<T>(value: T, delay: number): T;
+```
+
+**Usage:**
+```tsx
+import { useDebounce } from '@jmruthers/pace-core';
+
+function SearchBox() {
+  const [searchTerm, setSearchTerm] = useState('');
+  const debouncedSearchTerm = useDebounce(searchTerm, 500);
+
+  useEffect(() => {
+    if (debouncedSearchTerm) {
+      performSearch(debouncedSearchTerm);
+    }
+  }, [debouncedSearchTerm]);
+
+  return <input value={searchTerm} onChange={e => setSearchTerm(e.target.value)} />;
+}
+```
+
+### useZodForm
+
+Create forms with Zod validation.
+
+```typescript
+function useZodForm<TData>(schema: ZodSchema<TData>): FormReturn<TData>;
+```
+
+**Usage:**
+```tsx
+import { useZodForm } from '@jmruthers/pace-core';
+import { z } from 'zod';
+
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email()
+});
+
+function UserForm() {
+  const form = useZodForm(userSchema);
+
+  return (
+    <form onSubmit={form.handleSubmit(handleSubmit)}>
+      {/* Form fields */}
+    </form>
+  );
+}
+```
+
+---
+
+## Performance Hooks (Advanced)
+
+### useComponentPerformance
+
+Monitor component render performance.
+
+```typescript
+function useComponentPerformance(componentName: string): PerformanceMetrics;
+```
+
+**Usage:**
+```tsx
+import { useComponentPerformance } from '@jmruthers/pace-core';
+
+function ExpensiveComponent({ data }) {
+  const { renderTime } = useComponentPerformance('ExpensiveComponent');
+  
+  // Component logic
+}
+```
+
+### usePerformanceMonitor
+
+Monitor overall application performance.
+
+```typescript
+function usePerformanceMonitor(): PerformanceData;
+```
+
+**Usage:**
+```tsx
+import { usePerformanceMonitor } from '@jmruthers/pace-core';
+
+function PerformanceDashboard() {
+  const metrics = usePerformanceMonitor();
+  
+  return <div>Render time: {metrics.renderTime}ms</div>;
+}
+```
+
+### useDataTablePerformance
+
+Monitor DataTable performance metrics.
+
+```typescript
+function useDataTablePerformance(): DataTablePerformanceMetrics;
+```
+
+**Usage:**
+```tsx
+import { useDataTablePerformance } from '@jmruthers/pace-core';
+
+function DataTableWithMetrics() {
+  const metrics = useDataTablePerformance();
+  
+  return (
+    <>
+      <DataTable data={data} columns={columns} />
+      {metrics.renderTime > 100 && <WarningSlow />}
+    </>
+  );
+}
+```
+
+---
+
 ## Hook Testing
 
 All hooks include comprehensive testing:

package/docs/api-reference/providers.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Providers API Reference
 
 This section provides detailed API documentation for all context providers in `@jmruthers/pace-core`.

package/docs/api-reference/types.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Types API Reference
 
 This section provides detailed documentation for all TypeScript types and interfaces in `@jmruthers/pace-core`.

package/docs/api-reference/utilities.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Utilities API Reference
 
 This section provides detailed documentation for all utility functions in `@jmruthers/pace-core`.
@@ -378,6 +384,207 @@ import { sanitizeFormData } from '@jmruthers/pace-core';
 const sanitizedData = sanitizeFormData(formData);
 ```
 
+## Utility Functions
+
+### cn (ClassName Merge)
+
+Utility for merging Tailwind CSS classes with conflict resolution.
+
+```typescript
+function cn(...inputs: ClassValue[]): string;
+```
+
+#### Usage
+
+```typescript
+import { cn } from '@jmruthers/pace-core';
+
+// Merge classes
+cn('px-4 py-2', 'bg-main-500', 'hover:bg-main-600')
+
+// Conditional classes
+cn('base-class', isActive && 'active-class', isDisabled && 'disabled-class')
+
+// Override conflicts (last one wins)
+cn('px-4', 'px-2') // Returns 'px-2'
+```
+
+### formatCurrency
+
+Format a number as currency.
+
+```typescript
+function formatCurrency(
+  value: number, 
+  currencyCode?: string, 
+  locale?: string
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatCurrency } from '@jmruthers/pace-core';
+
+formatCurrency(1234.56) // '$1,234.56'
+formatCurrency(1234.56, 'EUR') // '€1,234.56'
+formatCurrency(1234.56, 'USD', 'en-AU') // '$1,234.56'
+```
+
+### formatNumber
+
+Format a number with custom Intl.NumberFormat options.
+
+```typescript
+function formatNumber(
+  value: number,
+  options?: Intl.NumberFormatOptions,
+  locale?: string
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatNumber } from '@jmruthers/pace-core';
+
+formatNumber(1234.56, { minimumFractionDigits: 2, maximumFractionDigits: 2 })
+formatNumber(1234.56, { style: 'decimal', minimumFractionDigits: 0 })
+```
+
+### formatPercent
+
+Format a number as a percentage.
+
+```typescript
+function formatPercent(
+  value: number,
+  locale?: string,
+  decimals?: number
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatPercent } from '@jmruthers/pace-core';
+
+formatPercent(45.5) // '45.5%'
+formatPercent(45.5, 'en-US', 2) // '45.50%'
+```
+
+### formatCompactNumber
+
+Format large numbers with K, M, B abbreviations.
+
+```typescript
+function formatCompactNumber(value: number, locale?: string): string;
+```
+
+#### Usage
+
+```typescript
+import { formatCompactNumber } from '@jmruthers/pace-core';
+
+formatCompactNumber(1000) // '1K'
+formatCompactNumber(1500000) // '1.5M'
+formatCompactNumber(2300000000) // '2.3B'
+```
+
+### formatFileSize
+
+Format file size in bytes to human-readable string.
+
+```typescript
+function formatFileSize(bytes: number): string;
+```
+
+#### Usage
+
+```typescript
+import { formatFileSize } from '@jmruthers/pace-core';
+
+formatFileSize(1024) // '1 KB'
+formatFileSize(1048576) // '1 MB'
+formatFileSize(0) // '0 Bytes'
+```
+
+### App Configuration Utilities
+
+#### setAppConfig
+
+Set the current application configuration.
+
+```typescript
+function setAppConfig(config: AppConfig): void;
+
+interface AppConfig {
+  appName: string;
+  appId: string;
+}
+```
+
+#### Usage
+
+```typescript
+import { setAppConfig } from '@jmruthers/pace-core';
+
+setAppConfig({
+  appName: 'My App',
+  appId: 'my-app-id'
+});
+```
+
+#### getAppConfig
+
+Get the current application configuration.
+
+```typescript
+function getAppConfig(): AppConfig;
+```
+
+#### Usage
+
+```typescript
+import { getAppConfig } from '@jmruthers/pace-core';
+
+const config = getAppConfig();
+console.log(config.appName); // 'My App'
+console.log(config.appId);   // 'my-app-id'
+```
+
+#### getCurrentAppName
+
+Get the current app name.
+
+```typescript
+function getCurrentAppName(): string;
+```
+
+#### Usage
+
+```typescript
+import { getCurrentAppName } from '@jmruthers/pace-core';
+
+const appName = getCurrentAppName(); // 'My App'
+```
+
+#### getCurrentAppId
+
+Get the current app ID.
+
+```typescript
+function getCurrentAppId(): string;
+```
+
+#### Usage
+
+```typescript
+import { getCurrentAppId } from '@jmruthers/pace-core';
+
+const appId = getCurrentAppId(); // 'my-app-id'
+```
+
 ## Date and Time Utilities
 
 ### formatDate

package/docs/architecture/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # PACE Core Architecture
 
 This document provides a comprehensive overview of the PACE Core architecture, including system design, component relationships, and architectural decisions. This is the single source of truth for PACE Core's architectural documentation.