@hellboy/ds 0.1.2

package/src/utils/USER_PREFERENCES.md

@@ -0,0 +1,558 @@
+# User Preferences Utility
+
+## Overview
+
+The **User Preferences** utility is a comprehensive preference management system for the Hellboy Design System. It provides a practical, type-safe solution for storing and retrieving user preferences across sessions using localStorage with optional IndexedDB support.
+
+## Philosophy
+
+The Hellboy Design System aims to **maximize development velocity** by providing complete, practical solutions rather than staying purely agnostic. While many design systems focus solely on visual components, we believe in delivering utilities that solve common real-world problems developers face when building modern web applications.
+
+This preference system is designed to be:
+
+- ✅ **Easy to use** with minimal configuration
+- ✅ **Type-safe** with TypeScript
+- ✅ **Persistent** across browser sessions
+- ✅ **Extensible** for custom preferences
+- ✅ **Framework-agnostic** (works with React, Vue, Svelte, vanilla JS, etc.)
+
+## Why This Utility Exists
+
+When building applications with the Hellboy Design System, you'll commonly need to:
+
+- Remember user's theme preference (light/dark mode)
+- Persist custom color configurations
+- Save layout preferences (sidebar widths, panel sizes)
+- Store component states (drawer positions, table column preferences)
+- Maintain user-specific settings across sessions
+
+Instead of implementing this functionality from scratch in every project, the User Preferences utility provides a **ready-to-use, production-ready solution** that integrates seamlessly with the design system.
+
+## Installation
+
+The utility is included in the core `@hellboy/ds` package:
+
+```bash
+npm install @hellboy/ds
+```
+
+## Basic Usage
+
+### Importing
+
+```typescript
+import { 
+  getPreference, 
+  setPreference, 
+  removePreference,
+  clearPreferences 
+} from '@hellboy/ds';
+```
+
+### Simple Get/Set
+
+```typescript
+// Set a preference
+setPreference('theme', 'dark');
+setPreference('sidebarWidth', 320);
+
+// Get a preference with optional default
+const theme = getPreference('theme', 'light'); // 'dark'
+const width = getPreference('sidebarWidth', 280); // 320
+
+// Remove a preference
+removePreference('sidebarWidth');
+
+// Clear all preferences
+clearPreferences();
+```
+
+## Supported Preference Types
+
+The utility comes with built-in TypeScript interfaces for common preference categories:
+
+### Theme Preferences
+
+```typescript
+import { setPreference, getPreference } from '@hellboy/ds';
+
+// Theme mode
+setPreference('theme', 'dark');
+
+// Custom color configuration
+setPreference('colorConfig', {
+  primaryHue: 220,
+  primarySaturation: 80,
+  primaryLightness: 50,
+  // ... other color properties
+});
+```
+
+### Layout Preferences
+
+Perfect for remembering resizable panel dimensions:
+
+```typescript
+// Save sidebar widths
+setPreference('layout.leftSidebarWidth', 280);
+setPreference('layout.rightSidebarWidth', 320);
+setPreference('layout.navbarCollapsed', false);
+
+// Restore on load
+const leftWidth = getPreference('layout.leftSidebarWidth', 280);
+const rightWidth = getPreference('layout.rightSidebarWidth', 300);
+```
+
+### Component-Specific Preferences
+
+Store state for individual components:
+
+```typescript
+// Save drawer state
+setPreference('components.drawer.position', 'right');
+setPreference('components.drawer.width', 400);
+
+// Save table preferences
+setPreference('components.userTable.sortColumn', 'name');
+setPreference('components.userTable.sortDirection', 'asc');
+setPreference('components.userTable.pageSize', 50);
+```
+
+### Custom Preferences
+
+Store any custom data:
+
+```typescript
+setPreference('custom.userLanguage', 'pt-BR');
+setPreference('custom.timezone', 'America/Sao_Paulo');
+setPreference('custom.notifications', {
+  email: true,
+  push: false,
+  sms: true
+});
+```
+
+## Advanced Features
+
+### Namespaces
+
+Organize preferences with namespaces:
+
+```typescript
+import { createPreferenceNamespace } from '@hellboy/ds';
+
+// Create a namespace for layout preferences
+const layoutPrefs = createPreferenceNamespace('layout');
+
+// Use scoped methods
+layoutPrefs.set('sidebarWidth', 300);
+layoutPrefs.set('navbarHeight', 64);
+
+const width = layoutPrefs.get('sidebarWidth', 280); // 300
+
+// Clear only layout preferences
+layoutPrefs.clear();
+```
+
+### Export/Import
+
+Backup and restore preferences:
+
+```typescript
+import { exportPreferences, importPreferences } from '@hellboy/ds';
+
+// Export all preferences as JSON
+const json = exportPreferences();
+
+// Download as file
+const blob = new Blob([json], { type: 'application/json' });
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'user-preferences.json';
+a.click();
+
+// Import preferences (merge or replace)
+importPreferences(json, true); // Merge with existing
+importPreferences(json, false); // Replace all
+```
+
+### Get All Preferences
+
+```typescript
+import { getAllPreferences } from '@hellboy/ds';
+
+const allPrefs = getAllPreferences();
+console.log(allPrefs);
+// {
+//   'theme': 'dark',
+//   'layout.leftSidebarWidth': 320,
+//   'custom.language': 'pt-BR',
+//   ...
+// }
+```
+
+### Configuration
+
+Customize the storage backend and key prefix:
+
+```typescript
+import { configurePreferences } from '@hellboy/ds';
+
+// Configure at app initialization
+configurePreferences({
+  backend: 'localStorage', // or 'indexedDB' (future)
+  prefix: 'my-app',
+  dbName: 'my-app-prefs',
+  storeName: 'preferences'
+});
+```
+
+## Framework Integration
+
+### React Hook Pattern
+
+Here's a recommended pattern for React applications:
+
+```tsx
+// hooks/usePreference.ts
+import { useState, useEffect } from 'react';
+import { getPreference, setPreference } from '@hellboy/ds';
+
+export function usePreference<T>(key: string, defaultValue: T) {
+  const [value, setValue] = useState<T>(() => 
+    getPreference(key, defaultValue) ?? defaultValue
+  );
+
+  const updateValue = (newValue: T | ((prev: T) => T)) => {
+    const resolvedValue = typeof newValue === 'function' 
+      ? (newValue as (prev: T) => T)(value)
+      : newValue;
+    
+    setValue(resolvedValue);
+    setPreference(key, resolvedValue);
+  };
+
+  return [value, updateValue] as const;
+}
+
+// Usage in components
+function MyComponent() {
+  const [theme, setTheme] = usePreference('theme', 'light');
+  const [sidebarWidth, setSidebarWidth] = usePreference('layout.sidebarWidth', 280);
+
+  return (
+    <div>
+      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+        Toggle Theme
+      </button>
+      <button onClick={() => setSidebarWidth(w => w + 20)}>
+        Increase Sidebar
+      </button>
+    </div>
+  );
+}
+```
+
+### Vue Composition API
+
+```typescript
+// composables/usePreference.ts
+import { ref, watch } from 'vue';
+import { getPreference, setPreference } from '@hellboy/ds';
+
+export function usePreference<T>(key: string, defaultValue: T) {
+  const value = ref<T>(getPreference(key, defaultValue) ?? defaultValue);
+
+  watch(value, (newValue) => {
+    setPreference(key, newValue);
+  });
+
+  return value;
+}
+
+// Usage in components
+import { usePreference } from '@/composables/usePreference';
+
+export default {
+  setup() {
+    const theme = usePreference('theme', 'light');
+    const sidebarWidth = usePreference('layout.sidebarWidth', 280);
+
+    return { theme, sidebarWidth };
+  }
+}
+```
+
+### Vanilla JavaScript
+
+```javascript
+import { getPreference, setPreference } from '@hellboy/ds';
+
+// On page load
+document.addEventListener('DOMContentLoaded', () => {
+  const theme = getPreference('theme', 'light');
+  document.documentElement.setAttribute('data-theme', theme);
+
+  const sidebarWidth = getPreference('layout.sidebarWidth', 280);
+  document.querySelector('.sidebar').style.width = `${sidebarWidth}px`;
+});
+
+// On user interaction
+document.querySelector('#theme-toggle').addEventListener('click', () => {
+  const current = getPreference('theme', 'light');
+  const next = current === 'light' ? 'dark' : 'light';
+  setPreference('theme', next);
+  document.documentElement.setAttribute('data-theme', next);
+});
+```
+
+## Real-World Examples
+
+### Example 1: Persistent Resizable Sidebar
+
+```typescript
+import { useState, useCallback } from 'react';
+import { getPreference, setPreference } from '@hellboy/ds';
+import { Layout } from '@hellboy/ds';
+
+function App() {
+  const [leftWidth, setLeftWidth] = useState(() => 
+    getPreference('layout.leftSidebarWidth', 280)
+  );
+
+  const handleResize = useCallback((delta: number) => {
+    setLeftWidth(prev => {
+      const newWidth = Math.max(200, Math.min(600, prev + delta));
+      setPreference('layout.leftSidebarWidth', newWidth);
+      return newWidth;
+    });
+  }, []);
+
+  return (
+    <Layout
+      variant="sidebar-main-sidebar"
+      resizable
+      sidebarLeft={<Sidebar width={leftWidth} />}
+      onLeftResize={handleResize}
+    >
+      <MainContent />
+    </Layout>
+  );
+}
+```
+
+### Example 2: Theme Persistence with Color Customization
+
+```typescript
+import { useEffect } from 'react';
+import { 
+  getPreference, 
+  setPreference,
+  applyColorConfig,
+  setTheme 
+} from '@hellboy/ds';
+
+function ThemeProvider({ children }) {
+  useEffect(() => {
+    // Restore theme mode
+    const theme = getPreference('theme', 'light');
+    setTheme(theme);
+
+    // Restore custom colors
+    const colorConfig = getPreference('colorConfig');
+    if (colorConfig) {
+      applyColorConfig(colorConfig);
+    }
+  }, []);
+
+  const updateTheme = (newTheme) => {
+    setPreference('theme', newTheme);
+    setTheme(newTheme);
+  };
+
+  const updateColors = (colorConfig) => {
+    setPreference('colorConfig', colorConfig);
+    applyColorConfig(colorConfig);
+  };
+
+  return children;
+}
+```
+
+### Example 3: Table Preferences
+
+```typescript
+function DataTable() {
+  const [sortColumn, setSortColumn] = usePreference('table.sortColumn', 'name');
+  const [sortDirection, setSortDirection] = usePreference('table.sortDirection', 'asc');
+  const [pageSize, setPageSize] = usePreference('table.pageSize', 25);
+  const [visibleColumns, setVisibleColumns] = usePreference('table.visibleColumns', [
+    'name', 'email', 'role', 'status'
+  ]);
+
+  return (
+    <Table
+      sortColumn={sortColumn}
+      sortDirection={sortDirection}
+      pageSize={pageSize}
+      visibleColumns={visibleColumns}
+      onSortChange={(col, dir) => {
+        setSortColumn(col);
+        setSortDirection(dir);
+      }}
+      onPageSizeChange={setPageSize}
+      onVisibleColumnsChange={setVisibleColumns}
+    />
+  );
+}
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `getPreference<T>(key, defaultValue?)` | Get a preference value |
+| `setPreference<T>(key, value)` | Set a preference value |
+| `removePreference(key)` | Remove a preference |
+| `clearPreferences()` | Clear all preferences |
+| `getAllPreferences()` | Get all preferences as object |
+
+### Async Functions (IndexedDB)
+
+| Function | Description |
+|----------|-------------|
+| `getPreferenceAsync<T>(key, defaultValue?)` | Async get for IndexedDB |
+| `setPreferenceAsync<T>(key, value)` | Async set for IndexedDB |
+| `removePreferenceAsync(key)` | Async remove for IndexedDB |
+| `clearPreferencesAsync()` | Async clear for IndexedDB |
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `configurePreferences(config)` | Configure storage backend |
+| `createPreferenceNamespace(namespace)` | Create scoped preferences |
+| `exportPreferences()` | Export preferences as JSON |
+| `importPreferences(json, merge?)` | Import preferences from JSON |
+
+## TypeScript Support
+
+The utility is fully typed with TypeScript:
+
+```typescript
+import type { UserPreferences } from '@hellboy/ds';
+
+// Type-safe preference access
+const theme = getPreference<'light' | 'dark'>('theme', 'light');
+const width = getPreference<number>('layout.sidebarWidth', 280);
+
+// Extend UserPreferences interface for custom types
+declare module '@hellboy/ds' {
+  interface UserPreferences {
+    custom?: {
+      myCustomSetting?: string;
+      myFeatureFlags?: {
+        newUI: boolean;
+        betaFeatures: boolean;
+      };
+    };
+  }
+}
+```
+
+## Storage Details
+
+### localStorage (Default)
+
+- **Prefix**: `hellboy-ds:` (configurable)
+- **Format**: JSON serialization
+- **Capacity**: ~5-10MB (browser-dependent)
+- **Sync**: Synchronous operations
+- **Browser Support**: All modern browsers
+
+### IndexedDB (Future)
+
+- **Database**: `hellboy-ds-prefs` (configurable)
+- **Store**: `preferences` (configurable)
+- **Format**: Native JSON
+- **Capacity**: Much larger than localStorage
+- **Sync**: Asynchronous operations
+- **Browser Support**: All modern browsers
+
+## Best Practices
+
+1. **Use meaningful keys**: Use dot notation for hierarchical organization
+   ```typescript
+   setPreference('components.drawer.width', 400);
+   setPreference('layout.sidebar.collapsed', true);
+   ```
+
+2. **Always provide defaults**: Ensures app works on first load
+   ```typescript
+   const width = getPreference('sidebarWidth', 280);
+   ```
+
+3. **Namespace related preferences**: Keep things organized
+   ```typescript
+   const layoutPrefs = createPreferenceNamespace('layout');
+   ```
+
+4. **Export for backups**: Allow users to backup their settings
+   ```typescript
+   const json = exportPreferences();
+   ```
+
+5. **Type your preferences**: Use TypeScript for type safety
+   ```typescript
+   const theme = getPreference<'light' | 'dark'>('theme', 'light');
+   ```
+
+## Browser Compatibility
+
+- ✅ Chrome 4+
+- ✅ Firefox 3.5+
+- ✅ Safari 4+
+- ✅ Edge (all versions)
+- ✅ Opera 10.50+
+- ✅ iOS Safari 3.2+
+- ✅ Android Browser 2.1+
+
+## Performance Considerations
+
+- localStorage is **synchronous** - operations block the main thread
+- For **large datasets** (>1MB), consider using IndexedDB backend (when available)
+- **Batch updates** when possible to minimize localStorage writes
+- Use **namespaces** to organize and clear related preferences efficiently
+
+## Security Notes
+
+- localStorage is **not encrypted** - don't store sensitive data
+- Data is **domain-specific** - accessible to all scripts on the same origin
+- Data persists **indefinitely** until explicitly cleared or browser storage is cleared
+- Consider **user privacy** - allow users to export/clear their data
+
+## Migration from Legacy Storage
+
+If you're migrating from direct localStorage usage:
+
+```typescript
+// Before
+localStorage.setItem('myTheme', 'dark');
+const theme = localStorage.getItem('myTheme') || 'light';
+
+// After
+import { setPreference, getPreference } from '@hellboy/ds';
+setPreference('theme', 'dark');
+const theme = getPreference('theme', 'light');
+```
+
+## Support & Contributing
+
+This utility is part of the Hellboy Design System. For issues, feature requests, or contributions, please visit the [GitHub repository](#).
+
+---
+
+**Design System Philosophy**: We believe in providing **practical, opinionated solutions** that accelerate development. While staying framework-agnostic where possible, we're not afraid to be opinionated when it delivers real value to developers. The User Preferences utility embodies this philosophy by solving a common problem with a production-ready, batteries-included solution.

package/src/utils/theme.ts

@@ -0,0 +1,127 @@
+/**
+ * Theme Utility
+ * Manages data-theme attribute on <html>, localStorage persistence, and prefers-color-scheme fallback
+ * 
+ * Priority: data-theme (explicit) > prefers-color-scheme (OS preference) > light (default)
+ * 
+ * This utility now uses the User Preferences system for storage.
+ * See USER_PREFERENCES.md for more details on the underlying storage system.
+ */
+
+import { getPreference, setPreference } from './user-preferences';
+
+type Theme = 'light' | 'dark';
+
+// Preference key for storing the chosen mode only
+const THEME_KEY = 'theme';
+
+const ATTR_NAME = 'data-theme';
+
+/**
+ * Apply theme to document element
+ */
+export const applyTheme = (theme: Theme) => {
+  document.documentElement.setAttribute(ATTR_NAME, theme);
+};
+
+/**
+ * Get current theme.
+ * Sources of truth (simplified):
+ *  - `data-theme` attribute on <html>
+ *  - OS `prefers-color-scheme`
+ *  - default: 'light'
+ */
+export const getTheme = (): Theme => {
+  // 1. If `data-theme` is explicitly set on <html>, that wins
+  const dataTheme = document.documentElement.getAttribute(ATTR_NAME);
+  if (dataTheme === 'light' || dataTheme === 'dark') return dataTheme;
+
+  // 2. If the user previously selected a mode, use stored preference
+  try {
+    const stored = getPreference<Theme>(THEME_KEY);
+    if (stored === 'light' || stored === 'dark') return stored;
+  } catch (e) {
+    // ignore storage errors and fallback to system/default
+  }
+
+  // 3. Fall back to OS preference
+  if (typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+    return 'dark';
+  }
+
+  // 4. Default
+  return 'light';
+};
+
+/**
+ * Backwards-compatible alias
+ */
+export const getSavedTheme = (): Theme => getTheme();
+
+/**
+ * Set theme on document (no persistence)
+ */
+export const setTheme = (theme: Theme) => {
+  if (!['light', 'dark'].includes(theme)) {
+    console.warn(`Invalid theme: ${theme}. Using 'light' as fallback.`);
+    theme = 'light';
+  }
+
+  // Persist only the mode (light/dark)
+  try {
+    setPreference(THEME_KEY, theme);
+  } catch (e) {
+    // ignore storage errors
+  }
+
+  applyTheme(theme);
+};
+
+/**
+ * Initialize theme on startup (mode-only)
+ */
+export const initializeTheme = () => {
+  const theme = getTheme();
+  applyTheme(theme);
+};
+
+/**
+ * Listen to system theme changes. Only calls callback when OS preference
+ * changes. Consumers decide whether to apply it.
+ */
+export const onSystemThemeChange = (callback: (theme: Theme) => void): (() => void) => {
+  if (typeof window === 'undefined') return () => {};
+
+  const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+  const listener = (e: MediaQueryListEvent | MediaQueryList) => {
+    const theme = e.matches ? 'dark' : 'light';
+    // Only notify consumers if the user has NOT explicitly chosen a mode
+    const hasStored = (() => {
+      try {
+        const stored = getPreference<Theme>(THEME_KEY);
+        return stored === 'light' || stored === 'dark';
+      } catch { return false; }
+    })();
+
+    const dataTheme = document.documentElement.getAttribute(ATTR_NAME);
+    if (!hasStored && !dataTheme) callback(theme);
+  };
+
+  if (mediaQuery.addEventListener) {
+    mediaQuery.addEventListener('change', listener);
+    return () => mediaQuery.removeEventListener('change', listener);
+  }
+
+  mediaQuery.addListener(listener as any);
+  return () => mediaQuery.removeListener(listener as any);
+};
+
+/**
+ * Toggle between light and dark themes (no persistence)
+ */
+export const toggleTheme = (): Theme => {
+  const current = getTheme();
+  const next = current === 'light' ? 'dark' : 'light';
+  setTheme(next);
+  return next;
+};