akadmin/zulip
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

finished pruning for lit-only demo

Browse source
This commit is contained in:
authentik Default Admin 2026-03-04 14:18:44 -08:00
parent 648412dd6d
commit 3736d7278b
10 changed files with 217 additions and 281 deletions
Download patch file Download diff file Expand all files Collapse all files

266
README.md
View file

@ -1,168 +1,113 @@
# Lit + Zustand Architecture
# Lit-Only Architecture (No Build)
A simple (but modern & scalable) no-build web application architecture using Lit web components with Zustand state management and IndexedDB persistence.
A minimal, no-build web application using only Lit web components with local state management.
> **Note:** This is the `lit-only` branch. For the full-featured version with Zustand state management and IndexedDB persistence, see the `main` branch.
## For TSX/React Developers
If you're coming from React/TSX, here's how this architecture maps to familiar concepts:
If you're coming from React/TSX, here's how this minimal 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 |
| `useState` | Lit's `static properties` with `state: true` |
| Props drilling | Property passing via `.prop=${value}` |
| Custom events | `CustomEvent` with `bubbles: true` |
| 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 |
| React Router | Simple route state in root component |
| 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>\``
3. **Local State Only**: Each component manages its own state, parent manages shared state
4. **Event-Based Communication**: Child components emit events, parent handles them
5. **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
* **Local state management** - Component properties and state
* **Event-driven** - CustomEvents for child-to-parent communication
## Layout
## Project Structure
```
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>)
components/
app-root.js ← Root component with shared state
nav-bar.js ← Navigation component
page-home.js ← Home page component
page-items.js ← Items page component
index.html ← Entry point with inline importmap
README.md
tasks.md
```
## Data Flow Diagrams
## Data Flow Pattern
### Component-to-Store Pattern
### Parent-to-Child (Props)
```mermaid
sequenceDiagram
participant User
participant LitComponent
participant StoreController
participant ZustandStore
participant IndexedDB
```javascript
// Parent passes data down
html`<child-component .items=${this.items}></child-component>`
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
// Child receives via properties
static properties = {
items: { type: Array }
}
```
### Store Subscription Pattern
### 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>`
```
## State Management 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]
A[app-root] -->|.user, .items, .route| B[nav-bar]
A -->|.user, .items| C[page-home]
A -->|.items| D[page-items]
B -->|@navigate event| A
D -->|@add-item event| A
D -->|@remove-item event| A
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 │
└─────────────────────────────────────────┘
style C fill:#bfb,stroke:#333,stroke-width:2px
style D fill:#bfb,stroke:#333,stroke-width:2px
```
## 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 +116,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,7 +128,7 @@ class Counter extends LitElement {
customElements.define('my-counter', Counter)
```
### 3. Use in HTML (no build step!)
### 2. Use in HTML (no build step!)
```html
<!DOCTYPE html>
@ -192,9 +137,7 @@ customElements.define('my-counter', Counter)
<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"
"lit": "https://esm.sh/lit@3"
}
}
</script>
@ -206,17 +149,88 @@ customElements.define('my-counter', Counter)
</html>
```
## Component Communication Patterns
### Pattern 1: Shared State in Root
```javascript
class AppRoot extends LitElement {
static properties = {
items: { type: Array, state: true }
}
constructor() {
super()
this.items = []
}
addItem(item) {
this.items = [...this.items, item]
}
render() {
return html`
<child-component
.items=${this.items}
@add=${(e) => this.addItem(e.detail.item)}
></child-component>
`
}
}
```
### Pattern 2: Local State in Component
```javascript
class MyComponent extends LitElement {
static properties = {
_draft: { type: String, state: true }
}
constructor() {
super()
this._draft = ''
}
render() {
return html`
<input
.value=${this._draft}
@input=${e => this._draft = e.target.value}
/>
`
}
}
```
## Benefits Over React/TSX
✅ **No build step** - Edit and refresh, instant feedback
✅ **Minimal dependencies** - Just Lit, nothing else
✅ **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
✅ **Easy to learn** - Simple mental model, no complex state management
## When to Use This vs. Full Stack
### Use Lit-Only When:
- Building small to medium apps
- Don't need persistence
- State is simple and hierarchical
- Want maximum simplicity
### Use Full Stack (main branch) When:
- Need IndexedDB persistence
- Complex state shared across many components
- Need cross-tab synchronization
- Want time-travel debugging
- Building larger applications
## 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)
- [Import Maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap)