collective-lists/docs/history/fase-19-emoji-avatars.md

# Fase 19 — Emoji avatars expansion (food + animals)

**v1.0 · 3/4. Third pass of the v1.0 cycle.**

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

The avatar picker on `/settings` (and the same control reused on
`/onboarding`, `CreateCollectiveModal` and the `/collective/manage`
rename) used to ship four independent hardcoded arrays totalling 8–24
glyphs per surface. Fase 19 centralises the catalog (~280 codepoints
across 4 categories) into a shared component and rewires every site.

Plan: `plan/fase-19-emoji-avatars.md`. No DB migration.

## What changed

### 19.1 — Catalog (`$lib/data/emoji-catalog.ts`)

- Hardcoded `Record<EmojiCategory, readonly string[]>` with four categories: `faces` (64), `food` (119), `animals` (140), `objects` (36) = **359 codepoints** total. Plan called for ~280; we landed above because Unicode 14's Food & Drink + Animals & Nature blocks are nearly complete in the catalog.
- **Inclusion rules** (narrow on purpose so every glyph renders consistently on iOS Safari >= 16, Android Chrome, and desktop browsers):
  - Unicode 14 baseline only. Excludes Unicode 15+ (e.g. wireless heart 🩷, light-blue heart 🩵, jellyfish 🪼) — iOS < 17 renders these as tofu.
  - No ZWJ sequences. No `👨‍👩‍👧` (family), no `🐕‍🦺` (service dog), no `🏳️‍🌈` (rainbow flag). Two reasons: (a) `users.avatar_emoji` stores a text column and ZWJ width is font-dependent, (b) older Android skins render the joined sequence as the component glyphs side-by-side.
  - No skin-tone variants (`🏻..🏿`) — parked. The base codepoint already renders.
  - Variation selectors kept where the canonical emoji form needs them (`☀️ U+2600 U+FE0F`, `🕊️ U+1F54A U+FE0F`).
- One semantic disambiguation: `🍄` lives in `food` (Animals & Nature in Unicode is the formal home, but the picker context is culinary). Enforced by EC-U-04 which would have surfaced the collision otherwise.
- `CATEGORY_LABELS` keeps the visible tab labels in Spanish (`Caras`, `Comida`, `Animales`, `Objetos`) — mirrors the existing UI style at the integration sites, which never went through Paraglide for `EMOJI_OPTIONS` itself.

### 19.2 — `EmojiPicker.svelte`

- Props: `selected: string | null`, `onSelect: (emoji: string) => void`, optional `onClose?: () => void`. Caller owns the persistence side-effect.
- Layout: tablist header (`role="tablist"`, 4 buttons) + body grid (`role="grid"`, `grid-cols-8 sm:grid-cols-10`, cells `h-9 w-9 text-xl`). Cells match the legacy 9px button so caller layouts don't reflow.
- **Lazy render**: only the active category's grid is mounted at any time. Switching tabs unmounts the previous grid and mounts the new one. Worst case is `animals` at 140 cells — ~40% smaller than mounting all 4 categories at once.
- A11y: cells are `role="gridcell"` with roving `tabindex` (first cell `0`, rest `-1`). Arrow keys / Home / End walk focus cell-by-cell per the WAI-ARIA grid pattern. The tablist receives a single Tab stop.
- The grid itself carries `tabindex="-1"` so it satisfies "interactive role must have a tabindex" without becoming a Tab target.

### 19.3 — Integration

Four sites swapped their inline `EMOJI_OPTIONS` / `EMOJI_GRID` arrays for `<EmojiPicker selected={…} onSelect={…} />`. Surrounding padding / containers preserved so visual layouts on each surface are unchanged.

- `apps/web/src/routes/(app)/settings/+page.svelte` — user avatar (avatar-type=`emoji` branch).
- `apps/web/src/routes/onboarding/+page.svelte` — initial collective emoji.
- `apps/web/src/lib/components/CreateCollectiveModal.svelte` — collective creation from the sidebar.
- `apps/web/src/routes/(app)/collective/manage/+page.svelte` — admin rename (Fase 10.2 surface).

