@hellboy/ds 0.1.2

package/src/utils/README.md

@@ -0,0 +1,305 @@
+# Design System Utilities
+
+This directory contains utility modules that provide practical, production-ready solutions for common application needs.
+
+## Philosophy
+
+The Hellboy Design System utilities are designed to **accelerate development** by providing complete, opinionated solutions that go beyond basic component libraries. While we remain framework-agnostic where possible, we prioritize **developer productivity** and **real-world usability** over pure abstraction.
+
+## Available Utilities
+
+### 🎨 Theme Utilities (`theme.ts`)
+
+Theme management with support for:
+- Light/dark mode switching
+- System preference detection
+- Custom color configuration
+- Persistent storage across sessions
+
+**Key Features:**
+- Automatic OS theme detection
+- localStorage persistence (now using User Preferences system)
+- CSS variable management
+- TypeScript type safety
+
+**Documentation:** See inline JSDoc comments in `theme.ts`
+
+**Quick Start:**
+```typescript
+import { getTheme, setTheme, toggleTheme } from '@hellboy/ds';
+
+// Get current theme
+const theme = getTheme(); // 'light' | 'dark'
+
+// Set theme
+setTheme('dark');
+
+// Toggle theme
+toggleTheme();
+```
+
+---
+
+### 💾 User Preferences (`user-preferences.ts`)
+
+Comprehensive preference management system for storing user settings, configurations, and UI state.
+
+**Key Features:**
+- Type-safe preference storage
+- localStorage with optional IndexedDB fallback
+- Namespace support for organization
+- Export/import functionality
+- Framework-agnostic design
+- Automatic migration from legacy storage
+
+**Use Cases:**
+- Theme preferences (light/dark, custom colors)
+- Layout dimensions (sidebar widths, panel sizes)
+- Component states (drawer positions, table settings)
+- User-specific settings (language, timezone, etc.)
+
+**Documentation:** See `USER_PREFERENCES.md` for comprehensive guide
+
+**Quick Start:**
+```typescript
+import { getPreference, setPreference } from '@hellboy/ds';
+
+// Save a preference
+setPreference('sidebarWidth', 300);
+
+// Load a preference with default
+const width = getPreference('sidebarWidth', 280);
+
+// Use with namespaces
+import { createPreferenceNamespace } from '@hellboy/ds';
+const layoutPrefs = createPreferenceNamespace('layout');
+layoutPrefs.set('collapsed', true);
+```
+
+---
+
+## Integration Examples
+
+### Theme + User Preferences
+
+The theme utilities now use the User Preferences system under the hood, providing automatic migration from legacy storage:
+
+```typescript
+import { setTheme, getTheme } from '@hellboy/ds';
+
+// Theme is automatically stored using the preference system
+setTheme('dark'); // Saved to preferences as 'theme': 'dark'
+
+// Retrieve theme (checks preferences, then legacy localStorage)
+const theme = getTheme();
+```
+
+### Layout with Persistent Dimensions
+
+The `Layout` component automatically saves sidebar widths:
+
+```tsx
+import { Layout } from '@hellboy/ds';
+
+// Sidebar widths are automatically saved and restored
+<Layout
+  variant="sidebar-main-sidebar"
+  resizable
+  sidebarLeft={<Sidebar />}
+  sidebarRight={<RightPanel />}
+>
+  <MainContent />
+</Layout>
+```
+
+Internally, the Layout component uses:
+```typescript
+const leftWidth = getPreference('layout.leftSidebarWidth', 280);
+// User resizes sidebar...
+setPreference('layout.leftSidebarWidth', newWidth);
+```
+
+### React Hook Pattern
+
+Create reusable hooks for your app:
+
+```typescript
+// hooks/usePreference.ts
+import { useState } 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) => {
+    setValue(newValue);
+    setPreference(key, newValue);
+  };
+
+  return [value, updateValue] as const;
+}
+
+// Use 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>
+    </div>
+  );
+}
+```
+
+## Design Decisions
+
+### Why User Preferences?
+
+Many design systems stop at providing UI components. We believe that's only half the story. Real applications need:
+
+1. **State Persistence**: Users expect their preferences to be remembered
+2. **Type Safety**: TypeScript support prevents runtime errors
+3. **Organization**: Namespaces keep large apps maintainable
+4. **Portability**: Export/import allows users to backup settings
+5. **Migration**: Automatic legacy storage migration prevents breaking changes
+
+### Why localStorage by Default?
+
+- ✅ **Synchronous**: No async complexity for simple use cases
+- ✅ **Universal**: Supported in all browsers (even old ones)
+- ✅ **Simple**: No setup required, works out of the box
+- ✅ **Adequate**: 5-10MB is sufficient for most preferences
+
+IndexedDB support is included for future expansion when dealing with larger datasets.
+
+### Integration with Components
+
+Where appropriate, design system components integrate with the preference system automatically:
+
+- **Layout**: Saves sidebar/panel dimensions
+- **Theme**: Persists theme mode and custom colors
+- **Future components**: Will leverage preferences for state persistence
+
+This integration is **opt-in** via the `resizable` prop or similar, ensuring components remain flexible.
+
+## Best Practices
+
+### 1. Use Meaningful Key Names
+
+Organize preferences with dot notation:
+
+```typescript
+// Good
+setPreference('layout.sidebar.width', 300);
+setPreference('components.drawer.position', 'right');
+setPreference('user.language', 'pt-BR');
+
+// Avoid
+setPreference('w', 300);
+setPreference('pos', 'right');
+```
+
+### 2. Always Provide Defaults
+
+Ensure your app works on first load:
+
+```typescript
+// Good
+const width = getPreference('sidebarWidth', 280);
+
+// Avoid
+const width = getPreference('sidebarWidth'); // Could be undefined
+```
+
+### 3. Use Namespaces for Related Preferences
+
+Keep things organized:
+
+```typescript
+const layoutPrefs = createPreferenceNamespace('layout');
+const userPrefs = createPreferenceNamespace('user');
+
+layoutPrefs.set('sidebarWidth', 300);
+userPrefs.set('language', 'pt-BR');
+```
+
+### 4. Type Your Preferences
+
+Leverage TypeScript:
+
+```typescript
+type Theme = 'light' | 'dark';
+const theme = getPreference<Theme>('theme', 'light');
+```
+
+### 5. Consider User Privacy
+
+Allow users to export/clear their data:
+
+```typescript
+import { exportPreferences, clearPreferences } from '@hellboy/ds';
+
+// Export for backup
+const json = exportPreferences();
+
+// Clear all data
+clearPreferences();
+```
+
+## Migration Guide
+
+### From Direct localStorage
+
+If you're currently using `localStorage` directly:
+
+```typescript
+// Before
+localStorage.setItem('myTheme', 'dark');
+const theme = localStorage.getItem('myTheme') || 'light';
+
+// After
+import { setPreference, getPreference } from '@hellboy/ds';
+setPreference('myTheme', 'dark');
+const theme = getPreference('myTheme', 'light');
+```
+
+### From Legacy DS Theme Utils
+
+The theme utilities automatically migrate:
+
+```typescript
+// No changes needed! Your existing code works:
+import { setTheme, getTheme } from '@hellboy/ds';
+
+setTheme('dark'); // Now uses User Preferences internally
+const theme = getTheme(); // Checks new system, falls back to legacy
+```
+
+## Contributing
+
+When adding new utilities:
+
+1. **Document thoroughly**: Include JSDoc comments and examples
+2. **Provide TypeScript types**: Full type safety is required
+3. **Stay framework-agnostic**: Utilities should work in any environment
+4. **Write tests**: Ensure reliability
+5. **Update this README**: Keep documentation current
+
+## Future Utilities
+
+Planned additions:
+
+- 🔄 **State Management**: Simple state sync across tabs
+- 🌐 **i18n**: Internationalization helpers
+- 📊 **Analytics**: Privacy-focused analytics utilities
+- 🔒 **Validation**: Form validation helpers
+- 📱 **Responsive**: Breakpoint utilities
+
+---
+
+**Remember**: The goal is to provide **practical, production-ready solutions** that make developers' lives easier. If you find yourself writing the same code across multiple projects, it might be a good candidate for a utility in this directory.