@djangocfg/ui-nextjs 2.1.59 → 2.1.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.59",
+  "version": "2.1.60",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -58,8 +58,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.59",
-    "@djangocfg/ui-core": "^2.1.59",
+    "@djangocfg/api": "^2.1.60",
+    "@djangocfg/ui-core": "^2.1.60",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -106,7 +106,7 @@
     "vidstack": "next"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.59",
+    "@djangocfg/typescript-config": "^2.1.60",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

package/src/hooks/index.ts

@@ -9,7 +9,9 @@ export * from '@djangocfg/ui-core/hooks';
 
 // Storage hooks (browser localStorage/sessionStorage)
 export { useLocalStorage } from './useLocalStorage';
+export type { UseLocalStorageOptions } from './useLocalStorage';
 export { useSessionStorage } from './useSessionStorage';
+export type { UseSessionStorageOptions } from './useSessionStorage';
 
 // Theme hook (standalone, no provider required)
 export { useResolvedTheme } from './useResolvedTheme';

package/src/hooks/useLocalStorage.ts

@@ -3,7 +3,55 @@
 import { useEffect, useRef, useState } from 'react';
 
 /**
- * Simple localStorage hook with better error handling
+ * Storage wrapper format with metadata
+ * Used when TTL is specified
+ */
+interface StorageWrapper<T> {
+  _meta: {
+    createdAt: number;
+    ttl: number;
+  };
+  _value: T;
+}
+
+/**
+ * Options for useLocalStorage hook
+ */
+export interface UseLocalStorageOptions {
+  /**
+   * Time-to-live in milliseconds.
+   * After this time, value is considered expired and initialValue is returned.
+   * Data is automatically cleaned up on next read.
+   * @example 24 * 60 * 60 * 1000 // 24 hours
+   */
+  ttl?: number;
+}
+
+/**
+ * Check if data is in new wrapped format with _meta
+ */
+function isWrappedFormat<T>(data: unknown): data is StorageWrapper<T> {
+  return (
+    data !== null &&
+    typeof data === 'object' &&
+    '_meta' in data &&
+    '_value' in data &&
+    typeof (data as StorageWrapper<T>)._meta === 'object' &&
+    typeof (data as StorageWrapper<T>)._meta.createdAt === 'number'
+  );
+}
+
+/**
+ * Check if wrapped data is expired
+ */
+function isExpired<T>(wrapped: StorageWrapper<T>): boolean {
+  if (!wrapped._meta.ttl) return false;
+  const age = Date.now() - wrapped._meta.createdAt;
+  return age > wrapped._meta.ttl;
+}
+
+/**
+ * Simple localStorage hook with better error handling and optional TTL support
  *
  * IMPORTANT: To prevent hydration mismatch, this hook:
  * - Always returns initialValue on first render (same as SSR)
@@ -11,9 +59,25 @@ import { useEffect, useRef, useState } from 'react';
  *
  * @param key - Storage key
  * @param initialValue - Default value if key doesn't exist
+ * @param options - Optional configuration (ttl for auto-expiration)
  * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ *
+ * @example
+ * // Without TTL (backwards compatible)
+ * const [value, setValue] = useLocalStorage('key', 'default');
+ *
+ * @example
+ * // With TTL (24 hours)
+ * const [value, setValue] = useLocalStorage('key', 'default', {
+ *   ttl: 24 * 60 * 60 * 1000
+ * });
  */
