@hellboy/ds 0.1.2 → 0.2.7

package/src/utils/USER_PREFERENCES.md

@@ -1,558 +0,0 @@
-# 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

@@ -1,127 +0,0 @@
-/**
- * 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;
-};