diff --git a/README.md b/README.md index b1fc940..d2e4df2 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,11 @@ # zulip -A modern, no-build web application using Lit web components with Zustand state management. +A minimal, no-build web app kit using only Lit-based web components via importmaps. -## 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 -* **StoreController** - Reactive controller that bridges Zustand and Lit +## Quick Start Example -## 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) +### 1. Define a Component ```javascript // components/counter.js @@ -98,15 +22,16 @@ class Counter extends LitElement { } static styles = css` - button { padding: 1rem; font-size: 1.2rem; margin: 0.5rem; } + button { padding: 1rem; font-size: 1.2rem; } ` render() { return html`
-

Count: ${this.#count.value}

- - +

Count: ${this.count}

+
` } @@ -115,24 +40,53 @@ class Counter extends LitElement { customElements.define('my-counter', Counter) ``` -### 4. Instantiate in parent (such as app-root) +### 2. Use in App root (or other composition node) ```js -import counter from "./counter.js": +import "./my-counter.js"; class AppRoot extends LitElement { + ... render() { - return html` - - `; + return html``; } } ``` +### 3. Define Data Flows + +#### Parent-to-Child (Props) + +```javascript +// Parent passes data down +html`` + +// 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` this.handleAdd(e.detail.item)}>` +``` + ## 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 @@ -141,6 +95,4 @@ class AppRoot extends LitElement { 1. **Future-proof** - Built on web standards -1. **Familiar patterns** - Zustand works like Redux/Context - -1. **Type-safe** - Can add JSDoc or TypeScript without build step +1. **Easy to learn** - Simple mental model for state, with natural evolution into Zustand/IndexedDB or similar extensions diff --git a/TASKS.md b/TASKS.md deleted file mode 100644 index 7a232fe..0000000 --- a/TASKS.md +++ /dev/null @@ -1,66 +0,0 @@ -# Tasks & Issues - -## 1. Critical Issues - -- [x] **1.1 Fix missing `del` import in store/index.js** ✅ COMPLETE - - Line 3 now imports `get, set, del` from idb-keyval - - Used in removeItem function on line 13 - - No more ReferenceError - -- [x] **1.2 Fix hydration flag initialization** ✅ COMPLETE - - Implemented Option A: Initialize `_hydrated: true` by default - - Removed problematic `onRehydrateStorage` callback - - App now loads immediately without hanging on "loading..." - - Persistence happens in background automatically - -- [x] **1.3 Consolidate duplicate storage implementation** ✅ COMPLETE - - Single storage implementation in `store/index.js` - - Uses idb-keyval directly with createJSONStorage - - Clean, simple approach without extra middleware files - -## 2. Architectural Improvements - -- [x] **2.1 Add error handling** ✅ COMPLETE - - Added try/catch blocks around all IndexedDB operations (getItem, setItem, removeItem) - - Implemented fallback: returns null on getItem error, silently fails on setItem/removeItem - - Added error state to store with auto-clear after 3 seconds - - Added validation in addItem and removeItem actions - - Created error-toast component with slide-in animation - - Toast shows error messages and allows manual dismissal - -- [x] **2.2 Add partialize option to persist middleware** ✅ COMPLETE - - Added partialize to exclude `_hydrated` flag from persistence - - Only persists: user, items, and route - - 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 - -- [ ] **3.5 Add Storybook support** - - Introduces parallel build (vite internally) but core app remains no-build - - Storybook includes raw/native web component support - - Ensure individual components and layouts are properly organized, documented, demonstrated, and tested diff --git a/components/app-root.js b/components/app-root.js index 29454ec..88f59a6 100644 --- a/components/app-root.js +++ b/components/app-root.js @@ -1,46 +1,64 @@ import { LitElement, html, css } from "lit"; -import { store} from "../store/index.js"; -import { StoreController } from "../controllers/store-controller.js"; import "./nav-bar.js"; import "./page-home.js"; import "./page-items.js"; -import "./error-toast.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; - } `; + #navigate(route) { + this.route = route; + } + + #addItem(item) { + this.items = [...this.items, item]; + } + + #removeItem(id) { + this.items = this.items.filter(i => i.id !== id); + } + render() { - if (!this.#hydrated.value) { - return html`
loading...
`; - } return html` - + this.#navigate(e.detail.route)} + >
${this.#renderRoute()}
- `; } #renderRoute() { - switch (this.#route.value) { - case "home": return html``; - case "items": return html``; - default: return html``; + 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``; } } } diff --git a/components/error-toast.js b/components/error-toast.js deleted file mode 100644 index 0e90eda..0000000 --- a/components/error-toast.js +++ /dev/null @@ -1,79 +0,0 @@ -// 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 9b44aa2..6f192a1 100644 --- a/components/nav-bar.js +++ b/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-controller.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` this.#navigate(route, e)} >${label} ` @@ -61,4 +62,4 @@ class NavBar extends LitElement { } } -customElements.define('nav-bar', NavBar) \ No newline at end of file +customElements.define('nav-bar', NavBar) diff --git a/components/page-home.js b/components/page-home.js index f6536e7..3d5c616 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 { - #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`

Hey, ${name}

@@ -41,4 +41,4 @@ class PageHome extends LitElement { } } -customElements.define('page-home', PageHome) \ No newline at end of file +customElements.define('page-home', PageHome) diff --git a/components/page-items.js b/components/page-items.js index dde3a1a..f788396 100644 --- a/components/page-items.js +++ b/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-controller.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`

Items

@@ -108,4 +119,4 @@ class PageItems extends LitElement { } } -customElements.define('page-items', PageItems) \ No newline at end of file +customElements.define('page-items', PageItems) diff --git a/controllers/store-controller.js b/controllers/store-controller.js deleted file mode 100644 index 998294d..0000000 --- a/controllers/store-controller.js +++ /dev/null @@ -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?.() } - } \ No newline at end of file diff --git a/index.html b/index.html index 51c53cd..879175b 100644 --- a/index.html +++ b/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" } } diff --git a/store/idb.js b/store/idb.js deleted file mode 100644 index e276f00..0000000 --- a/store/idb.js +++ /dev/null @@ -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), - } -} \ No newline at end of file diff --git a/store/index.js b/store/index.js deleted file mode 100644 index feaea96..0000000 --- a/store/index.js +++ /dev/null @@ -1,86 +0,0 @@ -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 deleted file mode 100644 index bdb7dc1..0000000 --- a/store/persistence.js +++ /dev/null @@ -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), - })) \ No newline at end of file diff --git a/tasks.md b/tasks.md new file mode 100644 index 0000000..edd6904 --- /dev/null +++ b/tasks.md @@ -0,0 +1,60 @@ +# 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