@hellboy/ds 0.1.3 → 0.2.7

package/src/style/styles.css

@@ -1,51 +0,0 @@
-/**
- * Hellboy Design System - Main Styles
- * Central import for all tokens, foundations, themes, and component styles
- */
-
-/* Google Fonts */
-@import url('https://fonts.googleapis.com/css2?family=Signika:wght@300..700&family=Rubik:ital,wght@0,300;0,500;0,600;0,700;1,400;1,500;1,600;1,700&display=swap');
-
-/* Theme (replaceable)
-	NOTE: `theme.json` is the source of truth for theme values (7 core colors).
-	During build we generate `theme.css` from `src/style/themes/theme.json` and
-	write it to `dist/theme.css` so consumers can load `/theme.css` directly.
-	Do NOT import `theme.css` into this bundled stylesheet; keep the file
-	separate so end-users can override or replace `theme.json` as needed.
-*/
-
-/* Foundations */
-@import './foundations/typography.css';
-@import './foundations/spacing.css';
-@import './foundations/motion.css';
-@import './foundations/z-index.css';
-@import './foundations/global.css';
-
-/* Modes */
-@import './modes/light.css';
-@import './modes/dark.css';
-
-/* Semantic (color mappings) */
-@import './semantic.css';
-
-/* Component Styles */
-@import './components/button/button.css';
-@import './components/checkbox.css';
-@import './components/switch/switch.css';
-@import './components/header/header.css';
-@import './components/page/page.css';
-@import './components/section/section.css';
-@import './components/layout/layout.css';
-@import './components/navbar/navbar.css';
-@import './components/code-block/code-block.css';
-@import './components/popover/popover.css';
-@import './components/theme-control/theme-control.css';
-@import './components/card/card.css';
-@import './components/color-control/color-control.css';
-@import './components/grid/grid.css';
-@import './components/slider/slider.css';
-@import './components/input/input.css';
-@import './components/list/list.css';
-@import './components/radio.css';
-@import './components/select/select.css';
-@import './components/page-index/page-index.css';

package/src/style/themes/theme.json

@@ -1,37 +0,0 @@
-{
-  "primary": {
-    "hue": 0,
-    "saturation": 69,
-    "lightness": 31
-  },
-  "secondary": {
-    "hue": 16,
-    "saturation": 63,
-    "lightness": 23
-  },
-  "accent": {
-    "hue": 0,
-    "saturation": 89,
-    "lightness": 41
-  },
-  "success": {
-    "hue": 140,
-    "saturation": 100,
-    "lightness": 19
-  },
-  "warning": {
-    "hue": 34,
-    "saturation": 100,
-    "lightness": 31
-  },
-  "error": {
-    "hue": 264,
-    "saturation": 0,
-    "lightness": 14
-  },
-  "info": {
-    "hue": 261,
-    "saturation": 69,
-    "lightness": 31
-  }
-}

package/src/utils/README.md

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