zulip/README.md

# Lit + Zustand Architecture

A simple (but modern & scalable) no-build web application architecture using Lit web components with Zustand state management and IndexedDB persistence.

## 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)

```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 styles = css`
    button { padding: 1rem; font-size: 1.2rem; }
  `

  render() {
    return html`
      <div>
        <p>Count: ${this.#count.value}</p>
        <button @click=${() => store.getState().increment()}>
          Increment
        </button>
      </div>
    `
  }
}

customElements.define('my-counter', Counter)
```

### 3. Use in HTML (no build step!)

```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"
    }
  }
  </script>
</head>
<body>
  <script type="module" src="components/counter.js"></script>
  <my-counter></my-counter>
</body>
</html>
```

## Benefits Over React/TSX

✅ **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  

## See Also

- [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)