reactive-sqlite-ui

name	reactive-sqlite-ui
description	Build SQLite-backed reactive UI in `apps/desktop` using stable patterns for reads, selection, forms, writes, and loading states. Use when implementing or reviewing screens built on `useDrizzleLiveQuery` and SQLite mutations.

Goal

Use SQLite live queries as the screen data source without duplicating subscriptions, fighting the reactivity model, or making selection and form state unstable.

Patterns

1. Screen Boundary Query

• Subscribe once per resource domain at the screen boundary.
• Pass derived data downward.
• Open another live query only when the child truly needs different data.

const items = useItems();
const selectedItem = items.find((item) => item.id === selectedId) ?? null;

2. Selection Is UI State

• Keep selection in tab/zustand/local UI state as an id or index.
• Do not model selection as a second live query.
• Resolve the selected item from the already-loaded collection when possible.

3. Detail Pane From Snapshot

• Pass the selected object into detail components.
• Key detail forms by entity id only when you want local state reset on entity switch.
• Preserve visible data across normal selection changes.

This is the main anti-flicker pattern.

4. Forms Own Draft State

• Reactive query data is the source for persisted state.
• The form owns draft state while editing.
• Reset form state when the entity changes, not on every reactive payload.

5. Writes Flow One Way

• Reads: useDrizzleLiveQuery(db.select()...)
• Imperative reads: helper/query outside the render path
• Writes: db.insert, db.update, db.delete inside useMutation
• Let SQLite change notifications update subscribed UI

Do not add manual invalidation unless the write affects data outside the subscribed query graph.

6. Loading States Are Scoped

• Show loading UI for initial screen load.
• Do not blank the detail pane for ordinary selection changes.
• Prefer preserving previous data until the next snapshot when query args change frequently.

Anti-Patterns

• Parent list query plus child selected-row query for the same table
• Child components that take id and immediately subscribe again
• Resetting detail data to undefined during normal selection changes
• Form resets tied to every incoming reactive payload
• Mixing imperative local cache invalidation with SQLite live-query updates

Review Check

• Is there more than one live query for the same resource on the same screen?
• Can the detail view render from the parent snapshot?
• Does entity change reset the form, while ordinary reactive updates do not?
• Is loading UI limited to initial load or truly missing data?
• Are writes relying on the live-query loop instead of manual sync?