Therapy Pack — Tools → "Add to Editor" Implementation Plan¶

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Let a clinician push a tool's current results into a therapy pack — a uniform "Add to Editor" control on the shared results toolbar (Word Lists, Contrast Sets, Sentences) plus a single-word add in Lookup — with a pack-picker (choose a saved pack or "New pack…") and a confirmation toast with Undo (spec §5.7 + §15).

Architecture: The shared SelectionToolbar already carries every grid tool's results as data: ExportData + dataType + selection indices — the one uniform surface. A pure toPackItems(data, dataType, indices, sourceTool) adapter maps those shapes to PackItem[] (words carry image refs → picture cards). An AddToEditorButton (button + pack-picker menu) activates the chosen pack and bulk-adds via new store actions addItems/removeItems (Undo), showing a toast. The button drops into SelectionToolbar (covers 3 tools) and into LookupTool (single word).

Tech Stack: React 19, TypeScript, MUI 7, Zustand 5, Vitest 4 + @testing-library/react. Reuses the pack store, PackSourceTool, and the ExportData contract.

Global Constraints¶

Store is the single mutation surface. The control calls store actions (addItems, removeItems, loadPack, newPack); it never touches packDb.
Uniform contract via ExportData. SelectionToolbar's data: ExportData (Word[] | MinimalPair[] | ContrastiveGroup[] | CorpusMatch[]) + dataType: 'words'|'pairs'|'groups'|'sentences' is the single mapping surface for the three grid tools. Do NOT add per-tool result plumbing.
Add the SELECTED items (SelectionToolbar only shows on selection). Map data filtered by selectedIndices.
Words link to the lexicon at add-time. Tool Word objects already carry ipa/image_file/image_provider/has_image (from the search API) — map them straight onto PackWord.imageFile/imageProvider/ipa/hasImage (no re-fetch). (spec §15)
Pack-picker, not always-active. "Add to Editor" opens a menu of saved packs (from usePackStore.library) + "New pack…"; the pick becomes the active pack, items are added, the pack indicator reflects it. (spec §15)
Confirmation toast with Undo. After add: a MUI Snackbar "Added N to " with an Undo action that removes the just-added items. (spec §5.7)</li> <li><code>PackSourceTool</code> already includes <code>wordLists</code>, <code>contrastive</code>, <code>sentences</code>, <code>lookup</code>, <code>textAnalysis</code> (<code>src/types/therapyPack.ts</code>). Use the right one per surface.</li> <li>No new analytics events (taxonomy is the next phase). Speech Analysis and Text Analysis are out of scope for this phase (audio stays outside the pack MVP; Text-Analysis add is deferred — noted).</li> <li>Test commands (from <code>packages/web/frontend/</code>): <code>npm test -- --run <file></code>, <code>npm run type-check</code>, <code>npm run lint</code>, <code>npm run build</code>.</li> </ul> <hr /> <h2 id="file-structure">File Structure<a class="headerlink" href="#file-structure" title="Permanent link">¶</a></h2> <ul> <li><code>src/store/packStore.ts</code> (modify) — <code>addItems(items)</code> + <code>removeItems(ids)</code> actions.</li> <li><code>src/lib/pack/toPackItems.ts</code> (create) — <code>ExportData</code> → <code>PackItem[]</code> adapter.</li> <li><code>src/lib/pack/toPackItems.test.ts</code> (create).</li> <li><code>src/components/pack/AddToEditorButton.tsx</code> (create) — button + pack-picker menu + toast/Undo.</li> <li><code>src/components/pack/AddToEditorButton.test.tsx</code> (create).</li> <li><code>src/components/shared/SelectionToolbar.tsx</code> (modify) — render <code>AddToEditorButton</code> from <code>data</code>/<code>dataType</code>/<code>selectedIndices</code>.</li> <li><code>src/components/shared/SelectionToolbar.test.tsx</code> (create or modify).</li> <li><code>src/components/tools/LookupTool.tsx</code> (modify) — single-word <code>AddToEditorButton</code>.</li> </ul> <hr /> <h3 id="task-1-store-additems-removeitems">Task 1: Store <code>addItems</code> + <code>removeItems</code><a class="headerlink" href="#task-1-store-additems-removeitems" title="Permanent link">¶</a></h3> Files: - Modify: <code>src/store/packStore.ts</code> - Test: <code>src/store/packStore.test.ts</code> Interfaces: - Produces (added to <code>PackState</code>): - <code>addItems: (items: PackItem[]) => void</code> — appends each item to its section (<code>word</code>/<code>contrast</code>/<code>sentence</code>) and commits once; no-op on empty; no-op if no active pack. - <code>removeItems: (ids: string[]) => void</code> — removes every listed id across all sections in one commit; no-op on empty / no active pack. <ul> <li>[ ] Step 1: Write the failing tests</li> </ul> Add to <code>src/store/packStore.test.ts</code>: <div class="highlight"><pre><code> it('addItems appends a mixed batch in one commit', () => { store.getState().newPack(); store.getState().addItems([ { kind: 'word', id: 'w1', word: 'rocket', provenance: { sourceTool: 'wordLists', addedAt: 1 } }, { kind: 'contrast', id: 'c1', a: 'key', b: 'tea', provenance: { sourceTool: 'contrastive', addedAt: 1 } }, { kind: 'sentence', id: 's1', text: 'A rocket.', targets: [], provenance: { sourceTool: 'sentences', addedAt: 1 } }, ]); const p = store.getState().activePack!; expect(p.words).toHaveLength(1); expect(p.contrasts).toHaveLength(1); expect(p.sentences).toHaveLength(1); }); it('removeItems drops all listed ids across sections', () => { store.getState().newPack(); store.getState().addItems([ { kind: 'word', id: 'w1', word: 'a', provenance: { sourceTool: 'wordLists', addedAt: 1 } }, { kind: 'word', id: 'w2', word: 'b', provenance: { sourceTool: 'wordLists', addedAt: 1 } }, { kind: 'sentence', id: 's1', text: 'x', targets: [], provenance: { sourceTool: 'sentences', addedAt: 1 } }, ]); store.getState().removeItems(['w1', 's1']); const p = store.getState().activePack!; expect(p.words.map((w) => w.id)).toEqual(['w2']); expect(p.sentences).toHaveLength(0); }); it('addItems is a no-op with no active pack', () => { store.setState({ activePack: null }); store.getState().addItems([{ kind: 'word', id: 'w', word: 'x', provenance: { sourceTool: 'manual', addedAt: 1 } }]); expect(store.getState().activePack).toBeNull(); }); </code></pre></div> <ul> <li>[ ] Step 2: Run the tests to verify they fail</li> </ul> Run: <code>npm test -- --run src/store/packStore.test.ts</code> Expected: FAIL — <code>addItems</code>/<code>removeItems</code> undefined. <ul> <li>[ ] Step 3: Implement</li> </ul> In <code>src/store/packStore.ts</code>, add to the <code>PackState</code> interface: <div class="highlight"><pre><code> addItems: (items: PackItem[]) => void; removeItems: (ids: string[]) => void; </code></pre></div> and implement (near <code>addItem</code>): <div class="highlight"><pre><code> addItems(items) { const p = get().activePack; if (!p || items.length === 0) return; const words = [...p.words]; const contrasts = [...p.contrasts]; const sentences = [...p.sentences]; for (const it of items) { if (it.kind === 'word') words.push(it); else if (it.kind === 'contrast') contrasts.push(it); else sentences.push(it); } commit({ ...p, words, contrasts, sentences }); }, removeItems(ids) { const p = get().activePack; if (!p || ids.length === 0) return; const drop = new Set(ids); commit({ ...p, words: p.words.filter((w) => !drop.has(w.id)), contrasts: p.contrasts.filter((c) => !drop.has(c.id)), sentences: p.sentences.filter((s) => !drop.has(s.id)), }); }, </code></pre></div> <ul> <li>[ ] Step 4: Run the tests to verify they pass</li> </ul> Run: <code>npm test -- --run src/store/packStore.test.ts</code> Expected: PASS. <ul> <li>[ ] Step 5: Type-check and commit</li> </ul> <div class="highlight"><pre><code>npm run type-check git add src/store/packStore.ts src/store/packStore.test.ts git commit -m "feat(packs): addItems/removeItems bulk store actions (PHON-170)" </code></pre></div> <hr /> <h3 id="task-2-topackitems-exportdata-packitem">Task 2: <code>toPackItems</code> — ExportData → PackItem[]<a class="headerlink" href="#task-2-topackitems-exportdata-packitem" title="Permanent link">¶</a></h3> Files: - Create: <code>src/lib/pack/toPackItems.ts</code> - Test: <code>src/lib/pack/toPackItems.test.ts</code> Interfaces: - Consumes: <code>ExportData</code> + <code>ContrastiveGroup</code> from <code>../../components/shared/ExportMenu</code>; <code>Word</code>/<code>MinimalPair</code> from <code>../../services/phonolexApi</code>; <code>CorpusMatch</code> from <code>../../types/governance</code>; <code>PackItem</code>/<code>PackWord</code>/<code>PackContrast</code>/<code>PackSentence</code>/<code>PackSourceTool</code> from <code>../../types/therapyPack</code>; <code>newId</code> from <code>../id</code>. - Produces: - <code>export function toPackItems(data: ExportData, dataType: 'words' | 'pairs' | 'groups' | 'sentences', indices: number[] | null, sourceTool: PackSourceTool, at: number): PackItem[]</code> — maps the <code>indices</code>-selected rows (or all rows when <code>indices</code> is null/empty) to pack items: - <code>words</code> → <code>PackWord</code> each (word, ipa, <code>image_file</code>→<code>imageFile</code>, <code>image_provider</code>→<code>imageProvider</code>, <code>has_image</code>→<code>hasImage</code>). - <code>pairs</code> → <code>PackContrast</code> each (<code>word1.word</code>, <code>word2.word</code>, label <code>"${phoneme1} vs ${phoneme2}"</code>). - <code>groups</code> → the group's words flattened to <code>PackWord[]</code>. - <code>sentences</code> → <code>PackSentence</code> each (text; targets = union of <code>highlights.include_surfaces</code> + <code>highlights.pair_surfaces</code>). - Every item carries <code>provenance: { sourceTool, addedAt: at }</code>. <ul> <li>[ ] Step 1: Write the failing test</li> </ul> Create <code>src/lib/pack/toPackItems.test.ts</code>: <div class="highlight"><pre><code>import { describe, it, expect } from 'vitest'; import { toPackItems } from './toPackItems'; describe('toPackItems', () => { it('maps selected words with image refs', () => { const data = [ { word: 'rocket', ipa: 'ɹ', has_image: 1, image_file: 'rocket.svg', image_provider: 'mulberry' }, { word: 'skip', ipa: 's' }, ] as never; const items = toPackItems(data, 'words', [0], 'wordLists', 5); expect(items).toHaveLength(1); expect(items[0]).toMatchObject({ kind: 'word', word: 'rocket', imageFile: 'rocket.svg', imageProvider: 'mulberry', hasImage: true }); expect(items[0].provenance).toMatchObject({ sourceTool: 'wordLists', addedAt: 5 }); }); it('maps all rows when indices is null', () => { const data = [{ word: 'a' }, { word: 'b' }] as never; expect(toPackItems(data, 'words', null, 'wordLists', 1)).toHaveLength(2); }); it('maps pairs to contrasts', () => { const data = [{ word1: { word: 'key' }, word2: { word: 'tea' }, phoneme1: 'k', phoneme2: 't' }] as never; const items = toPackItems(data, 'pairs', null, 'contrastive', 1); expect(items[0]).toMatchObject({ kind: 'contrast', a: 'key', b: 'tea', label: 'k vs t' }); }); it('flattens groups to words', () => { const data = [{ words: [{ word: { word: 'cat' } }, { word: { word: 'bat' } }] }] as never; const items = toPackItems(data, 'groups', null, 'contrastive', 1); expect(items.map((i) => (i as { word: string }).word)).toEqual(['cat', 'bat']); }); it('maps sentences with highlight targets', () => { const data = [{ text: 'The key.', highlights: { include_surfaces: ['key'], pair_surfaces: [] } }] as never; const items = toPackItems(data, 'sentences', null, 'sentences', 1); expect(items[0]).toMatchObject({ kind: 'sentence', text: 'The key.', targets: ['key'] }); }); }); </code></pre></div> <ul> <li>[ ] Step 2: Run the test to verify it fails</li> </ul> Run: <code>npm test -- --run src/lib/pack/toPackItems.test.ts</code> Expected: FAIL — module not found. <ul> <li>[ ] Step 3: Implement</li> </ul> Create <code>src/lib/pack/toPackItems.ts</code>: <div class="highlight"><pre><code>/** * Adapter: a tool's ExportData (the uniform results contract shared by * SelectionToolbar/ExportMenu) → pack items (spec §5.7 / §15). Words carry * their lexicon image refs so they render as picture cards with no re-fetch. */ import type { ExportData, ContrastiveGroup } from '../../components/shared/ExportMenu'; import type { Word, MinimalPair } from '../../services/phonolexApi'; import type { CorpusMatch } from '../../types/governance'; import type { PackItem, PackWord, PackSourceTool } from '../../types/therapyPack'; import { newId } from '../id'; function wordToPack(w: Word, sourceTool: PackSourceTool, at: number): PackWord { return { kind: 'word', id: newId(), word: w.word, ipa: w.ipa ?? undefined, hasImage: w.has_image || w.image_file ? true : undefined, imageFile: w.image_file ?? undefined, imageProvider: w.image_provider ?? undefined, provenance: { sourceTool, addedAt: at }, }; } function pick<T>(rows: T[], indices: number[] | null): T[] { if (!indices || indices.length === 0) return rows; const set = new Set(indices); return rows.filter((_, i) => set.has(i)); } export function toPackItems( data: ExportData, dataType: 'words' | 'pairs' | 'groups' | 'sentences', indices: number[] | null, sourceTool: PackSourceTool, at: number, ): PackItem[] { if (dataType === 'words') { return pick(data as Word[], indices).map((w) => wordToPack(w, sourceTool, at)); } if (dataType === 'pairs') { return pick(data as MinimalPair[], indices).map((p) => ({ kind: 'contrast' as const, id: newId(), a: p.word1.word, b: p.word2.word, label: `${p.phoneme1} vs ${p.phoneme2}`, provenance: { sourceTool, addedAt: at }, })); } if (dataType === 'groups') { return pick(data as ContrastiveGroup[], indices).flatMap((g) => g.words.map((gw) => wordToPack(gw.word, sourceTool, at)), ); } return pick(data as CorpusMatch[], indices).map((m) => ({ kind: 'sentence' as const, id: newId(), text: m.text, targets: Array.from(new Set([ ...(m.highlights?.include_surfaces ?? []), ...(m.highlights?.pair_surfaces ?? []), ])), provenance: { sourceTool, addedAt: at }, })); } </code></pre></div> (If <code>MinimalPair</code> / <code>ContrastiveGroup</code> field names differ from the above when you read <code>ExportMenu.tsx</code>/<code>phonolexApi</code>, adjust the field access to match the real types — the shapes are: <code>MinimalPair</code> has <code>word1</code>/<code>word2</code> (<code>Word</code>) + <code>phoneme1</code>/<code>phoneme2</code>; <code>ContrastiveGroup</code> has <code>words: { word: Word; phoneme; position }[]</code>.) <ul> <li>[ ] Step 4: Run the test to verify it passes</li> </ul> Run: <code>npm test -- --run src/lib/pack/toPackItems.test.ts</code> Expected: PASS (5/5). <ul> <li>[ ] Step 5: Type-check and commit</li> </ul> <div class="highlight"><pre><code>npm run type-check git add src/lib/pack/toPackItems.ts src/lib/pack/toPackItems.test.ts git commit -m "feat(packs): toPackItems — ExportData → pack items adapter (PHON-170)" </code></pre></div> <hr /> <h3 id="task-3-addtoeditorbutton-pack-picker-toastundo">Task 3: <code>AddToEditorButton</code> — pack-picker + toast/Undo<a class="headerlink" href="#task-3-addtoeditorbutton-pack-picker-toastundo" title="Permanent link">¶</a></h3> Files: - Create: <code>src/components/pack/AddToEditorButton.tsx</code> - Test: <code>src/components/pack/AddToEditorButton.test.tsx</code> Interfaces: - Consumes: <code>usePackStore</code> (<code>library</code>, <code>hydrate</code>, <code>loadPack</code>, <code>newPack</code>, <code>addItems</code>, <code>removeItems</code>, <code>activePack</code>); <code>PackItem</code> type. - Produces: <code>AddToEditorButton</code> props <code>{ getItems: () => PackItem[]; disabled?: boolean; size?: 'small' | 'medium'; label?: string }</code>. - A button ("Add to Editor" by default). On click: <code>hydrate()</code> then open a Menu listing each saved pack (title + counts) and a "New pack…" item. - Picking a saved pack → <code>loadPack(id)</code>; "New pack…" → <code>newPack()</code>. Then compute <code>const items = getItems()</code>, <code>addItems(items)</code>, remember <code>items.map(i => i.id)</code>, and show a Snackbar <code>Added ${items.length} to "${activePack.title}"</code> with an Undo action that calls <code>removeItems(addedIds)</code>. - If <code>getItems()</code> returns <code>[]</code>, no-op (no menu, or a disabled state). <ul> <li>[ ] Step 1: Write the failing test</li> </ul> Create <code>src/components/pack/AddToEditorButton.test.tsx</code>: <div class="highlight"><pre><code>import { describe, it, expect, beforeEach, vi } from 'vitest'; import { render, screen, fireEvent, waitFor } from '@testing-library/react'; import AddToEditorButton from './AddToEditorButton'; import { usePackStore } from '../../store/packStore'; import { getAllPacks, deletePack } from '../../lib/packDb'; import type { PackItem } from '../../types/therapyPack'; async function clearDb() { const all = await getAllPacks(); await Promise.all(all.map((p) => deletePack(p.id))); } const items = (): PackItem[] => [ { kind: 'word', id: 'w1', word: 'rocket', provenance: { sourceTool: 'wordLists', addedAt: 1 } }, { kind: 'word', id: 'w2', word: 'rabbit', provenance: { sourceTool: 'wordLists', addedAt: 1 } }, ]; describe('AddToEditorButton', () => { beforeEach(async () => { await clearDb(); usePackStore.setState({ activePack: null, library: [], saveError: null }); }); it('creates a new pack and adds items via the menu', async () => { render(<AddToEditorButton getItems={items} />); fireEvent.click(screen.getByRole('button', { name: /add to editor/i })); fireEvent.click(await screen.findByRole('menuitem', { name: /new pack/i })); await waitFor(() => expect(usePackStore.getState().activePack).not.toBeNull()); expect(usePackStore.getState().activePack!.words).toHaveLength(2); expect(await screen.findByText(/added 2 to/i)).toBeInTheDocument(); }); it('adds to an existing saved pack', async () => { usePackStore.getState().newPack(); usePackStore.getState().setTitle('My /r/ pack'); const id = usePackStore.getState().activePack!.id; usePackStore.setState({ activePack: null }); render(<AddToEditorButton getItems={items} />); fireEvent.click(screen.getByRole('button', { name: /add to editor/i })); fireEvent.click(await screen.findByRole('menuitem', { name: /my \/r\/ pack/i })); await waitFor(() => expect(usePackStore.getState().activePack!.id).toBe(id)); expect(usePackStore.getState().activePack!.words).toHaveLength(2); }); it('Undo removes the just-added items', async () => { render(<AddToEditorButton getItems={items} />); fireEvent.click(screen.getByRole('button', { name: /add to editor/i })); fireEvent.click(await screen.findByRole('menuitem', { name: /new pack/i })); await waitFor(() => expect(usePackStore.getState().activePack!.words).toHaveLength(2)); fireEvent.click(await screen.findByRole('button', { name: /undo/i })); await waitFor(() => expect(usePackStore.getState().activePack!.words).toHaveLength(0)); }); }); </code></pre></div> <ul> <li>[ ] Step 2: Run the test to verify it fails</li> </ul> Run: <code>npm test -- --run src/components/pack/AddToEditorButton.test.tsx</code> Expected: FAIL — module not found. <ul> <li>[ ] Step 3: Implement</li> </ul> Create <code>src/components/pack/AddToEditorButton.tsx</code>: <div class="highlight"><pre><code>import React, { useState } from 'react'; import { Button, Menu, MenuItem, Divider, ListItemText, Snackbar } from '@mui/material'; import { PlaylistAdd as AddIcon } from '@mui/icons-material'; import { usePackStore } from '../../store/packStore'; import type { PackItem } from '../../types/therapyPack'; interface AddToEditorButtonProps { getItems: () => PackItem[]; disabled?: boolean; size?: 'small' | 'medium'; label?: string; } const AddToEditorButton: React.FC<AddToEditorButtonProps> = ({ getItems, disabled = false, size = 'small', label = 'Add to Editor', }) => { const library = usePackStore((s) => s.library); const [anchor, setAnchor] = useState<null | HTMLElement>(null); const [snack, setSnack] = useState<{ msg: string; ids: string[] } | null>(null); const open = (e: React.MouseEvent<HTMLElement>) => { void usePackStore.getState().hydrate(); setAnchor(e.currentTarget); }; const close = () => setAnchor(null); const addTo = (activate: () => void | Promise<void>) => { return async () => { close(); const items = getItems(); if (!items.length) return; await activate(); usePackStore.getState().addItems(items); const title = usePackStore.getState().activePack?.title ?? 'pack'; setSnack({ msg: `Added ${items.length} to "${title}"`, ids: items.map((i) => i.id) }); }; }; return ( <> <Button size={size} variant="outlined" startIcon={<AddIcon />} disabled={disabled} onClick={open}> {label} </Button> <Menu anchorEl={anchor} open={Boolean(anchor)} onClose={close}> <MenuItem onClick={addTo(() => usePackStore.getState().newPack())}> <ListItemText primary="New pack…" /> </MenuItem> {library.length > 0 && <Divider />} {library.map((s) => ( <MenuItem key={s.id} onClick={addTo(() => usePackStore.getState().loadPack(s.id))}> <ListItemText primary={s.title} secondary={`${s.counts.words} words · ${s.counts.contrasts} contrasts · ${s.counts.sentences} sentences`} /> </MenuItem> ))} </Menu> <Snackbar open={Boolean(snack)} autoHideDuration={6000} onClose={() => setSnack(null)} message={snack?.msg} action={ <Button color="secondary" size="small" onClick={() => { if (snack) usePackStore.getState().removeItems(snack.ids); setSnack(null); }}> Undo </Button> } /> </> ); }; export default AddToEditorButton; </code></pre></div> <ul> <li>[ ] Step 4: Run the test to verify it passes</li> </ul> Run: <code>npm test -- --run src/components/pack/AddToEditorButton.test.tsx</code> Expected: PASS (3/3). <ul> <li>[ ] Step 5: Commit</li> </ul> <div class="highlight"><pre><code>git add src/components/pack/AddToEditorButton.tsx src/components/pack/AddToEditorButton.test.tsx git commit -m "feat(packs): AddToEditorButton — pack-picker menu + toast/undo (PHON-170)" </code></pre></div> <hr /> <h3 id="task-4-wire-add-to-editor-into-selectiontoolbar-word-lists-contrast-sets-sentences">Task 4: Wire "Add to Editor" into <code>SelectionToolbar</code> (Word Lists · Contrast Sets · Sentences)<a class="headerlink" href="#task-4-wire-add-to-editor-into-selectiontoolbar-word-lists-contrast-sets-sentences" title="Permanent link">¶</a></h3> Files: - Modify: <code>src/components/shared/SelectionToolbar.tsx</code> - Test: <code>src/components/shared/SelectionToolbar.test.tsx</code> (create if absent) Interfaces: - <code>SelectionToolbar</code> renders <code><AddToEditorButton getItems={() => toPackItems(data, dataType, selectedIndices, sourceToolFor(dataType), Date.now())} /></code> alongside its existing <code>ExportMenu</code>. - Add a helper <code>sourceToolFor(dataType)</code>: <code>'words'</code>→<code>'wordLists'</code>, <code>'pairs'|'groups'</code>→<code>'contrastive'</code>, <code>'sentences'</code>→<code>'sentences'</code>. <ul> <li>[ ] Step 1: Write the failing test</li> </ul> Create/extend <code>src/components/shared/SelectionToolbar.test.tsx</code>. Read the current <code>SelectionToolbar</code> render to supply required props (<code>totalCount</code>, <code>selectedCount</code>, <code>selectedIndices</code>, <code>onSelectAll</code>, <code>onClearAll</code>, <code>data</code>, <code>dataType</code>). Because the toolbar renders only when <code>selectedCount > 0</code>, pass a non-zero selection. <div class="highlight"><pre><code>import { describe, it, expect, beforeEach, vi } from 'vitest'; import { render, screen, fireEvent, waitFor } from '@testing-library/react'; import SelectionToolbar from './SelectionToolbar'; import { usePackStore } from '../../store/packStore'; describe('SelectionToolbar — Add to Editor', () => { beforeEach(() => usePackStore.setState({ activePack: null, library: [], saveError: null })); it('adds the selected words to a new pack', async () => { render( <SelectionToolbar totalCount={2} selectedCount={1} selectedIndices={[0]} onSelectAll={vi.fn()} onClearAll={vi.fn()} data={[{ word: 'rocket', ipa: 'ɹ' }, { word: 'skip' }] as never} dataType="words" />, ); fireEvent.click(screen.getByRole('button', { name: /add to editor/i })); fireEvent.click(await screen.findByRole('menuitem', { name: /new pack/i })); await waitFor(() => expect(usePackStore.getState().activePack!.words.map((w) => w.word)).toEqual(['rocket'])); }); }); </code></pre></div> <ul> <li>[ ] Step 2: Run the test to verify it fails</li> </ul> Run: <code>npm test -- --run src/components/shared/SelectionToolbar.test.tsx</code> Expected: FAIL — no "Add to Editor" button. <ul> <li>[ ] Step 3: Implement</li> </ul> In <code>src/components/shared/SelectionToolbar.tsx</code>: import the button + adapter, add the helper, render the button next to <code>ExportMenu</code> (read the file to place it in the same action row). Map only the selected rows via <code>selectedIndices</code>. <div class="highlight"><pre><code>import AddToEditorButton from '../pack/AddToEditorButton'; import { toPackItems } from '../../lib/pack/toPackItems'; import type { PackSourceTool } from '../../types/therapyPack'; function sourceToolFor(dataType: 'words' | 'pairs' | 'groups' | 'sentences'): PackSourceTool { if (dataType === 'words') return 'wordLists'; if (dataType === 'sentences') return 'sentences'; return 'contrastive'; } </code></pre></div> In the toolbar's action area (next to <code><ExportMenu .../></code>): <div class="highlight"><pre><code> <AddToEditorButton getItems={() => toPackItems(data, dataType, selectedIndices, sourceToolFor(dataType), Date.now())} /> </code></pre></div> <ul> <li>[ ] Step 4: Run the test to verify it passes</li> </ul> Run: <code>npm test -- --run src/components/shared/SelectionToolbar.test.tsx</code> Expected: PASS. <ul> <li>[ ] Step 5: Commit</li> </ul> <div class="highlight"><pre><code>git add src/components/shared/SelectionToolbar.tsx src/components/shared/SelectionToolbar.test.tsx git commit -m "feat(packs): Add to Editor on the shared results toolbar (word lists/contrasts/sentences) (PHON-170)" </code></pre></div> <hr /> <h3 id="task-5-lookup-single-word-add-to-editor-full-gate">Task 5: Lookup single-word "Add to Editor" + full gate<a class="headerlink" href="#task-5-lookup-single-word-add-to-editor-full-gate" title="Permanent link">¶</a></h3> Files: - Modify: <code>src/components/tools/LookupTool.tsx</code> - Test: <code>src/components/tools/LookupTool.test.tsx</code> (create if absent; otherwise a focused new test) Interfaces: - In <code>LookupTool</code>, when <code>wordResult</code> (a <code>Word</code>) is present, render <code><AddToEditorButton getItems={() => toPackItems([wordResult], 'words', null, 'lookup', Date.now())} /></code> near the word header/detail. <ul> <li>[ ] Step 1: Write the failing test</li> </ul> Read <code>LookupTool.tsx</code> to find how to render it with a populated <code>wordResult</code> (it fetches on a query; the test can mock <code>api.getWord</code>). Create <code>src/components/tools/LookupTool.test.tsx</code>: <div class="highlight"><pre><code>import { describe, it, expect, beforeEach, vi } from 'vitest'; import { render, screen, fireEvent, waitFor } from '@testing-library/react'; import LookupTool from './LookupTool'; import api from '../../services/phonolexApi'; import { usePackStore } from '../../store/packStore'; describe('LookupTool — Add to Editor', () => { beforeEach(() => usePackStore.setState({ activePack: null, library: [], saveError: null })); it('adds the looked-up word to a new pack', async () => { vi.spyOn(api, 'getWord').mockResolvedValue({ word: 'rocket', ipa: 'ɹ', has_image: 1, image_file: 'rocket.svg', image_provider: 'mulberry' } as never); render(<LookupTool initialWord="rocket" />); // wait for the word to load, then Add to Editor await waitFor(() => expect(screen.getByRole('button', { name: /add to editor/i })).toBeInTheDocument()); fireEvent.click(screen.getByRole('button', { name: /add to editor/i })); fireEvent.click(await screen.findByRole('menuitem', { name: /new pack/i })); await waitFor(() => expect(usePackStore.getState().activePack!.words[0]).toMatchObject({ word: 'rocket', imageFile: 'rocket.svg' })); }); }); </code></pre></div> (If <code>LookupTool</code> doesn't accept <code>initialWord</code> or fetches differently, adapt the test to drive a lookup through its input — read the component first. The assertion that matters: a loaded word + Add to Editor → new pack contains that word with its image ref.) <ul> <li>[ ] Step 2: Run the test to verify it fails</li> </ul> Run: <code>npm test -- --run src/components/tools/LookupTool.test.tsx</code> Expected: FAIL — no "Add to Editor" button. <ul> <li>[ ] Step 3: Implement</li> </ul> In <code>src/components/tools/LookupTool.tsx</code>, import <code>AddToEditorButton</code> + <code>toPackItems</code>, and render the button in the word-result header block (guarded by <code>wordResult</code>): <div class="highlight"><pre><code>{wordResult && ( <AddToEditorButton getItems={() => toPackItems([wordResult], 'words', null, 'lookup', Date.now())} /> )} </code></pre></div> <ul> <li>[ ] Step 4: Run the test to verify it passes</li> </ul> Run: <code>npm test -- --run src/components/tools/LookupTool.test.tsx</code> Expected: PASS. <ul> <li>[ ] Step 5: Full gate</li> </ul> Run (from <code>packages/web/frontend/</code>): <div class="highlight"><pre><code>npm test -- --run npm run type-check npm run lint npm run build </code></pre></div> Expected: all pass (the one known pre-existing unrelated <code>MetadataErrorAlert</code> flake aside); build succeeds. <ul> <li>[ ] Step 6: Commit</li> </ul> <div class="highlight"><pre><code>git add src/components/tools/LookupTool.tsx src/components/tools/LookupTool.test.tsx git commit -m "feat(packs): Add to Editor on Lookup (single word) (PHON-170)" </code></pre></div> <hr /> <h2 id="self-review-notes-coverage-vs-spec-57-15">Self-Review notes (coverage vs spec §5.7 / §15)<a class="headerlink" href="#self-review-notes-coverage-vs-spec-57-15" title="Permanent link">¶</a></h2> <ul> <li>Uniform "Add to Editor" across grid tools: Task 4 (one <code>SelectionToolbar</code> integration → Word Lists, Contrast Sets, Sentences). ✓</li> <li>Single Lookup word: Task 5. ✓</li> <li>Pack-picker (saved packs + New pack…): Task 3 <code>AddToEditorButton</code> menu. ✓ (your amendment ask.)</li> <li>Words link to the lexicon (picture cards): Task 2 maps <code>image_file</code>/<code>image_provider</code> onto <code>PackWord</code>; the editor-cards phase renders them. ✓</li> <li>Confirmation toast with Undo: Task 3 Snackbar + <code>removeItems</code>. ✓</li> <li>Pack indicator updates: the chosen pack becomes active; the existing <code>PackIndicatorChip</code> reflects it (no change needed). ✓</li> <li>Deferred / out of scope: Text-Analysis "add extraction" (marginal fit + would need async word resolution — a follow-up); Speech Analysis (audio stays outside the pack MVP); navigating to the editor on add (the pack indicator is the path — intentional, tool keeps its UX); adding to a NON-active pack without activating it (picking activates — simpler, one active-pack model).</li> </ul> <h2 id="decisions-resolved-at-planning">Decisions resolved at planning<a class="headerlink" href="#decisions-resolved-at-planning" title="Permanent link">¶</a></h2> <ol> <li><code>SelectionToolbar</code> is the single anchor for the three grid tools — it already carries <code>data</code>/<code>dataType</code>/<code>selectedIndices</code>. One integration, not three.</li> <li>Add the selected rows (the toolbar is selection-scoped); "Select all" covers "add everything."</li> <li>Picking a pack activates it (<code>loadPack</code>/<code>newPack</code>) then adds — one active-pack model; the indicator reflects it; no separate add-to-inactive path.</li> <li>Undo via <code>removeItems(addedIds)</code> on the active pack (immediate, within the snackbar window).</li> <li>Text Analysis deferred (weak fit + async resolution); Lookup included (clear value).</li> </ol> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"annotate": null, "base": "../../..", "features": ["navigation.instant", "navigation.tracking", "navigation.tabs", "navigation.sections", "navigation.expand", "navigation.top", "search.suggest", "search.highlight", "content.code.copy"], "search": "../../../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script> <script src="../../../assets/javascripts/bundle.d7400e89.min.js"></script> </body> </html>