@hellboy/ds 0.1.2

package/src/utils/user-preferences.ts

@@ -0,0 +1,577 @@
+/**
+ * User Preferences Utility
+ * 
+ * A comprehensive user preference management system for the Hellboy Design System.
+ * This utility provides a practical, opinionated solution for storing and retrieving
+ * user preferences using localStorage with optional IndexedDB fallback.
+ * 
+ * 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.
+ * 
+ * This preference system is designed to be:
+ * - Easy to use with minimal configuration
+ * - Type-safe with TypeScript
+ * - Persistent across sessions
+ * - Extensible for custom preferences
+ * - Framework-agnostic (works with React, Vue, vanilla JS, etc.)
+ * 
+ * Supported preference categories:
+ * - Theme preferences (light/dark mode, custom colors)
+ * - Layout preferences (sidebar widths, panel sizes)
+ * - Component states (drawer positions, table column widths)
+ * - User-specific settings (language, timezone, etc.)
+ */
+
+/**
+ * Storage backend types
+ */
+type StorageBackend = 'localStorage' | 'indexedDB';
+
+/**
+ * Base preference key type for type safety
+ */
+type PreferenceKey = string;
+
+/**
+ * User preferences interface
+ * Extend this interface to add custom preference types
+ */
+export interface UserPreferences {
+  // Theme preferences
+  theme?: 'light' | 'dark';
+  colorConfig?: {
+    primaryHue?: number;
+    primarySaturation?: number;
+    primaryLightness?: number;
+    secondaryHue?: number;
+    secondarySaturation?: number;
+    secondaryLightness?: number;
+    accentHue?: number;
+    accentSaturation?: number;
+    accentLightness?: number;
+    successHue?: number;
+    successSaturation?: number;
+    successLightness?: number;
+    warningHue?: number;
+    warningSaturation?: number;
+    warningLightness?: number;
+    errorHue?: number;
+    errorSaturation?: number;
+    errorLightness?: number;
+    infoHue?: number;
+    infoSaturation?: number;
+    infoLightness?: number;
+  };
+
+  // Layout preferences
+  layout?: {
+    leftSidebarWidth?: number;
+    rightSidebarWidth?: number;
+    bottomBarHeight?: number;
+    navbarCollapsed?: boolean;
+  };
+
+  // Component-specific preferences
+  components?: {
+    [componentName: string]: {
+      [key: string]: any;
+    };
+  };
+
+  // Custom user settings
+  custom?: {
+    [key: string]: any;
+  };
+}
+
+/**
+ * Storage configuration
+ */
+interface StorageConfig {
+  backend: StorageBackend;
+  prefix: string;
+  dbName?: string;
+  storeName?: string;
+}
+
+/**
+ * Default storage configuration
+ */
+const DEFAULT_CONFIG: StorageConfig = {
+  backend: 'localStorage',
+  prefix: 'hellboy-ds',
+  dbName: 'hellboy-ds-prefs',
+  storeName: 'preferences',
+};
+
+/**
+ * Current storage configuration
+ */
+let config: StorageConfig = { ...DEFAULT_CONFIG };
+
+/**
+ * Configure the preference storage system
+ * Call this once at app initialization if you need custom configuration
+ * 
+ * @param userConfig - Custom storage configuration
+ * 
+ * @example
+ * ```ts
+ * import { configurePreferences } from '@hellboy/ds';
+ * 
+ * configurePreferences({
+ *   backend: 'localStorage',
+ *   prefix: 'my-app'
+ * });
+ * ```
+ */
+export const configurePreferences = (userConfig: Partial<StorageConfig>): void => {
+  config = { ...config, ...userConfig };
+};
+
+/**
+ * Get full storage key with prefix
+ */
+const getStorageKey = (key: PreferenceKey): string => {
+  return `${config.prefix}:${key}`;
+};
+
+/**
+ * Check if localStorage is available
+ */
+const isLocalStorageAvailable = (): boolean => {
+  try {
+    const test = '__storage_test__';
+    localStorage.setItem(test, test);
+    localStorage.removeItem(test);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * IndexedDB helper (for future expansion)
+ * Currently a placeholder - localStorage is the primary backend
+ */
+class IndexedDBStore {
+  private db: IDBDatabase | null = null;
+
+  async init(): Promise<void> {
+    if (typeof window === 'undefined' || !window.indexedDB) {
+      throw new Error('IndexedDB not available');
+    }
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(config.dbName!, 1);
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve();
+      };
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains(config.storeName!)) {
+          db.createObjectStore(config.storeName!, { keyPath: 'key' });
+        }
+      };
+    });
+  }
+
+  async get(key: string): Promise<any> {
+    if (!this.db) await this.init();
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([config.storeName!], 'readonly');
+      const store = transaction.objectStore(config.storeName!);
+      const request = store.get(key);
+
+      request.onsuccess = () => resolve(request.result?.value);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async set(key: string, value: any): Promise<void> {
+    if (!this.db) await this.init();
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([config.storeName!], 'readwrite');
+      const store = transaction.objectStore(config.storeName!);
+      const request = store.put({ key, value });
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async remove(key: string): Promise<void> {
+    if (!this.db) await this.init();
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([config.storeName!], 'readwrite');
+      const store = transaction.objectStore(config.storeName!);
+      const request = store.delete(key);
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async clear(): Promise<void> {
+    if (!this.db) await this.init();
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([config.storeName!], 'readwrite');
+      const store = transaction.objectStore(config.storeName!);
+      const request = store.clear();
+
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+}
+
+/**
+ * Singleton IndexedDB instance
+ */
+const indexedDBStore = new IndexedDBStore();
+
+/**
+ * Get a preference value
+ * 
+ * @param key - Preference key
+ * @param defaultValue - Default value if preference doesn't exist
+ * @returns The preference value or default value
+ * 
+ * @example
+ * ```ts
+ * import { getPreference } from '@hellboy/ds';
+ * 
+ * const theme = getPreference('theme', 'light');
+ * const sidebarWidth = getPreference('layout.leftSidebarWidth', 280);
+ * ```
+ */
+export const getPreference = <T = any>(
+  key: PreferenceKey,
+  defaultValue?: T
+): T | undefined => {
+  try {
+    if (config.backend === 'localStorage' && isLocalStorageAvailable()) {
+      const stored = localStorage.getItem(getStorageKey(key));
+      if (stored !== null) {
+        return JSON.parse(stored) as T;
+      }
+    }
+    return defaultValue;
+  } catch (error) {
+    console.warn(`Failed to get preference "${key}":`, error);
+    return defaultValue;
+  }
+};
+
+/**
+ * Async version for IndexedDB (future use)
+ */
+export const getPreferenceAsync = async <T = any>(
+  key: PreferenceKey,
+  defaultValue?: T
+): Promise<T | undefined> => {
+  try {
+    if (config.backend === 'indexedDB') {
+      const value = await indexedDBStore.get(getStorageKey(key));
+      return value !== undefined ? value : defaultValue;
+    }
+    return getPreference(key, defaultValue);
+  } catch (error) {
+    console.warn(`Failed to get preference "${key}":`, error);
+    return defaultValue;
+  }
+};
+
+/**
+ * Set a preference value
+ * 
+ * @param key - Preference key
+ * @param value - Preference value to store
+ * 
+ * @example
+ * ```ts
+ * import { setPreference } from '@hellboy/ds';
+ * 
+ * setPreference('theme', 'dark');
+ * setPreference('layout.leftSidebarWidth', 320);
+ * ```
+ */
+export const setPreference = <T = any>(key: PreferenceKey, value: T): void => {
+  try {
+    if (config.backend === 'localStorage' && isLocalStorageAvailable()) {
+      localStorage.setItem(getStorageKey(key), JSON.stringify(value));
+    }
+  } catch (error) {
+    console.warn(`Failed to set preference "${key}":`, error);
+  }
+};
+
+/**
+ * Async version for IndexedDB (future use)
+ */
+export const setPreferenceAsync = async <T = any>(
+  key: PreferenceKey,
+  value: T
+): Promise<void> => {
+  try {
+    if (config.backend === 'indexedDB') {
+      await indexedDBStore.set(getStorageKey(key), value);
+    } else {
+      setPreference(key, value);
+    }
+  } catch (error) {
+    console.warn(`Failed to set preference "${key}":`, error);
+  }
+};
+
+/**
+ * Remove a preference
+ * 
+ * @param key - Preference key to remove
+ * 
+ * @example
+ * ```ts
+ * import { removePreference } from '@hellboy/ds';
+ * 
+ * removePreference('layout.leftSidebarWidth');
+ * ```
+ */
+export const removePreference = (key: PreferenceKey): void => {
+  try {
+    if (config.backend === 'localStorage' && isLocalStorageAvailable()) {
+      localStorage.removeItem(getStorageKey(key));
+    }
+  } catch (error) {
+    console.warn(`Failed to remove preference "${key}":`, error);
+  }
+};
+
+/**
+ * Async version for IndexedDB (future use)
+ */
+export const removePreferenceAsync = async (key: PreferenceKey): Promise<void> => {
+  try {
+    if (config.backend === 'indexedDB') {
+      await indexedDBStore.remove(getStorageKey(key));
+    } else {
+      removePreference(key);
+    }
+  } catch (error) {
+    console.warn(`Failed to remove preference "${key}":`, error);
+  }
+};
+
+/**
+ * Clear all preferences
+ * 
+ * @example
+ * ```ts
+ * import { clearPreferences } from '@hellboy/ds';
+ * 
+ * clearPreferences(); // Removes all hellboy-ds preferences
+ * ```
+ */
+export const clearPreferences = (): void => {
+  try {
+    if (config.backend === 'localStorage' && isLocalStorageAvailable()) {
+      const prefix = `${config.prefix}:`;
+      const keysToRemove: string[] = [];
+
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key?.startsWith(prefix)) {
+          keysToRemove.push(key);
+        }
+      }
+
+      keysToRemove.forEach(key => localStorage.removeItem(key));
+    }
+  } catch (error) {
+    console.warn('Failed to clear preferences:', error);
+  }
+};
+
+/**
+ * Async version for IndexedDB (future use)
+ */
+export const clearPreferencesAsync = async (): Promise<void> => {
+  try {
+    if (config.backend === 'indexedDB') {
+      await indexedDBStore.clear();
+    } else {
+      clearPreferences();
+    }
+  } catch (error) {
+    console.warn('Failed to clear preferences:', error);
+  }
+};
+
+/**
+ * Get all preferences as an object
+ * 
+ * @returns Object containing all stored preferences
+ * 
+ * @example
+ * ```ts
+ * import { getAllPreferences } from '@hellboy/ds';
+ * 
+ * const allPrefs = getAllPreferences();
+ * console.log(allPrefs);
+ * // { 'theme': 'dark', 'layout.leftSidebarWidth': 320, ... }
+ * ```
+ */
+export const getAllPreferences = (): Record<string, any> => {
+  const preferences: Record<string, any> = {};
+
+  try {
+    if (config.backend === 'localStorage' && isLocalStorageAvailable()) {
+      const prefix = `${config.prefix}:`;
+
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key?.startsWith(prefix)) {
+          const prefKey = key.substring(prefix.length);
+          const value = localStorage.getItem(key);
+          if (value !== null) {
+            try {
+              preferences[prefKey] = JSON.parse(value);
+            } catch {
+              preferences[prefKey] = value;
+            }
+          }
+        }
+      }
+    }
+  } catch (error) {
+    console.warn('Failed to get all preferences:', error);
+  }
+
+  return preferences;
+};
+
+/**
+ * Export preferences as JSON
+ * Useful for backup or migration
+ * 
+ * @returns JSON string of all preferences
+ * 
+ * @example
+ * ```ts
+ * import { exportPreferences } from '@hellboy/ds';
+ * 
+ * const json = exportPreferences();
+ * // Download or save to file
+ * const blob = new Blob([json], { type: 'application/json' });
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+export const exportPreferences = (): string => {
+  const prefs = getAllPreferences();
+  return JSON.stringify(prefs, null, 2);
+};
+
+/**
+ * Import preferences from JSON
+ * Useful for restoring from backup
+ * 
+ * @param json - JSON string of preferences to import
+ * @param merge - Whether to merge with existing preferences (default: false)
+ * 
+ * @example
+ * ```ts
+ * import { importPreferences } from '@hellboy/ds';
+ * 
+ * const json = '{"theme":"dark","layout.leftSidebarWidth":320}';
+ * importPreferences(json, true); // Merge with existing
+ * ```
+ */
+export const importPreferences = (json: string, merge: boolean = false): void => {
+  try {
+    const prefs = JSON.parse(json);
+
+    if (!merge) {
+      clearPreferences();
+    }
+
+    Object.entries(prefs).forEach(([key, value]) => {
+      setPreference(key, value);
+    });
+  } catch (error) {
+    console.warn('Failed to import preferences:', error);
+  }
+};
+
+/**
+ * Create a preference namespace for better organization
+ * Returns scoped get/set functions
+ * 
+ * @param namespace - Namespace prefix
+ * 
+ * @example
+ * ```ts
+ * import { createPreferenceNamespace } from '@hellboy/ds';
+ * 
+ * const layoutPrefs = createPreferenceNamespace('layout');
+ * layoutPrefs.set('sidebarWidth', 300);
+ * const width = layoutPrefs.get('sidebarWidth', 280);
+ * ```
+ */
+export const createPreferenceNamespace = (namespace: string) => {
+  const getKey = (key: string) => `${namespace}.${key}`;
+
+  return {
+    get: <T = any>(key: string, defaultValue?: T) =>
+      getPreference<T>(getKey(key), defaultValue),
+    set: <T = any>(key: string, value: T) =>
+      setPreference(getKey(key), value),
+    remove: (key: string) => removePreference(getKey(key)),
+    clear: () => {
+      const prefs = getAllPreferences();
+      const prefix = `${namespace}.`;
+      Object.keys(prefs)
+        .filter(key => key.startsWith(prefix))
+        .forEach(key => removePreference(key));
+    },
+  };
+};
+
+/**
+ * React hook for preference management (optional, for React users)
+ * Import this separately to avoid bundling React in non-React projects
+ * 
+ * Note: This is a reference implementation. For production use in React,
+ * consider creating a dedicated hook file with proper React imports.
+ * 
+ * @example
+ * ```tsx
+ * // In a React component
+ * import { useState, useEffect } from 'react';
+ * import { getPreference, setPreference } from '@hellboy/ds';
+ * 
+ * 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;
+ * }
+ * 
+ * // Usage
+ * function MyComponent() {
+ *   const [theme, setTheme] = usePreference('theme', 'light');
+ *   return <button onClick={() => setTheme('dark')}>Switch to Dark</button>;
+ * }
+ * ```
+ */

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,52 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  external: ['react', 'react-dom', '@ariakit/react'],
+  // Copiar arquivos CSS e outros assets
+  // Copiar `theme.css` para `dist/theme.css` para que consumidores
+  // possam carregá-lo diretamente no browser como fonte da verdade.
+  asset: [],
+  onSuccess: async () => {
+    const fs = await import('fs');
+    const path = await import('path');
+    // Generate theme.css from theme.json (source of truth)
+    try {
+      const jsonPath = path.resolve(__dirname, 'src/style/themes/theme.json');
+      const dest = path.resolve(__dirname, 'dist/theme.css');
+
+      let themeObj: any = null;
+      if (fs.existsSync && fs.existsSync(jsonPath)) {
+        const raw = await fs.promises.readFile(jsonPath, 'utf8');
+        themeObj = JSON.parse(raw);
+      }
+
+      if (themeObj) {
+        const css = `/**\n * Theme Configuration (generated from theme.json)\n * Generated during build from src/style/themes/theme.json\n */\n\n:root {\n  /* Primary Color */\n  --primary-hue: ${themeObj.primary.hue};\n  --primary-saturation: ${themeObj.primary.saturation}%;\n  --primary-lightness: ${themeObj.primary.lightness}%;\n  --primary-lightness-hover: ${themeObj.primary.hover}%;\n  --primary-lightness-active: ${themeObj.primary.active}%;\n  --primary-lightness-disabled: ${themeObj.primary.disabled}%;\n\n  /* Secondary Color */\n  --secondary-hue: ${themeObj.secondary.hue};\n  --secondary-saturation: ${themeObj.secondary.saturation}%;\n  --secondary-lightness: ${themeObj.secondary.lightness}%;\n  --secondary-lightness-hover: ${themeObj.secondary.hover}%;\n  --secondary-lightness-active: ${themeObj.secondary.active}%;\n  --secondary-lightness-disabled: ${themeObj.secondary.disabled}%;\n\n  /* Accent Color */\n  --accent-hue: ${themeObj.accent.hue};\n  --accent-saturation: ${themeObj.accent.saturation}%;\n  --accent-lightness: ${themeObj.accent.lightness}%;\n  --accent-lightness-hover: ${themeObj.accent.hover}%;\n  --accent-lightness-active: ${themeObj.accent.active}%;\n  --accent-lightness-disabled: ${themeObj.accent.disabled}%;\n\n  /* Status Colors */\n  --success-hue: ${themeObj.success.hue};\n  --success-saturation: ${themeObj.success.saturation}%;\n  --success-lightness: ${themeObj.success.lightness}%;\n  --success-lightness-hover: ${themeObj.success.hover}%;\n  --success-lightness-active: ${themeObj.success.active}%;\n\n  --warning-hue: ${themeObj.warning.hue};\n  --warning-saturation: ${themeObj.warning.saturation}%;\n  --warning-lightness: ${themeObj.warning.lightness}%;\n  --warning-lightness-hover: ${themeObj.warning.hover}%;\n  --warning-lightness-active: ${themeObj.warning.active}%;\n\n  --error-hue: ${themeObj.error.hue};\n  --error-saturation: ${themeObj.error.saturation}%;\n  --error-lightness: ${themeObj.error.lightness}%;\n  --error-lightness-hover: ${themeObj.error.hover}%;\n  --error-lightness-active: ${themeObj.error.active}%;\n\n  --info-hue: ${themeObj.info.hue};\n  --info-saturation: ${themeObj.info.saturation}%;\n  --info-lightness: ${themeObj.info.lightness}%;\n  --info-lightness-hover: ${themeObj.info.hover}%;\n  --info-lightness-active: ${themeObj.info.active}%;\n}\n`;
+
+        await fs.promises.writeFile(dest, css, 'utf8');
+        console.log('✓ Generated dist/theme.css from theme.json');
+
+        // Also copy into web/public if exists
+        const webPublicDest = path.resolve(__dirname, '..', 'web', 'public', 'theme.css');
+        const webPublicDir = path.dirname(webPublicDest);
+        if (fs.existsSync && fs.existsSync(webPublicDir)) {
+          await fs.promises.writeFile(webPublicDest, css, 'utf8');
+          console.log('✓ Wrote theme.css to ../web/public/theme.css');
+        } else {
+          console.log('→ ../web/public not found — skipped writing theme.css to web public');
+        }
+      } else {
+        console.warn('! theme.json not found; skipping theme generation');
+      }
+    } catch (err) {
+      console.warn('! Could not generate theme.css from theme.json:', err);
+    }
+
+    console.log('✓ Build completo!');
+  },
+});