@stacksjs/components 0.2.3

package/src/ui/stepper/README.md

@@ -0,0 +1,36 @@
+# Stepper Component
+
+A step-by-step progress indicator for multi-step processes.
+
+## Installation
+
+```bash
+bun add @stacksjs/components
+```
+
+## Usage
+
+```stx
+<script>
+export let currentStep = 0
+
+export function handleStepClick(step) {
+  currentStep = step
+}
+</script>
+
+@component('Stepper', { currentStep })
+  @component('StepperStep', { stepNumber: 0, currentStep, label: 'Account', onClick: handleStepClick })
+  @component('StepperStep', { stepNumber: 1, currentStep, label: 'Profile', onClick: handleStepClick })
+  @component('StepperStep', { stepNumber: 2, currentStep, label: 'Confirmation', onClick: handleStepClick })
+@endcomponent
+```
+
+## Features
+
+- Horizontal and vertical orientation
+- Clickable steps
+- Complete/current/upcoming states
+- Dark mode support
+- Accessible
+- Customizable styling

package/src/ui/stepper/Stepper.stx

@@ -0,0 +1,17 @@
+<script>
+export const currentStep = $props.currentStep || 0
+export const orientation = $props.orientation || 'horizontal'
+export const className = $props.className || ''
+export const as = $props.as || 'div'
+
+const orientationClasses = orientation === 'horizontal'
+  ? 'flex flex-row'
+  : 'flex flex-col'
+
+const baseClasses = 'w-full'
+const stepperClasses = `${baseClasses} ${orientationClasses} ${className}`.trim()
+</script>
+
+<component :is="{{ as }}" class="{{ stepperClasses }}">
+  <slot :currentStep="currentStep" />
+</component>

package/src/ui/stepper/StepperStep.stx

@@ -0,0 +1,53 @@
+<script>
+export const stepNumber = $props.stepNumber
+export const currentStep = $props.currentStep || 0
+export const label = $props.label || ''
+export const description = $props.description || ''
+export const className = $props.className || ''
+export const as = $props.as || 'div'
+export const onClick = $props.onClick
+
+export const isComplete = stepNumber < currentStep
+export const isCurrent = stepNumber === currentStep
+export const isUpcoming = stepNumber > currentStep
+
+const baseClasses = 'flex items-center'
+const stepClasses = `${baseClasses} ${className}`.trim()
+
+export function handleClick() {
+  onClick?.(stepNumber)
+}
+</script>
+
+<component :is="{{ as }}" class="{{ stepClasses }}">
+  <button
+    type="button"
+    @click="handleClick"
+    class="flex items-center gap-3 focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 rounded-lg p-2"
+  >
+    <div class="{{ isComplete ? 'bg-blue-600 dark:bg-blue-500' : isCurrent ? 'bg-blue-600 dark:bg-blue-500 ring-4 ring-blue-200 dark:ring-blue-800' : 'bg-neutral-300 dark:bg-neutral-600' }} w-10 h-10 rounded-full flex items-center justify-center text-white font-semibold transition-all">
+      @if(isComplete)
+        <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
+        </svg>
+      @else
+        {{ stepNumber + 1 }}
+      @endif
+    </div>
+
+    @if(label)
+      <div class="text-left">
+        <div class="text-sm font-medium {{ isCurrent ? 'text-blue-600 dark:text-blue-400' : 'text-neutral-900 dark:text-white' }}">
+          {{ label }}
+        </div>
+        @if(description)
+          <div class="text-xs text-neutral-500 dark:text-neutral-400">
+            {{ description }}
+          </div>
+        @endif
+      </div>
+    @endif
+  </button>
+
+  <slot :isComplete="isComplete" :isCurrent="isCurrent" :isUpcoming="isUpcoming" />
+</component>

package/src/ui/stepper/index.ts

@@ -0,0 +1,19 @@
+export { default as Stepper } from './Stepper.stx'
+export { default as StepperStep } from './StepperStep.stx'
+
+export interface StepperProps {
+  currentStep?: number
+  orientation?: 'horizontal' | 'vertical'
+  className?: string
+  as?: string
+}
+
+export interface StepperStepProps {
+  stepNumber: number
+  currentStep?: number
+  label?: string
+  description?: string
+  className?: string
+  as?: string
+  onClick?: (step: number) => void
+}

package/src/ui/storage/README.md

