Pattern: What pattern should Platform Elements use for element state ...

Documentation for Sessions

🎨 Pattern: What pattern should Platform Elements use for element state ...

Date: 2026-03-25
Time: 12:09:20 UTC
Session: gspace1-268.10
Agent: storage
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

What pattern should Platform Elements use for element state persistence across page reloads?

Task: S268.2: Platform Elements Phase 1 — State persistence

🎯 Decision Made

Chosen:

createPersistentState() factory function returning a Proxy-wrapped object. Top-level property assignments auto-persist to localStorage with configurable debounce (default 300ms) and TTL (default 24h). Inspired by GoGrab's autoFlashState pattern but without Angular dependency.

Options Considered:

  1. Angular-style autoFlashState (requires Angular DI)
  2. sessionStorage (doesn't persist across tab close)
  3. IndexedDB (overcomplicated for simple key-value state)
  4. URL query params (leaks state, doesn't scale)
  5. No persistence (poor UX on reload)

💭 Reasoning

Users expect table sort order, current page, search query, and active route to survive page refresh. Without persistence, every reload resets the UI to defaults — poor UX for production platforms. The Proxy pattern was chosen because: (1) transparent to consuming code (state.page = 2 just works), (2) debounced writes prevent localStorage thrashing, (3) TTL prevents stale state from persisting indefinitely, (4) __reset() utility for programmatic state clearing. Known limitation: Proxy only intercepts top-level property assignments — nested object mutations (state.filters.status = 'active') are not detected. This is documented and acceptable because platform element state is flat (page, sortBy, sortOrder, searchQuery). The pattern mirrors the theme system's flash-persistence approach (see docs/english/GoGrab-Space/theme-system/flash-persistence-integration.md) but is framework-agnostic (no Angular signals/inject).

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation