@miozu/jera 0.3.0 → 0.4.2

package/src/utils/navigation.svelte.js

@@ -0,0 +1,423 @@
+/**
+ * NavigationState - Enterprise-grade reactive state management for navigation
+ *
+ * Provides centralized state management for complex navigation scenarios including:
+ * - Multi-level recursive navigation
+ * - Search and filtering across all items
+ * - Expansion state management
+ * - Active state detection
+ * - Breadcrumb generation
+ * - Permission-based visibility
+ *
+ * @example
+ * const nav = new NavigationState({
+ *   items: navigationConfig,
+ *   persistKey: 'my-app-nav',
+ *   searchable: true,
+ *   recursive: true
+ * });
+ */
+
+import { browser } from '$app/environment';
+
+export class NavigationState {
+  // Core reactive state
+  items = $state([]);
+  searchQuery = $state('');
+  expandedSections = $state({});
+  expandedItems = $state({});
+  activeItem = $state(null);
+  activePath = $state([]);
+
+  // Configuration
+  config = $state({
+    persistKey: null,
+    searchable: true,
+    recursive: true,
+    maxDepth: 10,
+    autoExpand: false,
+    caseSensitiveSearch: false
+  });
+
+  // Computed properties
+  filteredItems = $derived.by(() => this.#filterItems(this.items, this.searchQuery));
+  breadcrumbs = $derived.by(() => this.#generateBreadcrumbs(this.activeItem));
+  totalItemCount = $derived.by(() => this.#countItems(this.items));
+  visibleItemCount = $derived.by(() => this.#countItems(this.filteredItems));
+
+  constructor(options = {}) {
+    // Apply configuration
+    this.config = { ...this.config, ...options };
+
+    if (options.items) {
+      this.items = this.#normalizeItems(options.items);
+    }
+
+    // Load persisted state
+    if (this.config.persistKey && browser) {
+      this.#loadPersistedState();
+    }
+
+    // Auto-save state when it changes
+    if (this.config.persistKey && browser) {
+      $effect(() => {
+        this.#savePersistedState();
+      });
+    }
+  }
+
+  /**
+   * Update navigation items with intelligent merging
+   */
+  setItems(items) {
+    this.items = this.#normalizeItems(items);
+
+    // Auto-expand if configured
+    if (this.config.autoExpand) {
+      this.#autoExpandItems();
+    }
+  }
+
+  /**
+   * Set active item by ID or path
+   */
+  setActive(identifier, shouldExpand = true) {
+    const item = typeof identifier === 'string'
+      ? this.#findItemById(identifier)
+      : identifier;
+
+    if (item) {
+      this.activeItem = item;
+      this.activePath = this.#getItemPath(item);
+
+      if (shouldExpand) {
+        this.#expandToItem(item);
+      }
+    }
+  }
+
+  /**
+   * Search navigation items
+   */
+  search(query) {
+    this.searchQuery = query;
+
+    // Auto-expand search results
+    if (query && this.config.autoExpand) {
+      this.#expandSearchResults();
+    }
+  }
+
+  /**
+   * Clear search and collapse expanded results
+   */
+  clearSearch() {
+    this.searchQuery = '';
+  }
+
+  /**
+   * Toggle section expansion
+   */
+  toggleSection(sectionId) {
+    this.expandedSections[sectionId] = !this.expandedSections[sectionId];
+  }
+
+  /**
+   * Toggle item expansion (for recursive items)
+   */
+  toggleItem(itemId) {
+    this.expandedItems[itemId] = !this.expandedItems[itemId];
+  }
+
+  /**
+   * Expand all sections and items
+   */
+  expandAll() {
+    this.#walkItems(this.items, (item) => {
+      if (item.children?.length > 0) {
+        this.expandedItems[item.id] = true;
+      }
+    });
+
+    // Expand all sections
+    Object.keys(this.expandedSections).forEach(key => {
+      this.expandedSections[key] = true;
+    });
+  }
+
+  /**
+   * Collapse all sections and items
+   */
+  collapseAll() {
+    this.expandedItems = {};
+    Object.keys(this.expandedSections).forEach(key => {
+      this.expandedSections[key] = false;
+    });
+  }
+
+  /**
+   * Get navigation item by ID
+   */
+  getItem(id) {
+    return this.#findItemById(id);
+  }
+
+  /**
+   * Get all children of an item
+   */
+  getChildren(itemId) {
+    const item = this.#findItemById(itemId);
+    return item?.children || [];
+  }
+
+  /**
+   * Get parent of an item
+   */
+  getParent(itemId) {
+    return this.#findParentItem(itemId);
+  }
+
+  /**
+   * Get path to root for an item
+   */
+  getPath(itemId) {
+    const item = this.#findItemById(itemId);
+    return item ? this.#getItemPath(item) : [];
+  }
+
+  /**
+   * Check if item is visible based on permissions
+   */
+  isVisible(item) {
+    if (!item.permissions) return true;
+
+    // Override in subclass or provide permissions checker
+    return this.config.permissionChecker
+      ? this.config.permissionChecker(item.permissions)
+      : true;
+  }
+
+  /**
+   * Check if item is active
+   */
+  isActive(item) {
+    return this.activeItem?.id === item.id;
+  }
+
+  /**
+   * Check if item is in active path
+   */
+  isInActivePath(item) {
+    return this.activePath.some(pathItem => pathItem.id === item.id);
+  }
+
+  /**
+   * Check if section is expanded
+   */
+  isSectionExpanded(sectionId) {
+    return this.expandedSections[sectionId] ?? false;
+  }
+
+  /**
+   * Check if item is expanded
+   */
+  isItemExpanded(itemId) {
+    return this.expandedItems[itemId] ?? false;
+  }
+
+  // Private methods
+  #normalizeItems(items) {
+    const normalized = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const normalizedItem = {
+        id: item.id || `item-${i}`,
+        label: item.label || '',
+        href: item.href || null,
+        icon: item.icon || null,
+        badge: item.badge || null,
+        children: item.children ? this.#normalizeItems(item.children) : [],
+        permissions: item.permissions || null,
+        metadata: item.metadata || {},
+        depth: item.depth || 0,
+        parent: item.parent || null,
+        ...item
+      };
+
+      // Set parent references for children
+      normalizedItem.children.forEach(child => {
+        child.parent = normalizedItem.id;
+        child.depth = normalizedItem.depth + 1;
+      });
+
+      normalized.push(normalizedItem);
+    }
+
+    return normalized;
+  }
+
+  #filterItems(items, query) {
+    if (!query) return items;
+
+    const filtered = [];
+    const searchLower = this.config.caseSensitiveSearch ? query : query.toLowerCase();
+
+    for (const item of items) {
+      const matches = this.#itemMatches(item, searchLower);
+      const filteredChildren = this.#filterItems(item.children || [], query);
+
+      if (matches || filteredChildren.length > 0) {
+        filtered.push({
+          ...item,
+          children: filteredChildren,
+          _matchesSearch: matches
+        });
+      }
+    }
+
+    return filtered;
+  }
+
+  #itemMatches(item, searchQuery) {
+    const searchFields = [
+      item.label,
+      item.description,
+      item.metadata?.tags?.join(' '),
+      item.metadata?.keywords?.join(' ')
+    ].filter(Boolean);
+
+    const searchText = this.config.caseSensitiveSearch
+      ? searchFields.join(' ')
+      : searchFields.join(' ').toLowerCase();
+
+    return searchText.includes(searchQuery);
+  }
+
+  #findItemById(id, items = this.items) {
+    for (const item of items) {
+      if (item.id === id) return item;
+
+      if (item.children) {
+        const found = this.#findItemById(id, item.children);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  #findParentItem(itemId, items = this.items, parent = null) {
+    for (const item of items) {
+      if (item.id === itemId) return parent;
+
+      if (item.children) {
+        const found = this.#findParentItem(itemId, item.children, item);
+        if (found) return found;
+      }
+    }
+    return null;
+  }
+
+  #getItemPath(item) {
+    const path = [];
+    let current = item;
+
+    while (current) {
+      path.unshift(current);
+      current = current.parent ? this.#findItemById(current.parent) : null;
+    }
+
+    return path;
+  }
+
+  #expandToItem(item) {
+    const path = this.#getItemPath(item);
+
+    path.forEach(pathItem => {
+      if (pathItem.parent) {
+        this.expandedItems[pathItem.parent] = true;
+      }
+    });
+  }
+
+  #expandSearchResults() {
+    this.#walkItems(this.filteredItems, (item) => {
+      if (item._matchesSearch && item.parent) {
+        this.expandedItems[item.parent] = true;
+      }
+    });
+  }
+
+  #autoExpandItems() {
+    this.#walkItems(this.items, (item) => {
+      if (item.children?.length > 0) {
+        this.expandedItems[item.id] = true;
+      }
+    });
+  }
+
+  #walkItems(items, callback) {
+    for (const item of items) {
+      callback(item);
+      if (item.children) {
+        this.#walkItems(item.children, callback);
+      }
+    }
+  }
+
+  #countItems(items) {
+    let count = 0;
+    this.#walkItems(items, () => count++);
+    return count;
+  }
+
+  #generateBreadcrumbs(activeItem) {
+    if (!activeItem) return [];
+    return this.#getItemPath(activeItem);
+  }
+
+  #loadPersistedState() {
+    try {
+      const saved = localStorage.getItem(this.config.persistKey);
+      if (saved) {
+        const state = JSON.parse(saved);
+        this.expandedSections = state.expandedSections || {};
+        this.expandedItems = state.expandedItems || {};
+        this.searchQuery = state.searchQuery || '';
+      }
+    } catch (error) {
+      console.warn('Failed to load navigation state:', error);
+    }
+  }
+
+  #savePersistedState() {
+    try {
+      const state = {
+        expandedSections: this.expandedSections,
+        expandedItems: this.expandedItems,
+        searchQuery: this.searchQuery
+      };
+      localStorage.setItem(this.config.persistKey, JSON.stringify(state));
+    } catch (error) {
+      console.warn('Failed to save navigation state:', error);
+    }
+  }
+}
+
+/**
+ * Create a navigation state instance with common defaults
+ */
+export function createNavigationState(options = {}) {
+  return new NavigationState({
+    searchable: true,
+    recursive: true,
+    maxDepth: 10,
+    autoExpand: false,
+    ...options
+  });
+}
+
+/**
+ * Navigation context key for Svelte context
+ */
+export const NAVIGATION_CONTEXT_KEY = 'navigation-state';

