@hellboy/ds 0.1.3 → 0.2.7

package/src/utils/user-preferences.ts

@@ -1,577 +0,0 @@
-/**
- * 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

@@ -1,25 +0,0 @@
-{
-  "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

@@ -1,52 +0,0 @@
-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!');
-  },
-});