**Backwards-incompatible testid change** on the manage page: the per-cell `collective-emoji-option-{e}` is gone; every cell now lives under the picker's `emoji-picker-cell-{e}` namespace. Two existing specs were updated: `tests/e2e/onboarding.test.ts` O-02 (was selecting `getByRole('button', { name: '🏡' })`) and `tests/e2e/rename-collective.test.ts` MC-01a (was selecting `collective-emoji-option-🏡`). Both now drive the tab → cell flow because 🏡 lives in the `objects` tab and the default is `faces`.

### 19.4 — Test coverage

- `src/lib/data/emoji-catalog.test.ts` — EC-U-01..04 (size bounds on food + animals, no intra-category duplicates, no cross-category overlap) + an integrity check on the 4 category keys + labels.
- `src/lib/components/EmojiPicker.test.ts` — EP-U-01..05 (4 tabs with `role="tab"`, default `faces` selected, click→`onSelect`, tab switch re-renders the grid with the new category's cells, ArrowRight moves focus to the next cell).
- `tests/e2e/emoji-picker.test.ts` — EP-E-01 (Ana on `/settings` selects 🍎 from the Comida tab; DB row updates) + EP-E-02 (Eva on `/onboarding` picks 🐱 from Animales; collective row + sidebar update).

## Test counts (final)

- **pgTAP**: 191 (unchanged)
- **Vitest integration**: 185 (unchanged) + 3 skipped (2 Realtime presence; 1 rate-limit gated)
- **Vitest unit**: 85 (was 75; +10 = 5 EC + 5 EP)
- **Playwright**: 106 (was 104; +2)
- **Gated rate-limit**: 1 (unchanged)

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

## Bundle-size delta

Measured with `pnpm --filter @colectivo/web build`, comparing the total size of `apps/web/build/client/_app/immutable/chunks/*.js` (uncompressed) before and after:

- Before: 526,835 bytes
- After: 531,968 bytes
- Delta: **+5,133 bytes (~5 KB)** uncompressed JS

Well under the +12 KB target. Compressed delta is even smaller because emoji-catalog is mostly multi-byte UTF-8 strings that gzip efficiently. No need for dynamic-import.

## Decisions worth remembering

- **Catalog is hardcoded, not fetched.** ~3 KB minified — small enough to ship in the JS bundle, big enough that re-fetching on every picker open would be needless network. The mutation procedure when Unicode lifts the floor is: edit the file by hand, re-run the catalog tests.
- **Unicode 14 baseline, not 15.** Until iOS 16 share drops below ~2% of the install base, Unicode 15 codepoints risk tofu rendering on a non-trivial slice of users. Re-evaluate in 2027.
- **Lazy-render by tab, not virtualised.** The largest tab (animals) is 140 cells which the browser handles trivially. Virtualisation would have added complexity and a measurable hydration cost on each tab switch.
- **No skin-tone selector.** Out of scope for the avatar use case; the base codepoint reads fine. Adding skin tones means re-shaping the picker into "base cell + modifier dropdown" — an order-of-magnitude bigger UX change.
- **No search.** With 4 tabs and 36–140 cells each, scanning is fast. Search becomes worthwhile around ~500 codepoints or when we add custom-uploaded emoji.

## Out of scope (deliberately)

- Search emoji by name (`unicode-emoji-json` ships the localised names but doubles the JS payload).
- Skin-tone variants (`🏻..🏿`).
- Recently-used tracking (per-user history of last-selected emoji).
- Custom-uploaded emoji (per-collective sticker packs).
- OS-level emoji-keyboard parity (`<input type="text">` plus a `:` autocomplete).

## Files indexed

- `apps/web/src/lib/data/emoji-catalog.ts` + `emoji-catalog.test.ts`
- `apps/web/src/lib/components/EmojiPicker.svelte` + `EmojiPicker.test.ts`
- `apps/web/src/routes/(app)/settings/+page.svelte` (wired)
- `apps/web/src/routes/onboarding/+page.svelte` (wired)
- `apps/web/src/lib/components/CreateCollectiveModal.svelte` (wired)
- `apps/web/src/routes/(app)/collective/manage/+page.svelte` (wired)
- `apps/web/tests/e2e/emoji-picker.test.ts`
- `apps/web/tests/e2e/onboarding.test.ts` (O-02 driver updated)
- `apps/web/tests/e2e/rename-collective.test.ts` (MC-01a driver updated)