package/src/utils/reactive.svelte.js

@@ -5,8 +5,6 @@
  * Uses Svelte 5 runes ($state, $derived, $effect) internally.
  */
 
-import { getContext, setContext, onMount } from 'svelte';
-
 /**
  * Create a reactive store-like object with Svelte 5 runes
  * Unlike stores, these work seamlessly with runes and don't need $ prefix
@@ -58,15 +56,20 @@ export function createDerived(fn) {
 }
 
 /**
- * Theme Context Key
- */
-const THEME_KEY = Symbol('jera-theme');
-
-/**
- * Theme Reactive State Class
+ * Theme Reactive State Class (Singleton Pattern)
  *
  * Manages theme state with persistence and SSR support.
- * Uses class-based reactive state pattern.
+ * 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'} */
@@ -75,8 +78,23 @@ export class ThemeState {
   /** @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} */
-  #mounted = false;
+  isDark = $derived.by(() => this.resolved === 'dark');
+
+  /** @type {boolean} */
+  isLight = $derived.by(() => this.resolved === 'light');
+
+  /** @type {boolean} */
+  #initialized = false;
 
   /** @type {MediaQueryList | null} */
   #mediaQuery = null;
@@ -84,100 +102,171 @@ export class ThemeState {
   /** @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 light if no window
-      if (typeof window === 'undefined') return 'light';
+      // 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 in onMount
+   * 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('jera-theme');
+    const stored = localStorage.getItem('miozu-theme');
     if (stored && ['light', 'dark', 'system'].includes(stored)) {
       this.current = stored;
     }
 
-    // Setup media query listener
+    // Setup media query listener for system preference
     this.#mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
     this.#mediaQueryHandler = () => {
-      // Trigger re-resolution by reassigning
-      this.current = this.current;
+      // Force re-resolution when system preference changes
+      if (this.current === 'system') {
+        this.#apply();
+      }
     };
     this.#mediaQuery.addEventListener('change', this.#mediaQueryHandler);
 
-    this.#mounted = true;
+    this.#initialized = true;
     this.#apply();
   }
 
   /**
-   * Cleanup - call in onDestroy to prevent memory leaks
+   * 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.#mounted = false;
+    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 and persist
+   * Set theme preference and persist
    * @param {'light' | 'dark' | 'system'} theme
    */
   set(theme) {
-    this.current = theme;
-    if (typeof window !== 'undefined') {
-      localStorage.setItem('jera-theme', theme);
-      document.cookie = `jera-theme=${theme};path=/;max-age=31536000`;
+    if (!['light', 'dark', 'system'].includes(theme)) {
+      console.warn(`Invalid theme: ${theme}`);
+      return;
     }
+    this.current = theme;
+    this.#persist();
     this.#apply();
   }
 
   /**
-   * Toggle between light and dark
+   * 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.resolved);
+    document.documentElement.setAttribute('data-theme', this.dataTheme);
+    document.documentElement.style.colorScheme = this.resolved;
   }
 }
 
+// ============================================
+// SINGLETON INSTANCE
+// ============================================
+
+/** @type {ThemeState | null} */
+let themeInstance = null;
+
 /**
- * Create and provide theme context
- * @param {'light' | 'dark' | 'system'} [initial]
+ * 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 createThemeContext(initial = 'system') {
-  const theme = new ThemeState(initial);
-  setContext(THEME_KEY, theme);
-  return theme;
+export function getTheme(initial = 'system') {
+  if (!themeInstance) {
+    themeInstance = new ThemeState(initial);
+  }
+  return themeInstance;
 }
 
 /**
- * Get theme from context
- * @returns {ThemeState}
+ * Reset theme singleton (for testing)
  */
-export function getThemeContext() {
-  return getContext(THEME_KEY);
+export function resetTheme() {
+  if (themeInstance) {
+    themeInstance.cleanup();
+    themeInstance = null;
+  }
 }
 
 /**