@miozu/jera 0.0.2 → 0.4.2

package/src/utils/reactive.svelte.js

@@ -0,0 +1,328 @@
+/**
+ * Reactive State Utilities for Svelte 5
+ *
+ * Advanced patterns for creating shareable, reactive state.
+ * Uses Svelte 5 runes ($state, $derived, $effect) internally.
+ */
+
+/**
+ * Create a reactive store-like object with Svelte 5 runes
+ * Unlike stores, these work seamlessly with runes and don't need $ prefix
+ *
+ * @template T
+ * @param {T} initial
+ * @returns {{ value: T, set: (v: T) => void, update: (fn: (v: T) => T) => void }}
+ *
+ * @example
+ * const count = createReactive(0);
+ * count.value; // read
+ * count.set(5); // write
+ * count.update(n => n + 1); // update
+ */
+export function createReactive(initial) {
+  let value = $state(initial);
+
+  return {
+    get value() {
+      return value;
+    },
+    set value(v) {
+      value = v;
+    },
+    set(v) {
+      value = v;
+    },
+    update(fn) {
+      value = fn(value);
+    }
+  };
+}
+
+/**
+ * Create a derived reactive value
+ *
+ * @template T
+ * @param {() => T} fn
+ * @returns {{ readonly value: T }}
+ */
+export function createDerived(fn) {
+  const value = $derived.by(fn);
+
+  return {
+    get value() {
+      return value;
+    }
+  };
+}
+
+/**
+ * Theme Reactive State Class (Singleton Pattern)
+ *
+ * Manages theme state with persistence and SSR support.
+ * Uses singleton pattern for global app-level state.
+ *
+ * Storage key: 'miozu-theme'
+ * Data-theme values: 'miozu-dark' | 'miozu-light'
+ *
+ * @example
+ * import { getTheme } from '@miozu/jera';
+ * const theme = getTheme();
+ * theme.init(); // Call once in root layout onMount
+ * theme.toggle(); // Toggle dark/light
+ * theme.set('system'); // Use system preference
+ */
+export class ThemeState {
+  /** @type {'light' | 'dark' | 'system'} */
+  current = $state('system');
+
+  /** @type {'light' | 'dark'} */
+  resolved = $derived.by(() => this.#resolveTheme());
+
+  /** @type {'miozu-light' | 'miozu-dark'} */
+  dataTheme = $derived.by(() => this.resolved === 'dark' ? 'miozu-dark' : 'miozu-light');
+
+  /**
+   * Alias for dataTheme - backwards compatibility
+   * @type {'miozu-light' | 'miozu-dark'}
+   */
+  currentTheme = $derived.by(() => this.dataTheme);
+
+  /** @type {boolean} */
+  isDark = $derived.by(() => this.resolved === 'dark');
+
+  /** @type {boolean} */
+  isLight = $derived.by(() => this.resolved === 'light');
+
+  /** @type {boolean} */
+  #initialized = false;
+
+  /** @type {MediaQueryList | null} */
+  #mediaQuery = null;
+
+  /** @type {(() => void) | null} */
+  #mediaQueryHandler = null;
+
+  /**
+   * Parse theme from cookie string (for SSR)
+   * @param {string | null} cookieString - Raw cookie header
+   * @returns {'miozu-light' | 'miozu-dark'} - Theme value for data-theme attribute
+   */
+  static getThemeFromCookieString(cookieString) {
+    if (!cookieString) return 'miozu-dark';
+
+    const match = cookieString.match(/miozu-theme=([^;]+)/);
+    const preference = match ? match[1] : null;
+
+    if (preference === 'light') return 'miozu-light';
+    if (preference === 'dark') return 'miozu-dark';
+    // 'system' or invalid - default to dark
+    return 'miozu-dark';
+  }
+
+  constructor(initial = 'system') {
+    this.current = initial;
+  }
+
+  #resolveTheme() {
+    if (this.current === 'system') {
+      // SSR-safe: default to dark if no window (miozu default)
+      if (typeof window === 'undefined') return 'dark';
+      return this.#mediaQuery?.matches ? 'dark' : 'light';
+    }
+    return this.current;
+  }
+
+  /**
+   * Initialize theme - call once in root layout onMount
+   * Loads from storage and sets up system preference listener
+   */
+  init() {
+    if (typeof window === 'undefined') return;
+    if (this.#initialized) return; // Prevent double init
+
+    // Load from storage
+    const stored = localStorage.getItem('miozu-theme');
+    if (stored && ['light', 'dark', 'system'].includes(stored)) {
+      this.current = stored;
+    }
+
+    // Setup media query listener for system preference
+    this.#mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    this.#mediaQueryHandler = () => {
+      // Force re-resolution when system preference changes
+      if (this.current === 'system') {
+        this.#apply();
+      }
+    };
+    this.#mediaQuery.addEventListener('change', this.#mediaQueryHandler);
+
+    this.#initialized = true;
+    this.#apply();
+  }
+
+  /**
+   * Cleanup media query listener
+   * Call in onDestroy if needed (usually not necessary for singleton)
+   */
+  cleanup() {
+    if (this.#mediaQuery && this.#mediaQueryHandler) {
+      this.#mediaQuery.removeEventListener('change', this.#mediaQueryHandler);
+      this.#mediaQueryHandler = null;
+    }
+    this.#initialized = false;
+  }
+
+  /**
+   * Sync state with current DOM attribute (for hydration)
+   * Call after SSR to ensure state matches what app.html set
+   */
+  sync() {
+    if (typeof document === 'undefined') return;
+
+    const domTheme = document.documentElement.getAttribute('data-theme');
+    if (domTheme === 'miozu-dark') {
+      this.current = 'dark';
+    } else if (domTheme === 'miozu-light') {
+      this.current = 'light';
+    }
+  }
+
+  /**
+   * Set theme preference and persist
+   * @param {'light' | 'dark' | 'system'} theme
+   */
+  set(theme) {
+    if (!['light', 'dark', 'system'].includes(theme)) {
+      console.warn(`Invalid theme: ${theme}`);
+      return;
+    }
+    this.current = theme;
+    this.#persist();
+    this.#apply();
+  }
+
+  /**
+   * Toggle between light and dark (skips system)
+   */
+  toggle() {
+    this.set(this.resolved === 'light' ? 'dark' : 'light');
+  }
+
+  /**
+   * Persist to localStorage and cookie
+   */
+  #persist() {
+    if (typeof window === 'undefined') return;
+    localStorage.setItem('miozu-theme', this.current);
+    document.cookie = `miozu-theme=${this.current};path=/;max-age=31536000;SameSite=Lax`;
+  }
+
+  /**
+   * Apply theme to document
+   */
+  #apply() {
+    if (typeof document === 'undefined') return;
+    document.documentElement.setAttribute('data-theme', this.dataTheme);
+    document.documentElement.style.colorScheme = this.resolved;
+  }
+}
+
+// ============================================
+// SINGLETON INSTANCE
+// ============================================
+
+/** @type {ThemeState | null} */
+let themeInstance = null;
+
+/**
+ * Get the global theme singleton
+ * Creates instance on first call (lazy initialization)
+ *
+ * @param {'light' | 'dark' | 'system'} [initial] - Initial theme (only used on first call)
+ * @returns {ThemeState}
+ *
+ * @example
+ * // In root +layout.svelte
+ * import { getTheme } from '@miozu/jera';
+ * const theme = getTheme();
+ * onMount(() => theme.init());
+ *
+ * // Anywhere else
+ * import { getTheme } from '@miozu/jera';
+ * const theme = getTheme();
+ * theme.toggle();
+ */
+export function getTheme(initial = 'system') {
+  if (!themeInstance) {
+    themeInstance = new ThemeState(initial);
+  }
+  return themeInstance;
+}
+
+/**
+ * Reset theme singleton (for testing)
+ */
+export function resetTheme() {
+  if (themeInstance) {
+    themeInstance.cleanup();
+    themeInstance = null;
+  }
+}
+
+/**
+ * Component State Factory
+ *
+ * Creates encapsulated component state with derived values.
+ * Pattern for complex components like Select, Combobox, etc.
+ *
+ * @template T
+ * @param {T} initialState
+ * @param {(state: T) => Record<string, any>} [derivedFn]
+ */
+export function createComponentState(initialState, derivedFn) {
+  const state = $state(initialState);
+
+  // $derived.by tracks dependencies inside the function
+  const deriveFn = derivedFn || (() => ({}));
+  const derived = $derived.by(() => deriveFn(state));
+
+  return {
+    get state() {
+      return state;
+    },
+    set state(v) {
+      Object.assign(state, v);
+    },
+    get derived() {
+      return derived;
+    },
+    /**
+     * Patch state partially
+     * @param {Partial<T>} patch
+     */
+    patch(patch) {
+      Object.assign(state, patch);
+    },
+    /**
+     * Reset to initial state
+     */
+    reset() {
+      Object.assign(state, initialState);
+    }
+  };
+}
+
+/**
+ * Create a unique ID generator for accessibility
+ * @param {string} [prefix]
+ * @returns {() => string}
+ */
+export function createIdGenerator(prefix = 'jera') {
+  let counter = 0;
+  return () => `${prefix}-${++counter}-${Math.random().toString(36).slice(2, 7)}`;
+}
+
+/**
+ * Shared ID generator instance
+ */
+export const generateId = createIdGenerator();

