diff --git a/README.md b/README.md
index d2e4df2..b1fc940 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,87 @@
# zulip
-A minimal, no-build web app kit using only Lit-based web components via importmaps.
+A modern, no-build web application using Lit web components with Zustand state management.
+## Architecture Overview
-## Quick Start Example
+* **Lit-based web components** - Standards-based, framework-agnostic UI
+* **No-build tooling** - Import maps only, no bundler required
+* **Zustand state management** - Lightweight, vanilla JS store
+* **StoreController** - Reactive controller that bridges Zustand and Lit
-### 1. Define a Component
+## Project Structure
+
+```
+components/ -> standard lit components, including top-level "app-root"
+controllers/ -> lit reactive controllers (such as Zustand<->Lit bridge)
+store/ -> defines specific accessor sets
+index.html -> entry point with inline importmap and app-root
+README.md
+```
+
+## Data Flow Diagram
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant LitComponent
+ participant StoreController
+ participant ZustandStore
+
+ User->>LitComponent: Click button
+ LitComponent->>ZustandStore: Call action (e.g., addItem)
+ ZustandStore->>ZustandStore: Update state
+ ZustandStore->>StoreController: Notify subscribers
+ StoreController->>LitComponent: requestUpdate()
+ LitComponent->>LitComponent: Re-render
+ LitComponent->>User: Show updated UI
+```
+
+## Example
+
+### 1. Define Store (Zustand Vanilla)
+
+```javascript
+// store/index.js
+import { createStore } from 'zustand/vanilla'
+
+export const store = createStore((set, get) => ({
+ count: 0,
+ increment: () => set(s => ({ count: s.count + 1 })),
+ decrement: () => set(s => ({ count: s.count - 1 })),
+}))
+```
+
+### 2. Create StoreController (Bridge)
+
+```javascript
+// controllers/store.js
+export class StoreController {
+ constructor(host, store, selector) {
+ this.host = host
+ this.store = store
+ this.selector = selector
+ host.addController(this)
+ }
+
+ hostConnected() {
+ this._unsub = this.store.subscribe((state) => {
+ const next = this.selector(state)
+ if (next !== this.value) {
+ this.value = next
+ this.host.requestUpdate()
+ }
+ })
+ this.value = this.selector(this.store.getState())
+ }
+
+ hostDisconnected() {
+ this._unsub?.()
+ }
+}
+```
+
+### 3. Create Component (Lit + StoreController)
```javascript
// components/counter.js
@@ -22,16 +98,15 @@ class Counter extends LitElement {
}
static styles = css`
- button { padding: 1rem; font-size: 1.2rem; }
+ button { padding: 1rem; font-size: 1.2rem; margin: 0.5rem; }
`
render() {
return html`
-
Count: ${this.count}
-
+
Count: ${this.#count.value}
+
+
loading...
`;
+ }
return html`
- this.#navigate(e.detail.route)}
- >
+
${this.#renderRoute()}
+
`;
}
#renderRoute() {
- switch (this.route) {
- case "home":
- return html``;
- case "items":
- return html` this.#addItem(e.detail.item)}
- @remove-item=${(e) => this.#removeItem(e.detail.id)}
- >`;
- default:
- return html``;
+ switch (this.#route.value) {
+ case "home": return html``;
+ case "items": return html``;
+ default: return html``;
}
}
}
diff --git a/components/error-toast.js b/components/error-toast.js
new file mode 100644
index 0000000..0e90eda
--- /dev/null
+++ b/components/error-toast.js
@@ -0,0 +1,79 @@
+// components/error-toast.js
+import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from '../controllers/store-controller.js'
+
+class ErrorToast extends LitElement {
+ #error = new StoreController(this, store, s => s.error)
+
+ static styles = css`
+ :host {
+ position: fixed;
+ top: 1rem;
+ right: 1rem;
+ z-index: 1000;
+ }
+
+ .toast {
+ background: #ef4444;
+ color: white;
+ padding: 1rem 1.5rem;
+ border-radius: 8px;
+ box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+ display: flex;
+ align-items: center;
+ gap: 1rem;
+ min-width: 300px;
+ animation: slideIn 0.3s ease-out;
+ }
+
+ @keyframes slideIn {
+ from {
+ transform: translateX(400px);
+ opacity: 0;
+ }
+ to {
+ transform: translateX(0);
+ opacity: 1;
+ }
+ }
+
+ .message {
+ flex: 1;
+ font-size: 0.9rem;
+ }
+
+ .close {
+ background: none;
+ border: none;
+ color: white;
+ cursor: pointer;
+ font-size: 1.2rem;
+ padding: 0;
+ opacity: 0.8;
+ }
+
+ .close:hover {
+ opacity: 1;
+ }
+ `
+
+ render() {
+ if (!this.#error.value) {
+ return html``
+ }
+
+ return html`
+
+ ${this.#error.value}
+
+
+ `
+ }
+}
+
+customElements.define('error-toast', ErrorToast)
diff --git a/components/nav-bar.js b/components/nav-bar.js
index 6f192a1..9b44aa2 100644
--- a/components/nav-bar.js
+++ b/components/nav-bar.js
@@ -1,10 +1,13 @@
// components/nav-bar.js
import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from "../controllers/store-controller.js";
class NavBar extends LitElement {
+ #route = new StoreController(this, store, s => s.route)
+
static properties = {
- user: { type: Object },
- route: { type: String }
+ user: { type: Object }
}
static styles = css`
@@ -32,18 +35,14 @@ class NavBar extends LitElement {
#navigate(route, e) {
e.preventDefault()
- this.dispatchEvent(new CustomEvent('navigate', {
- detail: { route },
- bubbles: true,
- composed: true
- }))
+ store.getState().navigate(route)
}
#link(route, label) {
return html`
this.#navigate(route, e)}
>${label}
`
@@ -62,4 +61,4 @@ class NavBar extends LitElement {
}
}
-customElements.define('nav-bar', NavBar)
+customElements.define('nav-bar', NavBar)
\ No newline at end of file
diff --git a/components/page-home.js b/components/page-home.js
index 3d5c616..f6536e7 100644
--- a/components/page-home.js
+++ b/components/page-home.js
@@ -1,11 +1,11 @@
// components/page-home.js
import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from "../controllers/store-controller.js";
class PageHome extends LitElement {
- static properties = {
- user: { type: Object },
- items: { type: Array }
- }
+ #user = new StoreController(this, store, s => s.user)
+ #items = new StoreController(this, store, s => s.items)
static styles = css`
:host { display: block; padding: 2rem 1.5rem; }
@@ -25,8 +25,8 @@ class PageHome extends LitElement {
`
render() {
- const name = this.user?.name ?? 'there'
- const count = this.items?.length ?? 0
+ const name = this.#user.value?.name ?? 'there'
+ const count = this.#items.value.length
return html`
Hey, ${name}
@@ -41,4 +41,4 @@ class PageHome extends LitElement {
}
}
-customElements.define('page-home', PageHome)
+customElements.define('page-home', PageHome)
\ No newline at end of file
diff --git a/components/page-items.js b/components/page-items.js
index f788396..dde3a1a 100644
--- a/components/page-items.js
+++ b/components/page-items.js
@@ -1,17 +1,16 @@
// components/page-items.js
import { LitElement, html, css } from 'lit'
+import { store } from '../store/index.js'
+import { StoreController } from "../controllers/store-controller.js";
class PageItems extends LitElement {
+ #items = new StoreController(this, store, s => s.items)
+
static properties = {
- items: { type: Array },
_draft: { type: String, state: true }
}
- constructor() {
- super();
- this.items = [];
- this._draft = '';
- }
+ _draft = ''
static styles = css`
:host { display: block; padding: 2rem 1.5rem; }
@@ -64,22 +63,12 @@ class PageItems extends LitElement {
#add() {
const name = this._draft.trim()
if (!name) return
-
- this.dispatchEvent(new CustomEvent('add-item', {
- detail: { item: { id: crypto.randomUUID(), name } },
- bubbles: true,
- composed: true
- }))
-
+ store.getState().addItem({ id: crypto.randomUUID(), name })
this._draft = ''
}
#remove(id) {
- this.dispatchEvent(new CustomEvent('remove-item', {
- detail: { id },
- bubbles: true,
- composed: true
- }))
+ store.getState().removeItem(id)
}
#onKeydown(e) {
@@ -87,7 +76,7 @@ class PageItems extends LitElement {
}
render() {
- const items = this.items ?? []
+ const items = this.#items.value
return html`
Items
@@ -119,4 +108,4 @@ class PageItems extends LitElement {
}
}
-customElements.define('page-items', PageItems)
+customElements.define('page-items', PageItems)
\ No newline at end of file
diff --git a/controllers/store-controller.js b/controllers/store-controller.js
new file mode 100644
index 0000000..998294d
--- /dev/null
+++ b/controllers/store-controller.js
@@ -0,0 +1,23 @@
+export class StoreController {
+ constructor(host, store, selector) {
+ this.host = host
+ this.store = store
+ this.selector = selector
+ host.addController(this)
+ }
+
+ hostConnected() {
+ this._unsub = this.store.subscribe(
+ (state) => {
+ const next = this.selector(state)
+ if (next !== this.value) {
+ this.value = next
+ this.host.requestUpdate()
+ }
+ }
+ )
+ this.value = this.selector(this.store.getState())
+ }
+
+ hostDisconnected() { this._unsub?.() }
+ }
\ No newline at end of file
diff --git a/index.html b/index.html
index 879175b..51c53cd 100644
--- a/index.html
+++ b/index.html
@@ -8,7 +8,10 @@
{
"imports": {
"lit": "https://esm.sh/lit@3",
- "lit/decorators.js": "https://esm.sh/lit@3/decorators.js"
+ "lit/decorators.js": "https://esm.sh/lit@3/decorators.js",
+ "zustand/vanilla": "https://esm.sh/zustand@5/vanilla",
+ "zustand/middleware": "https://esm.sh/zustand@5/middleware",
+ "idb-keyval": "https://esm.sh/idb-keyval@6"
}
}
diff --git a/store/idb.js b/store/idb.js
new file mode 100644
index 0000000..e276f00
--- /dev/null
+++ b/store/idb.js
@@ -0,0 +1,33 @@
+// lib/idb.js
+import { createStore, get, set, del, entries, clear } from 'idb-keyval'
+
+// Named stores — each maps to a distinct IDBObjectStore
+export const itemsStore = createStore('app-db', 'items')
+export const userStore = createStore('app-db', 'user')
+export const cacheStore = createStore('app-db', 'cache')
+
+// Typed wrappers — keeps raw idb-keyval calls out of the rest of the app
+// and gives you one place to add validation, logging, or migration logic
+
+export const db = {
+ items: {
+ getAll: () => entries(itemsStore),
+ get: (id) => get(id, itemsStore),
+ set: (id, value) => set(id, value, itemsStore),
+ remove: (id) => del(id, itemsStore),
+ clear: () => clear(itemsStore),
+ },
+
+ user: {
+ get: () => get('user', userStore),
+ set: (value) => set('user', value, userStore),
+ clear: () => del('user', userStore),
+ },
+
+ cache: {
+ get: (key) => get(key, cacheStore),
+ set: (key, value) => set(key, value, cacheStore),
+ remove: (key) => del(key, cacheStore),
+ clear: () => clear(cacheStore),
+ }
+}
\ No newline at end of file
diff --git a/store/index.js b/store/index.js
new file mode 100644
index 0000000..feaea96
--- /dev/null
+++ b/store/index.js
@@ -0,0 +1,86 @@
+import { createStore } from 'zustand/vanilla'
+import { persist, createJSONStorage } from 'zustand/middleware'
+import { get, set, del } from 'idb-keyval'
+
+// Create IndexedDB storage adapter with error handling
+const storage = createJSONStorage(() => ({
+ getItem: async (name) => {
+ try {
+ const value = await get(name)
+ return value ?? null
+ } catch (error) {
+ console.error('IndexedDB getItem error:', error)
+ return null // Fallback to null if IndexedDB fails
+ }
+ },
+ setItem: async (name, value) => {
+ try {
+ await set(name, value)
+ } catch (error) {
+ console.error('IndexedDB setItem error:', error)
+ // Silently fail - app continues to work without persistence
+ }
+ },
+ removeItem: async (name) => {
+ try {
+ await del(name)
+ } catch (error) {
+ console.error('IndexedDB removeItem error:', error)
+ // Silently fail
+ }
+ },
+}))
+
+export const store = createStore(
+ persist(
+ (set, get) => ({
+ _hydrated: true, // Start as true - persistence happens in background
+ user: null,
+ items: [],
+ route: 'home',
+ error: null, // For error notifications
+
+ // Actions
+ setUser: (user) => set({ user }),
+
+ addItem: (item) => {
+ try {
+ if (!item || !item.name || !item.name.trim()) {
+ throw new Error('Item name is required')
+ }
+ set(s => ({ items: [...s.items, item], error: null }))
+ } catch (error) {
+ console.error('addItem error:', error)
+ set({ error: error.message })
+ setTimeout(() => set({ error: null }), 3000) // Clear after 3s
+ }
+ },
+
+ removeItem: (id) => {
+ try {
+ if (!id) {
+ throw new Error('Item ID is required')
+ }
+ set(s => ({ items: s.items.filter(i => i.id !== id), error: null }))
+ } catch (error) {
+ console.error('removeItem error:', error)
+ set({ error: error.message })
+ setTimeout(() => set({ error: null }), 3000)
+ }
+ },
+
+ navigate: (route) => set({ route }),
+
+ clearError: () => set({ error: null }),
+ }),
+ {
+ name: 'app-store',
+ storage,
+ partialize: (state) => ({
+ user: state.user,
+ items: state.items,
+ route: state.route,
+ }),
+ }
+ )
+)
diff --git a/store/persistence.js b/store/persistence.js
new file mode 100644
index 0000000..bdb7dc1
--- /dev/null
+++ b/store/persistence.js
@@ -0,0 +1,9 @@
+// store/middleware/persistence.js
+import { db } from './idb.js'
+
+export const makeIdbStorage = (storeName) =>
+ createJSONStorage(() => ({
+ getItem: (name) => db[storeName].get(name),
+ setItem: (name, value) => db[storeName].set(name, value),
+ removeItem: (name) => db[storeName].remove(name),
+ }))
\ No newline at end of file
diff --git a/tasks.md b/tasks.md
deleted file mode 100644
index edd6904..0000000
--- a/tasks.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Tasks & Issues
-
-## 1. Critical Issues
-
-- [ ] **1.1 Fix missing `del` import in store/index.js**
- - Line 3 imports `get, set` from idb-keyval but `del` is used on line 13
- - Add `del` to the import statement
- - This will cause a ReferenceError when removeItem is called
-
-- [ ] **1.2 Fix hydration flag initialization**
- - The `onRehydrateStorage` callback uses `store.setState()` before `store` is fully initialized
- - Creates a circular reference issue preventing app from loading
- - **Options:**
- - A) Initialize `_hydrated: true` by default (simplest)
- - B) Use Zustand's persist middleware built-in hydration detection
- - C) Move hydration callback outside store creation
-
-- [ ] **1.3 Consolidate duplicate storage implementation**
- - Storage is defined in both `store/index.js` AND `store/middleware/persistence.js`
- - The middleware file exports `idbStorage` but it's not being used
- - **Decision needed:** Use one or the other, not both
-
-## 2. Architectural Improvements
-
-- [ ] **2.1 Add error handling**
- - Add try/catch blocks around IndexedDB operations
- - Implement fallback if IndexedDB fails or is unavailable
- - Add user feedback for errors (toast notifications?)
-
-- [ ] **2.2 Add partialize option to persist middleware**
- - Currently saves ALL state including `_hydrated` flag and `route`
- - Should use `partialize: (state) => ({ user: state.user, items: state.items })`
- - Prevents unnecessary data in IndexedDB
-
-- [ ] **2.3 Add basic CSS reset to index.html**
- - No base styles, margins, or font settings currently
- - Consider adding minimal reset or normalize.css
-
-- [ ] **2.4 Add loading states for async operations**
- - No loading indicators for add/remove item operations
- - Consider adding optimistic updates
-
-## 3. Nice to Have
-
-- [ ] **3.1 Add TypeScript types** (optional)
- - JSDoc comments for better IDE support
- - Or migrate to .ts files with no-build setup
-
-- [ ] **3.2 Add cross-tab synchronization**
- - README mentions optional `sync.js` middleware
- - Implement BroadcastChannel for cross-tab state sync
-
-- [ ] **3.3 Add route history management**
- - Integrate with browser history API
- - Support back/forward navigation
-
-- [ ] **3.4 Add unit tests**
- - Test store actions and selectors
- - Test component rendering
- - Test persistence layer