chore(04): commit pattern map + session config; ignore intel/graph diff baselines
This commit is contained in:
Lucas Berger
@@ -0,0 +1,749 @@
|
||||
# Phase 4: Shared Lists + Live Sync — Pattern Map
|
||||
|
||||
**Mapped:** 2026-06-09
|
||||
**Files analyzed:** 18 new/modified files
|
||||
**Analogs found:** 16 / 18
|
||||
|
||||
---
|
||||
|
||||
## File Classification
|
||||
|
||||
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
||||
|-------------------|------|-----------|----------------|---------------|
|
||||
| `apps/api/src/db/schema.ts` | model (modify) | CRUD | self | exact |
|
||||
| `apps/api/src/db/migrations/0002_lists_schema.sql` | migration | batch | `0001_calendars_user_url_unique.sql` | role-match |
|
||||
| `apps/api/src/lib/listEmitter.ts` | utility | event-driven | none in codebase | no analog |
|
||||
| `apps/api/src/routes/lists.ts` | route/controller | CRUD | `apps/api/src/routes/events.ts` | exact |
|
||||
| `apps/api/src/routes/sse.ts` | route (modify) | streaming | self | exact |
|
||||
| `apps/api/src/index.ts` | config (modify) | request-response | self | exact |
|
||||
| `apps/pwa/src/App.tsx` | component (modify) | request-response | self | exact |
|
||||
| `apps/pwa/src/components/BottomTabBar.tsx` | component | request-response | `apps/pwa/src/components/AppNav.tsx` | role-match |
|
||||
| `apps/pwa/src/routes/ListsIndex.tsx` | component | CRUD | `apps/pwa/src/components/CalendarShell.tsx` | role-match |
|
||||
| `apps/pwa/src/routes/ListDetail.tsx` | component | CRUD + event-driven | `apps/pwa/src/components/CalendarShell.tsx` | role-match |
|
||||
| `apps/pwa/src/components/ListCard.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
|
||||
| `apps/pwa/src/components/ItemRow.tsx` | component | event-driven | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
|
||||
| `apps/pwa/src/components/AddItemInput.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
|
||||
| `apps/pwa/src/components/CreateListSheet.tsx` | component | request-response | `apps/pwa/src/components/DeleteConfirmationDialog.tsx` | role-match |
|
||||
| `apps/pwa/src/components/LiveSyncIndicator.tsx` | component | event-driven | none — novel | no analog |
|
||||
| `apps/pwa/src/components/ListsEmptyState.tsx` | component | request-response | `apps/pwa/src/components/SkeletonCalendar.tsx` | role-match |
|
||||
| `apps/pwa/src/hooks/useListSSE.ts` | hook | event-driven | none in codebase | no analog |
|
||||
| `apps/pwa/src/api/listsClient.ts` | utility | request-response | `apps/pwa/src/api/client.ts` | exact |
|
||||
| `apps/pwa/src/store/listsStore.ts` | store | request-response | `apps/pwa/src/store/calendarStore.ts` | exact |
|
||||
|
||||
---
|
||||
|
||||
## Pattern Assignments
|
||||
|
||||
### `apps/api/src/db/schema.ts` (model, CRUD — append new tables)
|
||||
|
||||
**Analog:** self — read `apps/api/src/db/schema.ts` lines 1–163 in full above.
|
||||
|
||||
**Imports pattern** (lines 1–13):
|
||||
```typescript
|
||||
import {
|
||||
mysqlTable,
|
||||
varchar,
|
||||
int,
|
||||
timestamp,
|
||||
boolean,
|
||||
index,
|
||||
unique,
|
||||
} from 'drizzle-orm/mysql-core'
|
||||
```
|
||||
Note: `mysqlEnum` is imported for `calendarOutbox` but is not needed for list tables. Import only what the new tables use.
|
||||
|
||||
**Table definition pattern** (lines 40–54, `memberCredentials` — simplest table with FK):
|
||||
```typescript
|
||||
export const memberCredentials = mysqlTable(
|
||||
'member_credentials',
|
||||
{
|
||||
id: int().primaryKey().autoincrement(),
|
||||
userId: int('user_id')
|
||||
.notNull()
|
||||
.references(() => users.id, { onDelete: 'cascade' }),
|
||||
encryptedPassword: text('encrypted_password').notNull(),
|
||||
createdAt: timestamp('created_at').defaultNow().notNull(),
|
||||
updatedAt: timestamp('updated_at').defaultNow().onUpdateNow(),
|
||||
},
|
||||
(t) => [index('idx_member_credentials_user_id').on(t.userId)],
|
||||
)
|
||||
```
|
||||
|
||||
**Composite unique key pattern** (lines 61–86, `calendars`):
|
||||
```typescript
|
||||
(t) => [
|
||||
index('idx_calendars_user_id').on(t.userId),
|
||||
unique('uniq_calendar_user_url').on(t.userId, t.url),
|
||||
]
|
||||
```
|
||||
|
||||
**New tables to append** — follow the schema from RESEARCH.md §Database Schema Design exactly:
|
||||
- `lists` — int PK, `owner_id` FK to `users`, `name varchar(255)`, `is_shared boolean DEFAULT true`, `created_at`, `updated_at`; index on `owner_id`
|
||||
- `listShares` — int PK, `list_id` FK to `lists` cascade, `user_id` FK to `users` cascade, `created_at`; unique on `(list_id, user_id)`, index on `user_id`
|
||||
- `listItems` — int PK, `list_id` FK to `lists` cascade, `text varchar(500)`, `checked boolean DEFAULT false`, `rank varchar(255)`, `created_at`, `updated_at`; composite index on `(list_id, rank)`, index on `(list_id, checked)`
|
||||
|
||||
---
|
||||
|
||||
### `apps/api/src/routes/lists.ts` (route, CRUD)
|
||||
|
||||
**Analog:** `apps/api/src/routes/events.ts` (full file above)
|
||||
|
||||
**File header doc-block pattern** (lines 1–22 of events.ts):
|
||||
```typescript
|
||||
/**
|
||||
* Lists router — list + item CRUD with SSE fan-out trigger.
|
||||
*
|
||||
* Security:
|
||||
* - All endpoints resolve currentUserId via resolveUserId (returns null → 401).
|
||||
* - Access control: list must be owned by currentUser OR appear in list_shares.
|
||||
* - Drizzle parameterized queries prevent SQL injection.
|
||||
* - zod validates all write payloads (name max 255, text max 500).
|
||||
*
|
||||
* Mounted under /api/* in index.ts — behind oidcAuthMiddleware.
|
||||
*/
|
||||
```
|
||||
|
||||
**Imports pattern** (lines 24–37 of events.ts):
|
||||
```typescript
|
||||
import { Hono } from 'hono'
|
||||
import { zValidator } from '@hono/zod-validator'
|
||||
import { z } from 'zod'
|
||||
import { and, or, eq } from 'drizzle-orm'
|
||||
import { db } from '../db/client.js'
|
||||
import { lists, listItems, listShares, users } from '../db/schema.js'
|
||||
import { getAuth } from '../auth/middleware.js'
|
||||
import { upsertUser, deriveDisplayName } from '../auth/user.js'
|
||||
import { publishListEvent } from '../lib/listEmitter.js'
|
||||
import '../auth/devBypass.js'
|
||||
|
||||
export const listsRouter = new Hono()
|
||||
```
|
||||
|
||||
**`resolveUserId` helper** — copy verbatim from `events.ts` lines 59–76. This function is duplicated per router (not extracted to a shared module) — maintain that pattern.
|
||||
|
||||
**Zod schema pattern** (lines 82–105 of events.ts):
|
||||
```typescript
|
||||
const createListSchema = z.object({
|
||||
name: z.string().min(1).max(255),
|
||||
isShared: z.boolean().default(true),
|
||||
})
|
||||
|
||||
const createItemSchema = z.object({
|
||||
text: z.string().min(1).max(500),
|
||||
})
|
||||
|
||||
// Per-field PATCH — enforce exactly one field per D-08
|
||||
const patchItemSchema = z
|
||||
.object({
|
||||
checked: z.boolean(),
|
||||
text: z.string().min(1).max(500),
|
||||
position: z.string().min(1).max(255),
|
||||
})
|
||||
.partial()
|
||||
.refine((obj) => Object.keys(obj).length === 1, {
|
||||
message: 'PATCH must update exactly one field',
|
||||
})
|
||||
```
|
||||
|
||||
**Route handler pattern** — GET with auth + access check + try/catch (lines 122–221 of events.ts):
|
||||
```typescript
|
||||
listsRouter.get('/', async (c) => {
|
||||
const currentUserId = await resolveUserId(c)
|
||||
if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)
|
||||
|
||||
try {
|
||||
// SELECT lists WHERE owner_id = ? OR id IN (SELECT list_id FROM list_shares WHERE user_id = ?)
|
||||
const rows = await db
|
||||
.select({ /* ... */ })
|
||||
.from(lists)
|
||||
.where(or(eq(lists.ownerId, currentUserId), /* join with listShares */ ))
|
||||
|
||||
return c.json({ lists: rows })
|
||||
} catch (err) {
|
||||
console.error('[lists] DB query failed:', err)
|
||||
return c.json({ error: 'Service unavailable' }, 503)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**Fan-out trigger pattern** — call after every successful write:
|
||||
```typescript
|
||||
// After insert/update/delete succeeds:
|
||||
publishListEvent(listId, { type: 'item:added', listId, payload: newItem })
|
||||
```
|
||||
|
||||
**Ownership verification pattern** (lines 326–339 of events.ts):
|
||||
```typescript
|
||||
// Verify list access before any item mutation
|
||||
const [listRow] = await db
|
||||
.select({ ownerId: lists.ownerId })
|
||||
.from(lists)
|
||||
.where(eq(lists.id, listId))
|
||||
|
||||
if (!listRow) return c.json({ error: 'Not found' }, 404)
|
||||
|
||||
const isOwner = listRow.ownerId === currentUserId
|
||||
const [shareRow] = isOwner ? [{}] : await db
|
||||
.select({ listId: listShares.listId })
|
||||
.from(listShares)
|
||||
.where(and(eq(listShares.listId, listId), eq(listShares.userId, currentUserId)))
|
||||
|
||||
if (!isOwner && !shareRow) return c.json({ error: 'Access denied' }, 403)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/api/src/routes/sse.ts` (route, streaming — extend existing)
|
||||
|
||||
**Analog:** self — `apps/api/src/routes/sse.ts` lines 1–40 (full file above).
|
||||
|
||||
**Core streamSSE pattern** (lines 28–40):
|
||||
```typescript
|
||||
sseRouter.get('/heartbeat', (c) => {
|
||||
return streamSSE(c, async (stream) => {
|
||||
let id = 0
|
||||
while (!stream.aborted) {
|
||||
await stream.writeSSE({
|
||||
data: JSON.stringify({ ts: new Date().toISOString(), id }),
|
||||
event: 'heartbeat',
|
||||
id: String(id++),
|
||||
})
|
||||
await stream.sleep(10_000)
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
**New `/lists` endpoint** extends this with:
|
||||
- `resolveUserId(c)` call first → 401 on null (same as events.ts pattern)
|
||||
- `getAccessibleListIds(userId)` DB query before `streamSSE` call
|
||||
- `subscribeListEvents(listId, handler)` loop inside `streamSSE`
|
||||
- Heartbeat loop at 30s cadence (not 10s — Pangolin smoke test used 10s for the heartbeat, 30s is fine for production load)
|
||||
- Cleanup: `unsubscribers.forEach(unsub => unsub())` after the while loop exits
|
||||
|
||||
```typescript
|
||||
sseRouter.get('/lists', async (c) => {
|
||||
const userId = await resolveUserId(c)
|
||||
if (!userId) return c.json({ error: 'Unauthorized' }, 401)
|
||||
|
||||
const accessibleListIds = await getAccessibleListIds(userId)
|
||||
|
||||
return streamSSE(c, async (stream) => {
|
||||
const unsubscribers: Array<() => void> = []
|
||||
|
||||
for (const listId of accessibleListIds) {
|
||||
const unsub = subscribeListEvents(listId, async (event) => {
|
||||
if (stream.aborted) return
|
||||
await stream.writeSSE({
|
||||
data: JSON.stringify(event),
|
||||
event: event.type,
|
||||
id: `${listId}-${Date.now()}`,
|
||||
})
|
||||
})
|
||||
unsubscribers.push(unsub)
|
||||
}
|
||||
|
||||
let tick = 0
|
||||
while (!stream.aborted) {
|
||||
await stream.writeSSE({
|
||||
data: JSON.stringify({ ts: new Date().toISOString() }),
|
||||
event: 'heartbeat',
|
||||
id: String(tick++),
|
||||
})
|
||||
await stream.sleep(30_000)
|
||||
}
|
||||
|
||||
unsubscribers.forEach((unsub) => unsub())
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/api/src/lib/listEmitter.ts` (utility, event-driven)
|
||||
|
||||
**No codebase analog** — this is new. Use the pattern from RESEARCH.md Finding 1 verbatim:
|
||||
|
||||
```typescript
|
||||
import { EventEmitter } from 'node:events'
|
||||
|
||||
const emitter = new EventEmitter()
|
||||
emitter.setMaxListeners(200)
|
||||
|
||||
export type ListEvent = {
|
||||
type: 'item:added' | 'item:updated' | 'item:deleted' | 'list:updated' | 'list:deleted'
|
||||
listId: number
|
||||
payload: unknown
|
||||
}
|
||||
|
||||
export function publishListEvent(listId: number, event: ListEvent): void {
|
||||
emitter.emit(`list:${listId}`, event)
|
||||
}
|
||||
|
||||
export function subscribeListEvents(
|
||||
listId: number,
|
||||
handler: (event: ListEvent) => void,
|
||||
): () => void {
|
||||
const channel = `list:${listId}`
|
||||
emitter.on(channel, handler)
|
||||
return () => emitter.off(channel, handler)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/api/src/index.ts` (config, modify)
|
||||
|
||||
**Analog:** self — lines 1–83 (full file above).
|
||||
|
||||
**Route mount pattern** (lines 59–61):
|
||||
```typescript
|
||||
app.route('/api/me', meRouter)
|
||||
app.route('/api/events', eventsRouter)
|
||||
app.route('/api/sse', sseRouter)
|
||||
```
|
||||
|
||||
**Add after `sseRouter` mount:**
|
||||
```typescript
|
||||
import { listsRouter } from './routes/lists.js'
|
||||
// ...
|
||||
app.route('/api/lists', listsRouter)
|
||||
```
|
||||
|
||||
**Auto-migrate pattern** — add before `startBrokerPoller()` (line 65):
|
||||
```typescript
|
||||
import { migrate } from 'drizzle-orm/mysql2/migrator'
|
||||
// ...
|
||||
await migrate(db, { migrationsFolder: './src/db/migrations' })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/App.tsx` (component, modify)
|
||||
|
||||
**Analog:** self — lines 1–5 (full file above). Currently a one-liner.
|
||||
|
||||
**Transform to** (pattern from RESEARCH.md Finding 5):
|
||||
```tsx
|
||||
import { BrowserRouter, Routes, Route, Navigate } from 'react-router'
|
||||
import { CalendarShell } from './components/CalendarShell.js'
|
||||
import { ListsIndex } from './routes/ListsIndex.js'
|
||||
import { ListDetail } from './routes/ListDetail.js'
|
||||
import { BottomTabBar } from './components/BottomTabBar.js'
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<BrowserRouter>
|
||||
<AppShell />
|
||||
</BrowserRouter>
|
||||
)
|
||||
}
|
||||
|
||||
function AppShell() {
|
||||
return (
|
||||
<>
|
||||
<Routes>
|
||||
<Route path="/" element={<Navigate to="/calendar" replace />} />
|
||||
<Route path="/calendar" element={<CalendarShell />} />
|
||||
<Route path="/lists" element={<ListsIndex />} />
|
||||
<Route path="/lists/:listId" element={<ListDetail />} />
|
||||
</Routes>
|
||||
<BottomTabBar />
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/components/BottomTabBar.tsx` (component, request-response)
|
||||
|
||||
**Analog:** `apps/pwa/src/components/AppNav.tsx` (nav component with active-state links — check that file if needed for CSS token conventions)
|
||||
|
||||
**Key pattern** — NavLink with isActive callback (from RESEARCH.md Finding 5):
|
||||
```tsx
|
||||
import { NavLink } from 'react-router'
|
||||
import { CalendarDays, List } from 'lucide-react'
|
||||
|
||||
export function BottomTabBar() {
|
||||
return (
|
||||
<nav
|
||||
style={{
|
||||
position: 'fixed',
|
||||
bottom: 0,
|
||||
left: 0,
|
||||
right: 0,
|
||||
height: '56px',
|
||||
display: 'flex',
|
||||
background: 'var(--color-surface)',
|
||||
borderTop: '1px solid var(--color-border)',
|
||||
zIndex: 100,
|
||||
}}
|
||||
>
|
||||
<NavLink
|
||||
to="/calendar"
|
||||
className={({ isActive }) => isActive ? 'tab tab--active' : 'tab'}
|
||||
>
|
||||
<CalendarDays size={22} aria-hidden="true" />
|
||||
<span>Calendar</span>
|
||||
</NavLink>
|
||||
<NavLink
|
||||
to="/lists"
|
||||
className={({ isActive }) => isActive ? 'tab tab--active' : 'tab'}
|
||||
>
|
||||
<List size={22} aria-hidden="true" />
|
||||
<span>Lists</span>
|
||||
</NavLink>
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
CSS tokens: use `var(--color-surface)`, `var(--color-border)`, `var(--color-text-primary)`, `var(--color-text-secondary)` — the existing token layer from Phase 2.
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/api/listsClient.ts` (utility, request-response)
|
||||
|
||||
**Analog:** `apps/pwa/src/api/client.ts` lines 1–53 (full pattern above).
|
||||
|
||||
**Imports + credential pattern**:
|
||||
```typescript
|
||||
// credentials: 'include' on every fetch — session cookie required (same as client.ts)
|
||||
const BASE = '/api'
|
||||
|
||||
async function apiFetch(path: string, init?: RequestInit): Promise<Response> {
|
||||
const res = await fetch(`${BASE}${path}`, {
|
||||
credentials: 'include',
|
||||
...init,
|
||||
})
|
||||
if (!res.ok) throw new Error(`${init?.method ?? 'GET'} ${path} failed: ${res.status}`)
|
||||
return res
|
||||
}
|
||||
```
|
||||
|
||||
**Type + function pattern** (mirrors client.ts):
|
||||
```typescript
|
||||
export interface List {
|
||||
id: number
|
||||
name: string
|
||||
isShared: boolean
|
||||
ownerId: number
|
||||
}
|
||||
|
||||
export interface ListItem {
|
||||
id: number
|
||||
listId: number
|
||||
text: string
|
||||
checked: boolean
|
||||
rank: string
|
||||
}
|
||||
|
||||
export async function fetchLists(): Promise<{ lists: List[] }> {
|
||||
return apiFetch('/lists').then((r) => r.json())
|
||||
}
|
||||
|
||||
export async function createList(payload: { name: string; isShared: boolean }): Promise<{ id: number }> {
|
||||
return apiFetch('/lists', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(payload),
|
||||
}).then((r) => r.json())
|
||||
}
|
||||
|
||||
export async function patchListItem(
|
||||
itemId: number,
|
||||
patch: { checked?: boolean } | { text: string } | { position: string },
|
||||
): Promise<void> {
|
||||
await apiFetch(`/list-items/${itemId}`, {
|
||||
method: 'PATCH',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify(patch),
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/store/listsStore.ts` (store, request-response)
|
||||
|
||||
**Analog:** `apps/pwa/src/store/calendarStore.ts` lines 1–89 (full file above).
|
||||
|
||||
**Imports + create pattern** (lines 26–27 of calendarStore.ts):
|
||||
```typescript
|
||||
import { create } from 'zustand'
|
||||
|
||||
export interface ListsStore {
|
||||
// UI-only state — no server data
|
||||
activeTab: 'calendar' | 'lists'
|
||||
createListSheetOpen: boolean
|
||||
// ...
|
||||
|
||||
setActiveTab: (tab: 'calendar' | 'lists') => void
|
||||
setCreateListSheetOpen: (open: boolean) => void
|
||||
}
|
||||
|
||||
export const useListsStore = create<ListsStore>()((set) => ({
|
||||
activeTab: 'calendar',
|
||||
createListSheetOpen: false,
|
||||
setActiveTab: (tab) => set({ activeTab: tab }),
|
||||
setCreateListSheetOpen: (open) => set({ createListSheetOpen: open }),
|
||||
}))
|
||||
```
|
||||
|
||||
Convention from calendarStore.ts: no `persist` middleware used in this project — state is ephemeral (view persistence done manually with localStorage in calendarStore; lists UI state does not need persistence).
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/routes/ListsIndex.tsx` (component, CRUD)
|
||||
|
||||
**Analog:** `apps/pwa/src/components/CalendarShell.tsx` lines 1–60 (header shown above).
|
||||
|
||||
**Data fetching pattern** — useQuery with credentials (from CalendarShell + client.ts):
|
||||
```tsx
|
||||
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
|
||||
import { fetchLists, createList, deleteList } from '../api/listsClient.js'
|
||||
|
||||
const { data, isLoading, isError } = useQuery({
|
||||
queryKey: ['lists'],
|
||||
queryFn: fetchLists,
|
||||
})
|
||||
```
|
||||
|
||||
**State branches** — mirror CalendarShell: `isLoading` → skeleton/empty, `isError` → error state with retry, `data` → render list. CalendarShell uses `isLoading` / `isError` / success branches explicitly.
|
||||
|
||||
**useMutation with optimistic update** (from RESEARCH.md Finding 6):
|
||||
```tsx
|
||||
const queryClient = useQueryClient()
|
||||
|
||||
const deleteMutation = useMutation({
|
||||
mutationFn: (listId: number) => deleteList(listId),
|
||||
onMutate: async (listId) => {
|
||||
await queryClient.cancelQueries({ queryKey: ['lists'] })
|
||||
const previous = queryClient.getQueryData(['lists'])
|
||||
queryClient.setQueryData(['lists'], (old: any) => ({
|
||||
...old,
|
||||
lists: old.lists.filter((l: any) => l.id !== listId),
|
||||
}))
|
||||
return { previous }
|
||||
},
|
||||
onError: (_err, _vars, context) => {
|
||||
if (context?.previous) queryClient.setQueryData(['lists'], context.previous)
|
||||
},
|
||||
onSettled: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ['lists'] })
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
**DeleteConfirmationDialog reuse** — import from `../components/DeleteConfirmationDialog.js` and render conditionally. The existing dialog is tightly coupled to `calendarStore`; create a new list-delete confirmation component (`ListDeleteDialog`) that mirrors its structure but is driven by `listsStore`. Do NOT modify the existing dialog — it is stable (D-06 says reuse, but the implementation is wired to calendarStore).
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/routes/ListDetail.tsx` (component, CRUD + event-driven)
|
||||
|
||||
**Analog:** `apps/pwa/src/components/CalendarShell.tsx`
|
||||
|
||||
**SSE + polling pattern** (from RESEARCH.md Finding 4):
|
||||
```tsx
|
||||
import { useListSSE } from '../hooks/useListSSE.js'
|
||||
|
||||
const { data } = useQuery({
|
||||
queryKey: ['list', listId],
|
||||
queryFn: () => fetchListItems(listId),
|
||||
refetchInterval: 30_000, // D-12: polling fallback always active
|
||||
})
|
||||
|
||||
useListSSE({ listId, onStateChange: setSyncState })
|
||||
```
|
||||
|
||||
**Active / completed section split** (D-05):
|
||||
```tsx
|
||||
const activeItems = items.filter((i) => !i.checked).sort(/* by rank ASC */)
|
||||
const completedItems = items.filter((i) => i.checked)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (reuse — no modification)
|
||||
|
||||
**This file is not modified.** A new `ListDeleteDialog.tsx` mirrors its structure:
|
||||
- Same modal layout: fixed backdrop + centered dialog
|
||||
- Same CSS tokens: `var(--color-overlay)`, `var(--color-surface-raised)`, `var(--color-destructive)`, `var(--space-*)`, `var(--text-*)`, `var(--font-family-base)`
|
||||
- Same `useMutation` + `onSuccess` → close pattern (lines 64–76 of DeleteConfirmationDialog.tsx)
|
||||
- Same accessibility: `role="dialog"`, `aria-modal="true"`, Escape key listener, `tabIndex={-1}` + focus on open
|
||||
|
||||
Key lines to copy for the modal skeleton (lines 86–208 of DeleteConfirmationDialog.tsx) — swap the heading text to "Delete list?" and the body text to "All items in this list will be permanently deleted."
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/components/ItemRow.tsx` (component, event-driven)
|
||||
|
||||
**Analog:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (for mutation + CSS token patterns)
|
||||
|
||||
**dnd-kit drag handle pattern** (from RESEARCH.md Finding 7):
|
||||
```tsx
|
||||
import { useSortable } from '@dnd-kit/sortable'
|
||||
import { CSS } from '@dnd-kit/utilities'
|
||||
import { GripVertical } from 'lucide-react'
|
||||
|
||||
export function ItemRow({ item, onCheck, onDelete }) {
|
||||
const { attributes, listeners, setNodeRef, transform, transition, isDragging } =
|
||||
useSortable({ id: item.id })
|
||||
|
||||
return (
|
||||
<div
|
||||
ref={setNodeRef}
|
||||
style={{
|
||||
transform: CSS.Transform.toString(transform),
|
||||
transition: transition ?? 'transform 150ms ease-out', // D-14: animate remote reorders
|
||||
opacity: isDragging ? 0.8 : 1,
|
||||
display: 'flex',
|
||||
alignItems: 'center',
|
||||
gap: 'var(--space-2)',
|
||||
minHeight: '44px', // touch target
|
||||
}}
|
||||
{...attributes}
|
||||
>
|
||||
{/* Drag handle — listeners on handle only (not whole row) */}
|
||||
<button
|
||||
{...listeners}
|
||||
aria-label="Drag to reorder"
|
||||
style={{ background: 'none', border: 'none', cursor: 'grab', padding: 'var(--space-1)' }}
|
||||
>
|
||||
<GripVertical size={16} color="var(--color-text-secondary)" />
|
||||
</button>
|
||||
{/* ... checkbox, text, delete button */}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `apps/pwa/src/hooks/useListSSE.ts` (hook, event-driven)
|
||||
|
||||
**No codebase analog.** Use the pattern from RESEARCH.md Finding 4 verbatim. Key conventions:
|
||||
- `useCallback` for `connect` to keep the `useEffect` dependency stable
|
||||
- `esRef`, `attemptsRef`, `timerRef` — all `useRef` (not state) to avoid re-render loops
|
||||
- Close `es` on error before scheduling retry (prevents browser auto-reconnect stacking with manual reconnect)
|
||||
- `withCredentials: true` on `new EventSource(...)` — required for session cookie (Pitfall 7)
|
||||
- Return `syncState` so the caller can render `LiveSyncIndicator`
|
||||
|
||||
---
|
||||
|
||||
## Shared Patterns
|
||||
|
||||
### Auth / User Resolution
|
||||
**Source:** `apps/api/src/routes/events.ts` lines 59–76
|
||||
**Apply to:** `apps/api/src/routes/lists.ts`
|
||||
```typescript
|
||||
async function resolveUserId(c: any): Promise<number | null> {
|
||||
const devUser = c.get('user') as { id: number } | undefined
|
||||
if (devUser) return devUser.id
|
||||
|
||||
const auth = await getAuth(c)
|
||||
if (!auth) return null
|
||||
|
||||
const iss = (auth.iss as string | undefined) ?? ''
|
||||
const sub = auth.sub ?? ''
|
||||
const displayName = deriveDisplayName(auth)
|
||||
const user = await upsertUser(iss, sub, displayName)
|
||||
return user?.id ?? null
|
||||
}
|
||||
```
|
||||
Copy verbatim — do not extract to a shared module (existing convention duplicates this per router).
|
||||
|
||||
### Error Handling (API routes)
|
||||
**Source:** `apps/api/src/routes/events.ts` (every handler's catch block)
|
||||
**Apply to:** `apps/api/src/routes/lists.ts`
|
||||
```typescript
|
||||
try {
|
||||
// ... db operations ...
|
||||
return c.json({ /* result */ })
|
||||
} catch (err) {
|
||||
console.error('[lists/<endpoint>] DB operation failed:', err)
|
||||
return c.json({ error: 'Service unavailable' }, 503)
|
||||
}
|
||||
```
|
||||
Pattern: 503 on caught exceptions, not 500. `console.error` with a `[module/endpoint]` prefix tag.
|
||||
|
||||
### 401 Guard Pattern
|
||||
**Source:** `apps/api/src/routes/events.ts` (every handler, lines 125–126):
|
||||
```typescript
|
||||
const currentUserId = await resolveUserId(c)
|
||||
if (currentUserId === null) return c.json({ error: 'Unauthorized' }, 401)
|
||||
```
|
||||
First two lines of every protected handler.
|
||||
|
||||
### CSS Token Usage (PWA components)
|
||||
**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (all inline styles)
|
||||
**Apply to:** all new PWA components
|
||||
Token set in use:
|
||||
- `var(--color-surface)`, `var(--color-surface-raised)`, `var(--color-overlay)`
|
||||
- `var(--color-text-primary)`, `var(--color-text-secondary)`
|
||||
- `var(--color-destructive)`, `var(--color-border)`
|
||||
- `var(--space-1)` through `var(--space-6)`
|
||||
- `var(--text-body-size)`, `var(--text-heading-size)`, `var(--text-label-size)`, `var(--font-family-base)`
|
||||
- Minimum touch target: `minHeight: '44px'` (buttons/rows)
|
||||
|
||||
### Fetch with Credentials (PWA API client)
|
||||
**Source:** `apps/pwa/src/api/client.ts` lines 36–39
|
||||
**Apply to:** `apps/pwa/src/api/listsClient.ts`
|
||||
```typescript
|
||||
const res = await fetch('/api/...', {
|
||||
credentials: 'include',
|
||||
redirect: 'manual', // only for /api/me; not required for data endpoints
|
||||
})
|
||||
```
|
||||
All list API calls use `credentials: 'include'`. `redirect: 'manual'` is only needed for the initial session check (`/api/me`) — not for list CRUD endpoints.
|
||||
|
||||
### TanStack Query Keys
|
||||
**Apply to:** `apps/pwa/src/routes/ListsIndex.tsx`, `apps/pwa/src/routes/ListDetail.tsx`
|
||||
```typescript
|
||||
// List of lists
|
||||
queryKey: ['lists']
|
||||
|
||||
// Items for a specific list
|
||||
queryKey: ['list', listId] // listId is a number
|
||||
```
|
||||
Invalidate `['lists']` after create/delete list. Invalidate `['list', listId]` after any item mutation or SSE event for that list.
|
||||
|
||||
### Lucide Icons (PWA)
|
||||
**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` line 27, CalendarShell.tsx line 43
|
||||
**Apply to:** all new PWA components
|
||||
```tsx
|
||||
import { Trash2 } from 'lucide-react'
|
||||
// Usage: <Trash2 size={16} aria-hidden="true" />
|
||||
```
|
||||
Always pass `aria-hidden="true"` to decorative icons. Use `size={16}` for inline/dense contexts, `size={22}` for navigation tabs.
|
||||
|
||||
### Zustand Store Shape
|
||||
**Source:** `apps/pwa/src/store/calendarStore.ts`
|
||||
**Apply to:** `apps/pwa/src/store/listsStore.ts`
|
||||
- Use `create<StoreInterface>()((set) => ({ ... }))` — no `persist`, no `immer`
|
||||
- Actions are inline setter functions, not separate files
|
||||
- UI-only state: no server data, no async in store actions (mutations live in components via `useMutation`)
|
||||
|
||||
### Plain-text XSS Guard (PWA)
|
||||
**Source:** `apps/pwa/src/components/DeleteConfirmationDialog.tsx` (comment `/* Plain text — XSS guard */` on every text node, line 133 etc.)
|
||||
**Apply to:** all new PWA components that render user-supplied strings (list names, item text)
|
||||
Never use `dangerouslySetInnerHTML`. All user content is a JSX text child.
|
||||
|
||||
---
|
||||
|
||||
## No Analog Found
|
||||
|
||||
| File | Role | Data Flow | Reason |
|
||||
|------|------|-----------|--------|
|
||||
| `apps/api/src/lib/listEmitter.ts` | utility | event-driven | No EventEmitter or pub/sub pattern exists in the codebase. Use RESEARCH.md Finding 1 pattern. |
|
||||
| `apps/pwa/src/components/LiveSyncIndicator.tsx` | component | event-driven | No live-sync state indicator exists. Novel UI component — use CSS token conventions and the "disconnected / updates paused" UX from D-11. |
|
||||
| `apps/pwa/src/hooks/useListSSE.ts` | hook | event-driven | No custom hooks exist in the codebase. Novel — use RESEARCH.md Finding 4 pattern. |
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
**Analog search scope:** `apps/api/src/routes/`, `apps/api/src/db/`, `apps/api/src/lib/`, `apps/api/src/index.ts`, `apps/pwa/src/`, `apps/pwa/src/components/`, `apps/pwa/src/api/`, `apps/pwa/src/store/`
|
||||
**Files scanned:** 12 source files read in full
|
||||
**Pattern extraction date:** 2026-06-09
|
||||
Reference in New Issue
Block a user