-export function useLocalStorage<T>(key: string, initialValue: T) {
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T,
+  options?: UseLocalStorageOptions
+) {
+  const ttl = options?.ttl;
   // Always start with initialValue to match SSR
   const [storedValue, setStoredValue] = useState<T>(initialValue);
   const [isHydrated, setIsHydrated] = useState(false);
@@ -29,7 +93,23 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
       if (item !== null) {
         // Try to parse as JSON first, fallback to string
         try {
-          setStoredValue(JSON.parse(item));
+          const parsed = JSON.parse(item);
+
+          // Check if new format with _meta
+          if (isWrappedFormat<T>(parsed)) {
+            // Check TTL expiration
+            if (isExpired(parsed)) {
+              // Expired! Clean up and use initial value
+              window.localStorage.removeItem(key);
+              // Keep initialValue (already set)
+            } else {
+              // Not expired, extract value
+              setStoredValue(parsed._value);
+            }
+          } else {
+            // Old format (backwards compatible)
+            setStoredValue(parsed as T);
+          }
         } catch {
           // If JSON.parse fails, return as string
           setStoredValue(item as T);
@@ -101,18 +181,37 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
     }
   };
 
+  // Prepare data for storage (with or without TTL wrapper)
+  const prepareForStorage = (value: T): string => {
+    if (ttl) {
+      // Wrap with _meta for TTL support
+      const wrapped: StorageWrapper<T> = {
+        _meta: {
+          createdAt: Date.now(),
+          ttl,
+        },
+        _value: value,
+      };
+      return JSON.stringify(wrapped);
+    }
+    // Old format (no wrapper) - for strings, store directly
+    if (typeof value === 'string') {
+      return value;
+    }
+    return JSON.stringify(value);
+  };
+
   // Update localStorage when value changes
   const setValue = (value: T | ((val: T) => T)) => {
     try {
       const valueToStore = value instanceof Function ? value(storedValue) : value;
-      
+
       // Check data size before attempting to save
       if (!checkDataSize(valueToStore)) {
         console.warn(`Data size too large for key "${key}", removing key`);
         // Remove the key if data is too large
         try {
           window.localStorage.removeItem(key);
-          window.localStorage.removeItem(`${key}_timestamp`);
         } catch {
           // Ignore errors when removing
         }
@@ -120,45 +219,32 @@ export function useLocalStorage<T>(key: string, initialValue: T) {
         setStoredValue(valueToStore);
         return;
       }
-      
+
       setStoredValue(valueToStore);
 
       if (typeof window !== 'undefined') {
+        const dataToStore = prepareForStorage(valueToStore);
+
         // Try to set the value
         try {
-          // For strings, store directly without JSON.stringify
-          if (typeof valueToStore === 'string') {
-            window.localStorage.setItem(key, valueToStore);
-          } else {
-            window.localStorage.setItem(key, JSON.stringify(valueToStore));
-          }
+          window.localStorage.setItem(key, dataToStore);
         } catch (storageError: any) {
           // If quota exceeded, clear old data and try again
-          if (storageError.name === 'QuotaExceededError' || 
-              storageError.code === 22 || 
+          if (storageError.name === 'QuotaExceededError' ||
+              storageError.code === 22 ||
               storageError.message?.includes('quota')) {
             console.warn('localStorage quota exceeded, clearing old data...');
             clearOldData();
-            
+
             // Try again after clearing
             try {
-              // For strings, store directly without JSON.stringify
-              if (typeof valueToStore === 'string') {
-                window.localStorage.setItem(key, valueToStore);
-              } else {
-                window.localStorage.setItem(key, JSON.stringify(valueToStore));
-              }
+              window.localStorage.setItem(key, dataToStore);
             } catch (retryError) {
               console.error(`Failed to set localStorage key "${key}" after clearing old data:`, retryError);
               // If still fails, force clear all and try one more time
               try {
                 forceClearAll();
-                // For strings, store directly without JSON.stringify
-                if (typeof valueToStore === 'string') {
-                  window.localStorage.setItem(key, valueToStore);
-                } else {
-                  window.localStorage.setItem(key, JSON.stringify(valueToStore));
-                }
+                window.localStorage.setItem(key, dataToStore);
               } catch (finalError) {
                 console.error(`Failed to set localStorage key "${key}" after force clearing:`, finalError);
                 // If still fails, just update the state without localStorage

package/src/hooks/useSessionStorage.ts

@@ -3,12 +3,78 @@
 import { useState } from 'react';
 
 /**
- * Simple sessionStorage hook with better error handling
+ * Storage wrapper format with metadata
+ * Used when TTL is specified
+ */
+interface StorageWrapper<T> {
+  _meta: {
+    createdAt: number;
+    ttl: number;
+  };
+  _value: T;
+}
+
+/**
+ * Options for useSessionStorage hook
+ */
+export interface UseSessionStorageOptions {
+  /**
+   * Time-to-live in milliseconds.
+   * After this time, value is considered expired and initialValue is returned.
+   * Data is automatically cleaned up on next read.
+   * @example 24 * 60 * 60 * 1000 // 24 hours
+   */
+  ttl?: number;
+}
+
+/**
+ * Check if data is in new wrapped format with _meta
+ */
+function isWrappedFormat<T>(data: unknown): data is StorageWrapper<T> {
+  return (
+    data !== null &&
+    typeof data === 'object' &&
+    '_meta' in data &&
+    '_value' in data &&
+    typeof (data as StorageWrapper<T>)._meta === 'object' &&
+    typeof (data as StorageWrapper<T>)._meta.createdAt === 'number'
+  );
+}
+
+/**
+ * Check if wrapped data is expired
+ */
+function isExpired<T>(wrapped: StorageWrapper<T>): boolean {
+  if (!wrapped._meta.ttl) return false;
+  const age = Date.now() - wrapped._meta.createdAt;
+  return age > wrapped._meta.ttl;
+}
+
+/**
+ * Simple sessionStorage hook with better error handling and optional TTL support
+ *
  * @param key - Storage key
  * @param initialValue - Default value if key doesn't exist
+ * @param options - Optional configuration (ttl for auto-expiration)
  * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ *
+ * @example
+ * // Without TTL (backwards compatible)
+ * const [value, setValue] = useSessionStorage('key', 'default');
+ *
+ * @example
+ * // With TTL (1 hour)
+ * const [value, setValue] = useSessionStorage('key', 'default', {
+ *   ttl: 60 * 60 * 1000
+ * });
  */
-export function useSessionStorage<T>(key: string, initialValue: T) {
+export function useSessionStorage<T>(
+  key: string,
+  initialValue: T,
+  options?: UseSessionStorageOptions
+) {
+  const ttl = options?.ttl;
+
   // Get initial value from sessionStorage or use provided initialValue
   const [storedValue, setStoredValue] = useState<T>(() => {
     if (typeof window === 'undefined') {
@@ -17,7 +83,29 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
 
     try {
       const item = window.sessionStorage.getItem(key);
-      return item ? JSON.parse(item) : initialValue;
+      if (item === null) return initialValue;
+
+      try {
+        const parsed = JSON.parse(item);
+
+        // Check if new format with _meta
+        if (isWrappedFormat<T>(parsed)) {
+          // Check TTL expiration
+          if (isExpired(parsed)) {
+            // Expired! Clean up and use initial value
+            window.sessionStorage.removeItem(key);
+            return initialValue;
+          }
+          // Not expired, extract value
+          return parsed._value;
+        }
+
+        // Old format (backwards compatible)
+        return parsed as T;
+      } catch {
+        // If JSON.parse fails, return as string
+        return item as T;
+      }
     } catch (error) {
       console.error(`Error reading sessionStorage key "${key}":`, error);
       return initialValue;
@@ -30,13 +118,13 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
       const jsonString = JSON.stringify(data);
       const sizeInBytes = new Blob([jsonString]).size;
       const sizeInKB = sizeInBytes / 1024;
-      
+
       // Limit to 1MB per item
       if (sizeInKB > 1024) {
         console.warn(`Data size (${sizeInKB.toFixed(2)}KB) exceeds 1MB limit for key "${key}"`);
         return false;
       }
-      
+
       return true;
     } catch (error) {
       console.error(`Error checking data size for key "${key}":`, error);
@@ -47,16 +135,15 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
   // Clear old data when sessionStorage is full
   const clearOldData = () => {
     try {
-      const keys = Object.keys(sessionStorage).filter(key => key && typeof key === 'string');
+      const keys = Object.keys(sessionStorage).filter(k => k && typeof k === 'string');
       // Remove oldest items if we have more than 50 items
       if (keys.length > 50) {
         const itemsToRemove = Math.ceil(keys.length * 0.2);
         for (let i = 0; i < itemsToRemove; i++) {
           try {
-            const key = keys[i];
-            if (key) {
-              sessionStorage.removeItem(key);
-              sessionStorage.removeItem(`${key}_timestamp`);
+            const k = keys[i];
+            if (k) {
+              sessionStorage.removeItem(k);
             }
           } catch {
             // Ignore errors when removing items
@@ -72,9 +159,9 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
   const forceClearAll = () => {
     try {
       const keys = Object.keys(sessionStorage);
-      for (const key of keys) {
+      for (const k of keys) {
         try {
-          sessionStorage.removeItem(key);
+          sessionStorage.removeItem(k);
         } catch {
           // Ignore errors when removing items
         }
@@ -84,18 +171,37 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
     }
   };
 
+  // Prepare data for storage (with or without TTL wrapper)
+  const prepareForStorage = (value: T): string => {
+    if (ttl) {
+      // Wrap with _meta for TTL support
+      const wrapped: StorageWrapper<T> = {
+        _meta: {
+          createdAt: Date.now(),
+          ttl,
+        },
+        _value: value,
+      };
+      return JSON.stringify(wrapped);
+    }
+    // Old format (no wrapper) - for strings, store directly
+    if (typeof value === 'string') {
+      return value;
+    }
+    return JSON.stringify(value);
+  };
+
   // Update sessionStorage when value changes
   const setValue = (value: T | ((val: T) => T)) => {
     try {
       const valueToStore = value instanceof Function ? value(storedValue) : value;
-      
+
       // Check data size before attempting to save
       if (!checkDataSize(valueToStore)) {
         console.warn(`Data size too large for key "${key}", removing key`);
         // Remove the key if data is too large
         try {
           window.sessionStorage.removeItem(key);
-          window.sessionStorage.removeItem(`${key}_timestamp`);
         } catch {
           // Ignore errors when removing
         }
@@ -103,34 +209,32 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
         setStoredValue(valueToStore);
         return;
       }
-      
+
       setStoredValue(valueToStore);
 
       if (typeof window !== 'undefined') {
+        const dataToStore = prepareForStorage(valueToStore);
+
         // Try to set the value
         try {
-          window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
-          // Add timestamp for cleanup
-          window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+          window.sessionStorage.setItem(key, dataToStore);
         } catch (storageError: any) {
           // If quota exceeded, clear old data and try again
-          if (storageError.name === 'QuotaExceededError' || 
-              storageError.code === 22 || 
+          if (storageError.name === 'QuotaExceededError' ||
+              storageError.code === 22 ||
               storageError.message?.includes('quota')) {
             console.warn('sessionStorage quota exceeded, clearing old data...');
             clearOldData();
-            
+
             // Try again after clearing
             try {
-              window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
-              window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+              window.sessionStorage.setItem(key, dataToStore);
             } catch (retryError) {
               console.error(`Failed to set sessionStorage key "${key}" after clearing old data:`, retryError);
               // If still fails, force clear all and try one more time
               try {
                 forceClearAll();
-                window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
-                window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+                window.sessionStorage.setItem(key, dataToStore);
               } catch (finalError) {
                 console.error(`Failed to set sessionStorage key "${key}" after force clearing:`, finalError);
                 // If still fails, just update the state without sessionStorage
@@ -157,18 +261,16 @@ export function useSessionStorage<T>(key: string, initialValue: T) {
       if (typeof window !== 'undefined') {
         try {
           window.sessionStorage.removeItem(key);
-          window.sessionStorage.removeItem(`${key}_timestamp`);
         } catch (removeError: any) {
           // If removal fails due to quota, try to clear some data first
-          if (removeError.name === 'QuotaExceededError' || 
-              removeError.code === 22 || 
+          if (removeError.name === 'QuotaExceededError' ||
+              removeError.code === 22 ||
               removeError.message?.includes('quota')) {
             console.warn('sessionStorage quota exceeded during removal, clearing old data...');
             clearOldData();
-            
+
             try {
               window.sessionStorage.removeItem(key);
-              window.sessionStorage.removeItem(`${key}_timestamp`);
             } catch (retryError) {
               console.error(`Failed to remove sessionStorage key "${key}" after clearing:`, retryError);
               // If still fails, force clear all