@@ -0,0 +1,193 @@
+# Storage Utilities
+
+Type-safe utilities for localStorage and sessionStorage with expiration support.
+
+## Installation
+
+```bash
+bun add @stacksjs/components
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { localStorage, sessionStorage } from '@stacksjs/components'
+
+// Set a value
+localStorage.set('user', { name: 'John', age: 30 })
+
+// Get a value
+const user = localStorage.get('user')
+console.log(user) // { name: 'John', age: 30 }
+
+// Remove a value
+localStorage.remove('user')
+
+// Clear all
+localStorage.clear()
+```
+
+### With Expiration
+
+```typescript
+// Expire after 1 hour (3600000 ms)
+localStorage.set('token', 'abc123', { expire: 3600000 })
+
+// After 1 hour, get() returns null
+const token = localStorage.get('token') // null if expired
+```
+
+### With Namespace
+
+```typescript
+import { createStorage } from '@stacksjs/components'
+
+const userStorage = createStorage('local', 'user')
+const appStorage = createStorage('local', 'app')
+
+userStorage.set('preferences', { theme: 'dark' })
+appStorage.set('preferences', { language: 'en' })
+
+// These are stored as 'user:preferences' and 'app:preferences'
+```
+
+### Session Storage
+
+```typescript
+import { sessionStorage } from '@stacksjs/components'
+
+// Same API as localStorage
+sessionStorage.set('tempData', { value: 123 })
+const data = sessionStorage.get('tempData')
+```
+
+## API
+
+### Storage Methods
+
+#### `set(key: string, value: any, options?: StorageOptions): void`
+Store a value with optional expiration.
+
+#### `get<T>(key: string): T | null`
+Retrieve a value. Returns null if expired or not found.
+
+#### `remove(key: string): void`
+Remove a specific key.
+
+#### `clear(): void`
+Clear all items (or all namespaced items).
+
+#### `has(key: string): boolean`
+Check if a key exists and hasn't expired.
+
+#### `keys(): string[]`
+Get all keys (without namespace prefix).
+
+#### `size(): number`
+Get the number of stored items.
+
+## StorageOptions
+
+```typescript
+interface StorageOptions {
+  expire?: number // Expiration in milliseconds
+  namespace?: string // Prefix for keys (in createStorage)
+}
+```
+
+## Features
+
+- **Type-safe** - Full TypeScript support
+- **Expiration** - Automatic expiration handling
+- **Namespacing** - Prevent key collisions
+- **Error handling** - Graceful error handling
+- **JSON serialization** - Automatic serialization/deserialization
+- **Both storages** - localStorage and sessionStorage support
+
+## Examples
+
+### User Authentication Token
+
+```typescript
+import { localStorage } from '@stacksjs/components'
+
+// Store token with 24-hour expiration
+function login(token: string) {
+  localStorage.set('auth_token', token, {
+    expire: 24 * 60 * 60 * 1000, // 24 hours
+  })
+}
+
+// Get token (returns null if expired)
+function getToken(): string | null {
+  return localStorage.get('auth_token')
+}
+
+// Check if logged in
+function isLoggedIn(): boolean {
+  return localStorage.has('auth_token')
+}
+
+// Logout
+function logout() {
+  localStorage.remove('auth_token')
+}
+```
+
+### User Preferences
+
+```typescript
+import { createStorage } from '@stacksjs/components'
+
+const prefs = createStorage('local', 'preferences')
+
+interface UserPreferences {
+  theme: 'light' | 'dark'
+  language: string
+  notifications: boolean
+}
+
+// Save preferences
+function savePreferences(preferences: UserPreferences) {
+  prefs.set('user', preferences)
+}
+
+// Load preferences with defaults
+function loadPreferences(): UserPreferences {
+  const saved = prefs.get<UserPreferences>('user')
+  return saved || {
+    theme: 'light',
+    language: 'en',
+    notifications: true,
+  }
+}
+```
+
+### Shopping Cart
+
+```typescript
+import { localStorage } from '@stacksjs/components'
+
+interface CartItem {
+  id: string
+  name: string
+  quantity: number
+  price: number
+}
+
+function addToCart(item: CartItem) {
+  const cart = localStorage.get<CartItem[]>('cart') || []
+  cart.push(item)
+  localStorage.set('cart', cart)
+}
+
+function getCart(): CartItem[] {
+  return localStorage.get<CartItem[]>('cart') || []
+}
+
+function clearCart() {
+  localStorage.remove('cart')
+}
+```

package/src/ui/storage/index.ts