package/src/utils/sidebar.svelte.js

@@ -0,0 +1,211 @@
+/**
+ * Sidebar State Management
+ *
+ * Provides reactive state management for sidebar components.
+ * Uses Svelte 5 runes for fine-grained reactivity.
+ *
+ * @example
+ * const sidebar = createSidebarState({ persistKey: 'my-sidebar' });
+ *
+ * // In component
+ * sidebar.toggle();
+ * console.log(sidebar.collapsed); // true/false
+ */
+
+/**
+ * Create a reactive sidebar state manager
+ *
+ * @param {Object} options
+ * @param {boolean} [options.collapsed=false] - Initial collapsed state
+ * @param {string|null} [options.persistKey=null] - localStorage key for persistence
+ * @returns {Object} Sidebar state object with reactive properties and methods
+ */
+export function createSidebarState(options = {}) {
+  const { collapsed: initial = false, persistKey = null } = options;
+
+  // Core state
+  let _collapsed = $state(initial);
+  let _expandedGroups = $state(new Set());
+  let _hoverPopover = $state({
+    item: null,
+    position: { top: 0, left: 0 }
+  });
+  let _hoverTimeout = null;
+
+  // Load from localStorage on init (client-side only)
+  if (persistKey && typeof localStorage !== 'undefined') {
+    try {
+      const saved = localStorage.getItem(persistKey);
+      if (saved !== null) {
+        _collapsed = saved === 'true';
+      }
+
+      const savedGroups = localStorage.getItem(`${persistKey}-groups`);
+      if (savedGroups) {
+        _expandedGroups = new Set(JSON.parse(savedGroups));
+      }
+    } catch (e) {
+      // Ignore localStorage errors
+    }
+  }
+
+  // Persist to localStorage when state changes
+  function persist() {
+    if (persistKey && typeof localStorage !== 'undefined') {
+      try {
+        localStorage.setItem(persistKey, String(_collapsed));
+        localStorage.setItem(`${persistKey}-groups`, JSON.stringify([..._expandedGroups]));
+      } catch (e) {
+        // Ignore localStorage errors
+      }
+    }
+  }
+
+  return {
+    // Collapsed state
+    get collapsed() {
+      return _collapsed;
+    },
+    set collapsed(value) {
+      _collapsed = value;
+      persist();
+    },
+
+    /**
+     * Toggle collapsed state
+     */
+    toggle() {
+      _collapsed = !_collapsed;
+      persist();
+    },
+
+    /**
+     * Expand the sidebar
+     */
+    expand() {
+      _collapsed = false;
+      persist();
+    },
+
+    /**
+     * Collapse the sidebar
+     */
+    collapse() {
+      _collapsed = true;
+      persist();
+    },
+
+    // Group expansion
+    get expandedGroups() {
+      return _expandedGroups;
+    },
+
+    /**
+     * Check if a group is expanded
+     * @param {string} groupId
+     * @returns {boolean}
+     */
+    isGroupExpanded(groupId) {
+      return _expandedGroups.has(groupId);
+    },
+
+    /**
+     * Toggle group expansion
+     * @param {string} groupId
+     */
+    toggleGroup(groupId) {
+      if (_expandedGroups.has(groupId)) {
+        _expandedGroups = new Set([..._expandedGroups].filter(id => id !== groupId));
+      } else {
+        _expandedGroups = new Set([..._expandedGroups, groupId]);
+      }
+      persist();
+    },
+
+    /**
+     * Expand a group
+     * @param {string} groupId
+     */
+    expandGroup(groupId) {
+      if (!_expandedGroups.has(groupId)) {
+        _expandedGroups = new Set([..._expandedGroups, groupId]);
+        persist();
+      }
+    },
+
+    /**
+     * Collapse a group
+     * @param {string} groupId
+     */
+    collapseGroup(groupId) {
+      if (_expandedGroups.has(groupId)) {
+        _expandedGroups = new Set([..._expandedGroups].filter(id => id !== groupId));
+        persist();
+      }
+    },
+
+    // Hover popover state
+    get hoverPopover() {
+      return _hoverPopover;
+    },
+
+    /**
+     * Show hover popover for an item
+     * @param {string} itemId
+     * @param {{top: number, left: number}} position
+     */
+    showPopover(itemId, position) {
+      if (!_collapsed) return;
+
+      if (_hoverTimeout) {
+        clearTimeout(_hoverTimeout);
+        _hoverTimeout = null;
+      }
+
+      _hoverPopover = {
+        item: itemId,
+        position
+      };
+    },
+
+    /**
+     * Hide hover popover with delay
+     * @param {number} [delay=150]
+     */
+    hidePopover(delay = 150) {
+      if (_hoverTimeout) {
+        clearTimeout(_hoverTimeout);
+      }
+
+      _hoverTimeout = setTimeout(() => {
+        _hoverPopover = { item: null, position: { top: 0, left: 0 } };
+      }, delay);
+    },
+
+    /**
+     * Cancel pending popover hide
+     */
+    keepPopoverOpen() {
+      if (_hoverTimeout) {
+        clearTimeout(_hoverTimeout);
+        _hoverTimeout = null;
+      }
+    },
+
+    /**
+     * Immediately hide popover
+     */
+    hidePopoverImmediate() {
+      if (_hoverTimeout) {
+        clearTimeout(_hoverTimeout);
+        _hoverTimeout = null;
+      }
+      _hoverPopover = { item: null, position: { top: 0, left: 0 } };
+    }
+  };
+}
+
+/**
+ * Sidebar context key for Svelte context API
+ */
+export const SIDEBAR_CONTEXT_KEY = 'sidebar';

