# Fase 18 — Shopping list creation flow (required title + auto-numbered prefix + autocomplete + defaults)

**v1.0 · 2/4. Second pass of the v1.0 cycle.**

**Status: ✅ Shipped 2026-05-19.**

Four coupled asks on the "I create a new shopping list" moment:

1. **Required title** — no creating without a name; client blocks on empty trim, DB enforces `NOT NULL` (already in migration 005).
2. **Auto-numbered `#N`** — when the typed title matches an admin-curated prefix (e.g. `Compra`), the modal auto-suffixes `#N` with `N = max(N) + 1` from existing lists in the same collective. `#N` is part of the title (column `name`), not a separate column.
3. **Default list title** — admins set a per-collective default that prefills the create-list modal's input.
4. **Curated title catalog** — admins manage a small set of "known prefixes" that drive both the autocomplete dropdown and the auto-suffix decision.

Plan: `plan/fase-18-shopping-list-flow.md`. Migration: `supabase/migrations/027_list_title_catalog.sql`. pgTAP: `supabase/tests/019_list_title_catalog.sql`.

## What changed

### 18.1 — Data model (migration 027 + pgTAP 019)

- `collectives.default_list_title text` (nullable). Empty / NULL means no prefill (current behaviour preserved).
- `collective_list_titles (collective_id, title, created_at)` with composite PK and `ON DELETE CASCADE` from the parent collective. Mirrors the shape of `item_frequency` from Fase 15 — members read via `is_member`, writes are all-deny RLS; the two SECURITY DEFINER RPCs are the only entry points.
- `add_list_title(p_collective_id uuid, p_title text)` — trims, rejects empty (P0001), gates on `collective_members.role = 'admin'` (P0002), inserts with `ON CONFLICT DO NOTHING` so the UI can call it idempotently.
- `remove_list_title(p_collective_id uuid, p_title text)` — same role check, deletes the row.
- Both `GRANT EXECUTE ... TO authenticated`. PostgREST routes them as RPCs.
- **Realtime**: `collective_list_titles` is added to the `supabase_realtime` publication with `REPLICA IDENTITY FULL` so the manage UI sees admin edits live across tabs/browsers (matches the migration 007 pattern for `shopping_lists` / `shopping_items`).
- pgTAP `019_list_title_catalog.sql` (13 assertions): schema invariants on the column + table, PK shape, RLS posture, policy count, RPC existence + SECURITY DEFINER flag, realtime membership, default-NULL behaviour. The role-gate denial path is covered by the integration suite (postgres bypasses `auth.uid()` inside pgTAP, same caveat as Fase 15's 018).

### 18.2 — Stores + numbering utils (pure module)

- `apps/web/src/lib/utils/list-title.ts` is the pure I/O-free helper:
  - `parseTitle(input)` → `{ prefix, number }`. The regex `^(.+?)\s+#(\d+)$` requires whitespace between prefix and `#`, so `Compra#5` stays literal and bare `#5` returns `prefix: null` (the chip is for catalog-curated prefixes only).
  - `nextNumberFromNumbers(numbers)` → `max(numbers) + 1`, returns `1` for an empty array.
  - `computeNextNumberFromNames(prefix, names)` — case-insensitive prefix match per row, bare-prefix occurrence counts as N=0, no matches returns 1.
- `apps/web/src/lib/stores/listTitles.ts`:
  - `loadTitleCatalog(collectiveId)` and a `listTitleCatalog` writable.
  - `addTitle` / `removeTitle` wrap the RPCs with optimistic store updates.
  - `setDefaultListTitle(collectiveId, value)` is a plain UPDATE on `collectives` — RLS already gates UPDATE to admins.
  - `fetchTitleSuggestions(collectiveId, prefix)` — union of catalog + last 10 distinct `shopping_lists.name`, deduped case-insensitively, capped at 15.
  - `computeNextNumber(collectiveId, basePrefix)` — drives the SQL `or(name.ilike.<prefix>,name.ilike.<prefix> #%)` filter and pipes the row names through the pure helper.
- 19 unit tests on the pure module (covers LT-U-01..05 from the plan plus 7 boundary cases).
- 6 integration tests on the RPC + DB-driven numbering path (LT-INT-01..06).

### 18.3 — Create-list modal (UX shift)

`apps/web/src/lib/components/CreateListModal.svelte` replaces the legacy "click New list → create with empty name → land on detail and rename inline" flow with an explicit modal:

- Input prefilled with `currentCollective.default_list_title || ''`.
- A dropdown of `fetchTitleSuggestions` candidates (debounced 150 ms) and an inline chip `Sugerencia: Compra #6` when the typed value exactly matches a catalog prefix and `computeNextNumber` resolves a value.
- Submit disabled while the trimmed value is empty or creation is in flight.
- On submit, if the catalog match still holds, the modal auto-suffixes `#N` before inserting; the lists page surfaces a transient toast `Creada como "Compra #6"`.

The prefill `$effect` is guarded by a `wasOpen` edge-tracker — a naive `$effect(() => { if (open) value = default })` re-fires whenever `$currentCollective` updates (e.g. a realtime UPDATE landing after the user typed something) and clobbered the typed value. The edge guard limits prefill to the false→true transition.

`/lists/+page.svelte` swaps the old `handleCreate()` handler for `openCreateModal()` and mounts `<CreateListModal />` at the page root. Existing per-list action menus and trash flow are untouched.

### 18.4 — `/collective/manage` "Suggested titles" subsection

Admins see a default-title input (save-on-blur, optimistic patch on `currentCollective`) and a curated catalog list with inline `Remove` per row, plus an "Add title" button that opens a small modal. Members see the same surface read-only — the input is `disabled`, the add button is hidden, and a banner explains "Only admins can curate these titles." Guests don't see the section at all (mirrors the `canSeeCommonItems` gate from Fase 15).

The `$effect` syncing `defaultTitleDraft` from `$currentCollective.default_list_title` is gated by `document.activeElement?.id !== 'default-list-title-input'` so realtime UPDATEs from another tab don't clobber an unsaved local edit.

### 18.5 — E2E coverage

`apps/web/tests/e2e/list-title-flow.test.ts` ships 4 specs:

- **LTF-01** Ana sets `default_list_title` (via `__sb` rather than the manage UI to isolate the modal under test from the section under test); the create modal opens prefilled; submitting yields a list with the prefilled name as-is (no `#N` because the default was never added to the catalog).
- **LTF-02** Ana adds the prefix to the catalog via the manage UI, sets the default via the same UI, then drives the create modal three times — confirms the third list lands as `${prefix} #3`. Exercises the full path: manage RPC → store update → modal auto-suffix on submit.
- **LTF-03** Empty input keeps submit disabled; whitespace-only stays disabled; typing real text enables.
- **LTF-04** Borja (member) opens manage, sees the section, sees the read-only banner, sees no "Add title" button, and the default-title input is `disabled`.

Existing specs adjusted for the new flow: `tests/e2e/lists.test.ts` `createList()` helper + C-13 guest path now drive the modal; `tests/e2e/session.test.ts` S-03 uses the modal for the fresh-list setup.

## Test counts (final)

- **pgTAP**: 191 (was 178; +13)
- **Vitest integration**: 185 (was 179; +6) + 3 skipped (2 Realtime presence — upstream `handle_out/3` bug; 1 rate-limit — gated)
- **Vitest unit**: 75 (was 56; +19)
- **Playwright**: 104 (was 100; +4)
- **Gated rate-limit**: 1 (unchanged)

Total: **555 + 3 skipped** (was 514 + 3).

## Decisions worth remembering

- **The DB is agnostic about #N format.** `shopping_lists.name` stores the final string. The client decides if/when to suffix `#N`. Future formats like `Compra YYYY-MM` won't need a migration.
- **No unique constraint on `(collective_id, name)`.** Two clients racing on `Compra #6` will both succeed and produce two rows with the same name; this is accepted (documented in migration 027 header). A unique constraint would block deliberate duplicates and is rejected.
- **Auto-suffix only fires for catalog matches.** If the typed value doesn't exactly match a catalog entry (case-insensitive), the modal inserts it verbatim — even when `parseTitle` could extract a prefix. This keeps random / one-off names from being silently renamed.
- **Bare `#5` does not trigger autonumbering.** The parser requires a prefix before the hash; bare `#5` returns `{ prefix: null, number: null }` so the chip stays hidden.
- **The default-title input is debounce-free.** Save on blur + Enter, mirroring the collective-name input from Fase 10.2. The catalog list-add uses a modal because we wanted clear "I'm adding a new thing" semantics; a plain input would risk accidentally creating rows on every keystroke.

## Out of scope (deliberately)

- Item templates (lists with pre-loaded items). Just the title.
- Month/year numbering (`Compra 2026-05`). Only `#N` integer.
- Bulk CSV import/export of the catalog. Inline CRUD only.
- Cross-collective suggestions (titles from other collectives a user belongs to).

## Migrations + tests indexed

- `supabase/migrations/027_list_title_catalog.sql`
- `supabase/tests/019_list_title_catalog.sql`
- `apps/web/src/lib/utils/list-title.ts` + `list-title.test.ts`
- `apps/web/src/lib/stores/listTitles.ts`
- `packages/test-utils/tests/list-title-flow.test.ts`
- `apps/web/src/lib/components/CreateListModal.svelte`
- `apps/web/src/routes/(app)/lists/+page.svelte` (wired)
- `apps/web/src/routes/(app)/collective/manage/+page.svelte` (subsection)
- `apps/web/tests/e2e/list-title-flow.test.ts`
- `apps/web/tests/e2e/lists.test.ts` (helper updated for new modal)
- `apps/web/tests/e2e/session.test.ts` (helper updated for new modal)