@@ -0,0 +1,347 @@
+// Storage utilities for localStorage and sessionStorage
+
+export interface StorageOptions {
+  expire?: number // Expiration in milliseconds
+  namespace?: string // Prefix for keys
+  encrypt?: boolean // Encrypt data (basic XOR encryption)
+  compress?: boolean // Compress large objects
+}
+
+type StorageWatchCallback = (newValue: any, oldValue: any, key: string) => void
+
+export class StorageManager {
+  private storage: globalThis.Storage
+  private namespace: string
+  private watchers: Map<string, Set<StorageWatchCallback>> = new Map()
+  private encryptionKey = 'stx-storage-key' // Simple encryption key
+
+  constructor(type: 'local' | 'session' = 'local', namespace = '') {
+    this.storage = type === 'local' ? globalThis.localStorage : globalThis.sessionStorage
+    this.namespace = namespace
+
+    // Listen for storage events from other tabs/windows
+    if (typeof window !== 'undefined') {
+      window.addEventListener('storage', this.handleStorageEvent.bind(this))
+    }
+  }
+
+  private handleStorageEvent(event: StorageEvent): void {
+    if (!event.key)
+      return
+
+    const key = this.namespace && event.key.startsWith(`${this.namespace}:`)
+      ? event.key.slice(this.namespace.length + 1)
+      : event.key
+
+    const callbacks = this.watchers.get(key)
+    if (callbacks) {
+      const oldValue = event.oldValue ? JSON.parse(event.oldValue).value : null
+      const newValue = event.newValue ? JSON.parse(event.newValue).value : null
+      callbacks.forEach(callback => callback(newValue, oldValue, key))
+    }
+  }
+
+  private encrypt(data: string): string {
+    // Simple XOR encryption (not cryptographically secure, just obfuscation)
+    let result = ''
+    for (let i = 0; i < data.length; i++) {
+      result += String.fromCharCode(data.charCodeAt(i) ^ this.encryptionKey.charCodeAt(i % this.encryptionKey.length))
+    }
+    return btoa(result) // Base64 encode
+  }
+
+  private decrypt(data: string): string {
+    try {
+      const decoded = atob(data) // Base64 decode
+      let result = ''
+      for (let i = 0; i < decoded.length; i++) {
+        result += String.fromCharCode(decoded.charCodeAt(i) ^ this.encryptionKey.charCodeAt(i % this.encryptionKey.length))
+      }
+      return result
+    }
+    catch {
+      return data // Return as-is if decryption fails
+    }
+  }
+
+  private compress(data: string): string {
+    // Simple LZ-based compression for large strings
+    if (data.length < 100)
+      return data // Don't compress small strings
+
+    const dict: Record<string, number> = {}
+    let dictSize = 256
+    const result: number[] = []
+    let w = ''
+
+    for (let i = 0; i < data.length; i++) {
+      const c = data.charAt(i)
+      const wc = w + c
+
+      if (dict[wc] !== undefined) {
+        w = wc
+      }
+      else {
+        result.push(w.length > 1 ? dict[w] : w.charCodeAt(0))
+        dict[wc] = dictSize++
+        w = c
+      }
+    }
+
+    if (w !== '') {
+      result.push(w.length > 1 ? dict[w] : w.charCodeAt(0))
+    }
+
+    return JSON.stringify(result)
+  }
+
+  private decompress(data: string): string {
+    try {
+      const compressed = JSON.parse(data)
+      if (!Array.isArray(compressed))
+        return data
+
+      const dict: Record<number, string> = {}
+      let dictSize = 256
+      let w = String.fromCharCode(compressed[0])
+      let result = w
+
+      for (let i = 1; i < compressed.length; i++) {
+        const k = compressed[i]
+        let entry: string
+
+        if (dict[k] !== undefined) {
+          entry = dict[k]
+        }
+        else if (k === dictSize) {
+          entry = w + w.charAt(0)
+        }
+        else {
+          return data // Decompression failed
+        }
+
+        result += entry
+        dict[dictSize++] = w + entry.charAt(0)
+        w = entry
+      }
+
+      return result
+    }
+    catch {
+      return data // Return as-is if decompression fails
+    }
+  }
+
+  private getKey(key: string): string {
+    return this.namespace ? `${this.namespace}:${key}` : key
+  }
+
+  set(key: string, value: any, options?: StorageOptions): void {
+    const fullKey = this.getKey(key)
+    const oldValue = this.get(key)
+
+    const data = {
+      value,
+      timestamp: Date.now(),
+      expire: options?.expire,
+      encrypted: options?.encrypt || false,
+      compressed: options?.compress || false,
+    }
+
+    try {
+      let serialized = JSON.stringify(data)
+
+      // Compress if enabled
+      if (options?.compress) {
+        serialized = this.compress(serialized)
+      }
+
+      // Encrypt if enabled
+      if (options?.encrypt) {
+        serialized = this.encrypt(serialized)
+      }
+
+      this.storage.setItem(fullKey, serialized)
+
+      // Notify watchers
+      this.notifyWatchers(key, value, oldValue)
+    }
+    catch (error) {
+      console.error('Storage set error:', error)
+    }
+  }
+
+  get<T = any>(key: string): T | null {
+    const fullKey = this.getKey(key)
+
+    try {
+      let item = this.storage.getItem(fullKey)
+      if (!item)
+        return null
+
+      // Try to decrypt if it looks encrypted (base64)
+      if (item.match(/^[A-Z0-9+/]+=*$/i)) {
+        try {
+          item = this.decrypt(item)
+        }
+        catch {
+          // Not encrypted, continue
+        }
+      }
+
+      // Try to decompress if it looks compressed (starts with [)
+      if (item.startsWith('[')) {
+        try {
+          item = this.decompress(item)
+        }
+        catch {
+          // Not compressed, continue
+        }
+      }
+
+      const data = JSON.parse(item)
+
+      // Check expiration
+      if (data.expire && Date.now() - data.timestamp > data.expire) {
+        this.remove(key)
+        return null
+      }
+
+      return data.value as T
+    }
+    catch (error) {
+      console.error('Storage get error:', error)
+      return null
+    }
+  }
+
+  watch(key: string, callback: StorageWatchCallback): () => void {
+    if (!this.watchers.has(key)) {
+      this.watchers.set(key, new Set())
+    }
+
+    this.watchers.get(key)!.add(callback)
+
+    // Return unwatch function
+    return () => {
+      const callbacks = this.watchers.get(key)
+      if (callbacks) {
+        callbacks.delete(callback)
+        if (callbacks.size === 0) {
+          this.watchers.delete(key)
+        }
+      }
+    }
+  }
+
+  private notifyWatchers(key: string, newValue: any, oldValue: any): void {
+    const callbacks = this.watchers.get(key)
+    if (callbacks) {
+      callbacks.forEach(callback => callback(newValue, oldValue, key))
+    }
+  }
+
+  remove(key: string): void {
+    const fullKey = this.getKey(key)
+    const oldValue = this.get(key)
+    this.storage.removeItem(fullKey)
+
+    // Notify watchers
+    this.notifyWatchers(key, null, oldValue)
+  }
+
+  clear(): void {
+    if (this.namespace) {
+      // Clear only namespaced items
+      const keys = this.keys()
+      keys.forEach(key => this.remove(key))
+    }
+    else {
+      this.storage.clear()
+    }
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== null
+  }
+
+  keys(): string[] {
+    const allKeys = Object.keys(this.storage)
+
+    if (this.namespace) {
+      const prefix = `${this.namespace}:`
+      return allKeys
+        .filter(key => key.startsWith(prefix))
+        .map(key => key.slice(prefix.length))
+    }
+
+    return allKeys
+  }
+
+  size(): number {
+    return this.keys().length
+  }
+
+  // Get storage quota information (if available)
+  getQuota(): { usage: number, quota: number, percentage: number } | null {
+    if ('storage' in navigator && 'estimate' in navigator.storage) {
+      // Use async/await pattern but return promise
+      return null // This would need to be async, but keeping sync API
+    }
+
+    // Fallback: estimate based on current data
+    try {
+      let totalSize = 0
+      for (let i = 0; i < this.storage.length; i++) {
+        const key = this.storage.key(i)
+        if (key) {
+          const value = this.storage.getItem(key) || ''
+          totalSize += key.length + value.length
+        }
+      }
+
+      // Typical localStorage quota is 5-10MB
+      const estimatedQuota = 5 * 1024 * 1024 // 5MB
+      return {
+        usage: totalSize * 2, // Multiply by 2 for UTF-16 encoding
+        quota: estimatedQuota,
+        percentage: (totalSize * 2 / estimatedQuota) * 100,
+      }
+    }
+    catch {
+      return null
+    }
+  }
+
+  // Batch operations
+  setMany(items: Record<string, any>, options?: StorageOptions): void {
+    Object.entries(items).forEach(([key, value]) => {
+      this.set(key, value, options)
+    })
+  }
+
+  getMany<T = any>(keys: string[]): Record<string, T | null> {
+    const result: Record<string, T | null> = {}
+    keys.forEach((key) => {
+      result[key] = this.get<T>(key)
+    })
+    return result
+  }
+
+  removeMany(keys: string[]): void {
+    keys.forEach(key => this.remove(key))
+  }
+}
+
+// Convenience exports
+export const storage: {
+  local: StorageManager
+  session: StorageManager
+} = {
+  local: new StorageManager('local'),
+  session: new StorageManager('session'),
+}
+
+export function createStorage(type: 'local' | 'session' = 'local', namespace?: string): StorageManager {
+  return new StorageManager(type, namespace)
+}