package/jera.js

@@ -1,135 +0,0 @@
-#!/usr/bin/env node
-
-import { Command } from 'commander';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// Find the components directory relative to the package
-function findComponentsDir() {
-  // Try to locate the components directory
-  const possiblePaths = [
-    // When running from the installed package
-    path.join(__dirname, 'src', 'components'),
-    // When running from the project root
-    path.join(__dirname, 'components'),
-    // When running from a cloned repo
-    path.join(__dirname, '..', 'src', 'components')
-  ];
-
-  for (const dir of possiblePaths) {
-    if (fs.existsSync(dir)) {
-      return dir;
-    }
-  }
-
-  // If components directory not found, return null
-  return null;
-}
-
-const COMPONENTS_DIR = findComponentsDir();
-
-// List available components in the components directory
-function listAvailableComponents() {
-  if (!COMPONENTS_DIR) {
-    return [];
-  }
-
-  try {
-    return fs.readdirSync(COMPONENTS_DIR)
-      .filter(file => file.endsWith('.svelte'))
-      .map(file => file.replace('.svelte', ''));
-  } catch (error) {
-    console.error('Error reading components directory:', error);
-    return [];
-  }
-}
-
-const program = new Command();
-
-program
-  .name('jera')
-  .description('Install Jera components to your project')
-  .version('0.0.1');
-
-program
-  .command('list')
-  .description('List all available components')
-  .action(() => {
-    const components = listAvailableComponents();
-
-    if (components.length === 0) {
-      console.log('No components found.');
-      return;
-    }
-
-    console.log('Available components:');
-    components.forEach(comp => console.log(`- ${comp}`));
-  });
-
-program
-  .command('add')
-  .description('Add a component to your project')
-  .argument('<component>', 'Component to add (e.g. Input)')
-  .option('-d, --dir <directory>', 'Target directory', 'src/lib/components')
-  .action((component, options) => {
-    console.log(`Adding ${component} to ${options.dir}...`);
-
-    const componentFile = component.endsWith('.svelte')
-      ? component
-      : `${component}.svelte`;
-
-    // Check if components directory exists
-    if (!COMPONENTS_DIR) {
-      console.error('Error: Components directory not found.');
-      console.error('This could happen if you\'re running the CLI in development mode');
-      console.error('or if the package structure has changed.');
-      return;
-    }
-
-    // Check if component exists
-    const sourceComponentPath = path.join(COMPONENTS_DIR, componentFile);
-    if (!fs.existsSync(sourceComponentPath)) {
-      console.error(`Error: Component "${component}" not found.`);
-      console.error('Available components:');
-      listAvailableComponents().forEach(comp => console.error(`- ${comp}`));
-      return;
-    }
-
-    // Create target directory if it doesn't exist
-    const targetDir = path.resolve(options.dir);
-    if (!fs.existsSync(targetDir)) {
-      fs.mkdirSync(targetDir, { recursive: true });
-    }
-
-    // Copy the component file
-    const componentContent = fs.readFileSync(sourceComponentPath, 'utf-8');
-    fs.writeFileSync(path.join(targetDir, componentFile), componentContent);
-
-    console.log(`Component ${component} added to ${options.dir}`);
-    console.log('\nUsage:');
-    console.log('\nNOTE: This component uses the Miozu theme.');
-    console.log('Make sure you have installed @miozu/js-theme and configured it in your Tailwind config.');
-  });
-
-// Add init command to set up the repository structure
-program
-  .command('init')
-  .description('Initialize a new project with Jera components')
-  .action(() => {
-    console.log('Initializing Jera components...');
-
-    const componentsDir = path.resolve('src/lib/components');
-
-    if (!fs.existsSync(componentsDir)) {
-      fs.mkdirSync(componentsDir, { recursive: true });
-    }
-
-    console.log('Project initialized! You can now add components with:');
-    console.log('  jera add <component>');
-  });
-
-program.parse();