streamlining readme

README.md

@@ -1,168 +1,25 @@
-# Lit + Zustand Architecture
+# zulip
 
-A modern, no-build web application architecture using Lit web components with Zustand state management and IndexedDB persistence.
+A minimal, no-build web app kit using only Lit-based web components via importmaps.
 
-## For TSX/React Developers
-
-If you're coming from React/TSX, here's how this architecture maps to familiar concepts:
-
-| React/TSX Pattern | This Architecture |
-|-------------------|-------------------|
-| `useState` / `useReducer` | Zustand vanilla store |
-| `useEffect` + state subscription | `StoreController` (ReactiveController) |
-| Context API | Global Zustand store |
-| `localStorage` / `sessionStorage` | IndexedDB via persist middleware |
-| JSX | Lit's `html` tagged template literals |
-| CSS-in-JS / CSS Modules | Lit's `css` tagged template literals |
-| React Router | Simple route state in store |
-| Build step (Vite/Webpack) | Import maps (no build!) |
-
-### Key Differences
-
-1. **No Virtual DOM**: Lit uses native Web Components with efficient DOM updates
-2. **No Build Step**: Import maps let you use npm packages directly from CDN
-3. **Reactive Controllers**: Replace hooks - attach to component lifecycle
-4. **Tagged Templates**: Instead of JSX, use `html\`<div>...</div>\``
-
-## Architecture Overview
-
-* **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
-* **IndexedDB persistence** - Automatic state persistence with idb-keyval
-
-
-## Layout
-
-```
-src/
-  store/
-    index.js          ← zustand store definition
-    middleware/
-      persistence.js  ← idb-keyval persist adapter
-      sync.js         ← optional cross-tab broadcast
-  components/
-    app-root.js
-    feature-a/
-      feature-a.js    ← Lit component
-      feature-a.css   ← adopted stylesheet or constructable
-  controllers/
-    fetch.js          ← ReactiveController for API calls
-    3d.js             ← optional Three/WebGPU controller
-  lib/
-    idb.js            ← thin idb-keyval wrapper/schema
-index.html
-importmap.json        ← extracted importmap (referenced via <script src>)
-```
-
-## Data Flow Diagrams
-
-### Component-to-Store Pattern
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant LitComponent
-    participant StoreController
-    participant ZustandStore
-    participant IndexedDB
-
-    User->>LitComponent: Click button
-    LitComponent->>ZustandStore: Call action (e.g., addItem)
-    ZustandStore->>ZustandStore: Update state
-    ZustandStore->>IndexedDB: Persist (via middleware)
-    ZustandStore->>StoreController: Notify subscribers
-    StoreController->>LitComponent: requestUpdate()
-    LitComponent->>LitComponent: Re-render
-    LitComponent->>User: Show updated UI
-```
-
-### Store Subscription Pattern
-
-```mermaid
-graph TD
-    A[Zustand Store] -->|subscribe| B[StoreController]
-    B -->|selector function| C[Extract specific state]
-    C -->|value changed?| D{Compare}
-    D -->|Yes| E[host.requestUpdate]
-    D -->|No| F[Skip update]
-    E --> G[Lit re-renders component]
-    
-    style A fill:#f9f,stroke:#333,stroke-width:2px
-    style B fill:#bbf,stroke:#333,stroke-width:2px
-    style G fill:#bfb,stroke:#333,stroke-width:2px
-```
-
-### Complete Mental Model
-
-```
-┌─────────────────────────────────────────┐
-│           User Interaction              │
-└──────────────┬──────────────────────────┘
-               │ (events)
-               ▼
-┌─────────────────────────────────────────┐
-│        Lit Web Components               │
-│  - html`` templates (like JSX)          │
-│  - css`` styles (scoped)                │
-│  - Event handlers                       │
-└──────────────┬──────────────────────────┘
-               │ (actions)
-               ▼
-┌─────────────────────────────────────────┐
-│      StoreController (glue layer)       │
-│  - ReactiveController interface         │
-│  - Subscribes to store                  │
-│  - Triggers requestUpdate()             │
-└──────────────┬──────────────────────────┘
-               │ (selector)
-               ▼
-┌─────────────────────────────────────────┐
-│       Zustand Vanilla Store             │
-│  - Global state (like Context)          │
-│  - Actions (like reducers)              │
-│  - Subscriptions                        │
-└──────────────┬──────────────────────────┘
-               │ (persist middleware)
-               ▼
-┌─────────────────────────────────────────┐
-│  IndexedDB (via idb-keyval)             │
-│  - Automatic persistence                │
-│  - Async storage                        │
-└─────────────────────────────────────────┘
-```
 
 ## Quick Start Example
 
-### 1. Define Store (like Redux/Zustand)
-
-```javascript
-// store/index.js
-import { createStore } from 'zustand/vanilla'
-import { persist } from 'zustand/middleware'
-
-export const store = createStore(
-  persist(
-    (set) => ({
-      count: 0,
-      increment: () => set(s => ({ count: s.count + 1 })),
-    }),
-    { name: 'my-store' }
-  )
-)
-```
-
-### 2. Create Component (like React component)
+### 1. Define a Component
 
 ```javascript
 // components/counter.js
 import { LitElement, html, css } from 'lit'
-import { StoreController } from '../controllers/store.js'
-import { store } from '../store/index.js'
 
 class Counter extends LitElement {
-  // Subscribe to store (like useSelector)
-  #count = new StoreController(this, store, s => s.count)
+  static properties = {
+    count: { type: Number, state: true }
+  }
+
+  constructor() {
+    super()
+    this.count = 0
+  }
 
   static styles = css`
     button { padding: 1rem; font-size: 1.2rem; }
@@ -171,8 +28,8 @@ class Counter extends LitElement {
   render() {
     return html`
       <div>
-        <p>Count: ${this.#count.value}</p>
-        <button @click=${() => store.getState().increment()}>
+        <p>Count: ${this.count}</p>
+        <button @click=${() => this.count++}>
           Increment
         </button>
       </div>
@@ -183,40 +40,59 @@ class Counter extends LitElement {
 customElements.define('my-counter', Counter)
 ```
 
-### 3. Use in HTML (no build step!)
+### 2. Use in App root (or other composition node)
 
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <script type="importmap">
-  {
-    "imports": {
-      "lit": "https://esm.sh/lit@3",
-      "zustand/vanilla": "https://esm.sh/zustand@5/vanilla",
-      "zustand/middleware": "https://esm.sh/zustand@5/middleware"
+```js
+import "./my-counter.js";
+
+class AppRoot extends LitElement {
+  ...
+  render() {
+    return html`<my-counter .count=${0}></my-counter>`;
   }
-  }
-  </script>
-</head>
-<body>
-  <script type="module" src="components/counter.js"></script>
-  <my-counter></my-counter>
-</body>
-</html>
+}
 ```
 
-## Benefits Over React/TSX
+### 3. Define Data Flows
 
-✅ **No build step** - Edit and refresh, instant feedback  
-✅ **Smaller bundle** - No framework runtime, just standards  
-✅ **Better encapsulation** - Shadow DOM, scoped styles  
-✅ **Framework agnostic** - Works anywhere, even in React apps  
-✅ **Future-proof** - Built on web standards  
+#### Parent-to-Child (Props)
 
-## See Also
+```javascript
+// Parent passes data down
+html`<child-component .items=${this.items}></child-component>`
 
-- [tasks.md](./tasks.md) - Current issues and improvements
-- [Lit Documentation](https://lit.dev)
-- [Zustand Documentation](https://zustand.docs.pmnd.rs)
-- [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
+// Child receives via properties
+static properties = {
+  items: { type: Array }
+}
+```
+
+#### Child-to-Parent (Events)
+
+```javascript
+// Child emits event
+this.dispatchEvent(new CustomEvent('add-item', {
+  detail: { item: newItem },
+  bubbles: true,
+  composed: true
+}))
+
+// Parent listens
+html`<child-component @add-item=${(e) => this.handleAdd(e.detail.item)}></child-component>`
+```
+
+## Benefits Over TSX
+
+1. **No build step** - Edit and refresh, instant feedback  
+
+1. **Minimal dependencies** - Just Lit, nothing else  
+
+1. **Smaller bundle** - No framework runtime, just standards  
+
+1. **Better encapsulation** - Shadow DOM, scoped styles  
+
+1. **Framework agnostic** - Works anywhere, even in React apps  
+
+1. **Future-proof** - Built on web standards  
+
+1. **Easy to learn** - Simple mental model for state, with natural evolution into Zustand/IndexedDB or similar extensions

components/app-root.js

@@ -1,44 +1,64 @@
 import { LitElement, html, css } from "lit";
-import { store} from "../store/index.js";
-import { StoreController } from "../controllers/store.js";
 import "./nav-bar.js";
 import "./page-home.js";
 import "./page-items.js";
 
 class AppRoot extends LitElement {
-    #hydrated = new StoreController(this, store, s => s._hydrated);
-    #user = new StoreController(this, store, s => s.user);
-    #route = new StoreController(this, store, s => s.route);
+    static properties = {
+        user: { type: Object, state: true },
+        route: { type: String, state: true },
+        items: { type: Array, state: true }
+    };
+
+    constructor() {
+        super();
+        this.user = null;
+        this.route = 'home';
+        this.items = [];
+    }
 
     static styles = css`
         :host {
             display: block;
             min-height: 100vh;
         }
-        
-        .loading {
-            display: grid;
-            place-items: center;
-            height: 100vh;
-            opacity: 0.4;
-        }
     `;
 
-    render() {
-        if (!this.#hydrated.value) {
-            return html`<div class="loading">loading...</div>`;
+    #navigate(route) {
+        this.route = route;
     }
+
+    #addItem(item) {
+        this.items = [...this.items, item];
+    }
+
+    #removeItem(id) {
+        this.items = this.items.filter(i => i.id !== id);
+    }
+
+    render() {
         return html`
-            <nav-bar .user=${this.#user.value}></nav-bar>
+            <nav-bar 
+                .user=${this.user}
+                .route=${this.route}
+                @navigate=${(e) => this.#navigate(e.detail.route)}
+            ></nav-bar>
             <main>${this.#renderRoute()}</main>
         `;
     }
 
     #renderRoute() {
-        switch (this.#route.value) {
-            case "home": return html`<page-home></page-home>`;
-            case "items": return html`<page-items></page-items>`;
-            default: return html`<page-home></page-home>`;
+        switch (this.route) {
+            case "home": 
+                return html`<page-home .user=${this.user} .items=${this.items}></page-home>`;
+            case "items": 
+                return html`<page-items 
+                    .items=${this.items}
+                    @add-item=${(e) => this.#addItem(e.detail.item)}
+                    @remove-item=${(e) => this.#removeItem(e.detail.id)}
+                ></page-items>`;
+            default: 
+                return html`<page-home .user=${this.user} .items=${this.items}></page-home>`;
         }
     }
 }

components/nav-bar.js

@@ -1,13 +1,10 @@
 // components/nav-bar.js
 import { LitElement, html, css } from 'lit'
-import { store } from '../store/index.js'
-import { StoreController } from '../controllers/store.js'
 
 class NavBar extends LitElement {
-  #route = new StoreController(this, store, s => s.route)
-
   static properties = {
-    user: { type: Object }
+    user: { type: Object },
+    route: { type: String }
   }
 
   static styles = css`
@@ -35,14 +32,18 @@ class NavBar extends LitElement {
 
   #navigate(route, e) {
     e.preventDefault()
-    store.getState().navigate(route)
+    this.dispatchEvent(new CustomEvent('navigate', { 
+      detail: { route },
+      bubbles: true,
+      composed: true
+    }))
   }
 
   #link(route, label) {
     return html`
       <a
         href="/${route}"
-        ?active=${this.#route.value === route}
+        ?active=${this.route === route}
         @click=${(e) => this.#navigate(route, e)}
       >${label}</a>
     `

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.js'
 
 class PageHome extends LitElement {
-  #user  = new StoreController(this, store, s => s.user)
-  #items = new StoreController(this, store, s => s.items)
+  static properties = {
+    user: { type: Object },
+    items: { type: Array }
+  }
 
   static styles = css`
     :host { display: block; padding: 2rem 1.5rem; }
@@ -25,8 +25,8 @@ class PageHome extends LitElement {
   `
 
   render() {
-    const name = this.#user.value?.name ?? 'there'
-    const count = this.#items.value.length
+    const name = this.user?.name ?? 'there'
+    const count = this.items?.length ?? 0
 
     return html`
       <h1>Hey, ${name}</h1>

components/page-items.js

@@ -1,16 +1,17 @@
 // components/page-items.js
 import { LitElement, html, css } from 'lit'
-import { store } from '../store/index.js'
-import { StoreController } from '../controllers/store.js'
 
 class PageItems extends LitElement {
-  #items = new StoreController(this, store, s => s.items)
-
   static properties = {
+    items: { type: Array },
     _draft: { type: String, state: true }
   }
 
-  _draft = ''
+  constructor() {
+    super();
+    this.items = [];
+    this._draft = '';
+  }
 
   static styles = css`
     :host { display: block; padding: 2rem 1.5rem; }
@@ -63,12 +64,22 @@ class PageItems extends LitElement {
   #add() {
     const name = this._draft.trim()
     if (!name) return
-    store.getState().addItem({ id: crypto.randomUUID(), name })
+    
+    this.dispatchEvent(new CustomEvent('add-item', {
+      detail: { item: { id: crypto.randomUUID(), name } },
+      bubbles: true,
+      composed: true
+    }))
+    
     this._draft = ''
   }
 
   #remove(id) {
-    store.getState().removeItem(id)
+    this.dispatchEvent(new CustomEvent('remove-item', {
+      detail: { id },
+      bubbles: true,
+      composed: true
+    }))
   }
 
   #onKeydown(e) {
@@ -76,7 +87,7 @@ class PageItems extends LitElement {
   }
 
   render() {
-    const items = this.#items.value
+    const items = this.items ?? []
 
     return html`
       <h1>Items</h1>

controllers/store.js

@@ -1,23 +0,0 @@
-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?.() }
-  }

index.html

@@ -8,10 +8,7 @@
     {
         "imports": {
             "lit": "https://esm.sh/lit@3",
-            "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"
+            "lit/decorators.js": "https://esm.sh/lit@3/decorators.js"
         }
     }
     </script>

store/idb.js

@@ -1,33 +0,0 @@
-// 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),
-  }
-}

store/index.js

@@ -1,42 +0,0 @@
-import { createStore } from 'zustand/vanilla'
-import { persist, createJSONStorage } from 'zustand/middleware'
-import { get, set } from 'idb-keyval'
-
-const storage = createJSONStorage(() => ({
-  getItem: async (name) => {
-    const value = await get(name)
-    return value ?? null
-  },
-  setItem: async (name, value) => {
-    await set(name, value)
-  },
-  removeItem: async (name) => {
-    await del(name)
-  },
-}))
-
-export const store = createStore(
-  persist(
-    (set, get) => ({
-      _hydrated: false,
-      user: null,
-      items: [],
-      route: 'home',
-      setUser: (user) => set({ user }),
-      addItem: (item) => set(s => ({ items: [...s.items, item] })),
-      removeItem: (id) => set(s => ({ items: s.items.filter(i => i.id !== id) })),
-      navigate: (route) => set({ route }),
-    }),
-    {
-      name: 'app-store',
-      storage,
-      onRehydrateStorage: () => {
-        return (state, error) => {
-          if (!error) {
-            store.setState({ _hydrated: true })
-          }
-        }
-      },
-    }
-  )
-)

store/middleware/persistence.js

@@ -1,9 +0,0 @@
-// 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),
-  }))