# Build the "Starter prompt gallery" pattern: `StarterPromptGallery`

## Stack (edit this block to match your project)
- React 18+ with TypeScript: one function component, typed props, no `any`.
- Tailwind CSS, using your design system's tokens if you have them.
- Presentational only: data comes in through props, decisions go out through callbacks. No fetching or global state inside.
- If your codebase already has conventions (naming, shared components, tokens), follow them over this spec.

## What the pattern is for
A curated set of example prompts on the empty state, teaching capability by demonstration rather than description.

Use it when: Cold-start surfaces where the input is open-ended and the user has no mental model of scope yet.

## What to build
A small set of example prompts shown on an empty chat or input, each a real task this product can do with the data it can reach. Picking one fills the input so a person sees the scope by example. It renders in the empty state above or around the composer.

### Props
- `starters`: Array<{ id: string; verb: string; text: string; uses?: string[] }>, served from config, e.g. { verb: "Summarize", text: "Summarize this ticket and suggest a reply", uses: ["Tickets", "Billing"] }.
- `heading?`: string and `scopeNote?`: string, e.g. a line stating which data the assistant can read here.
- `groups?`: Array<{ title: string; ids: string[] }>, optional grouping by job.
- `status`: "loading" | "ready" | "hidden".
- `onPick(id: string, text: string)`: fills the composer. The component never sends the prompt itself.
- `onImpression?(ids: string[])`: called once when the cards are shown, so the parent can log and rotate them.

### States it must render
- Loading: card-shaped placeholders that keep the composer from jumping.
- Ready: 3 to 6 cards, each with its verb, the full prompt text and the data sources it uses.
- Grouped: cards under short group titles when `groups` is passed.
- Picked: the chosen card is marked and the composer holds its text, ready to edit.
- Hidden: once the conversation has started or the person types, the gallery is gone.

### Interactions
- Clicking a card calls `onPick`; the parent places the text in the composer with focus at the end so it can be edited before sending.
- Typing in the composer hides the gallery; clearing the composer before any message brings it back.
- `onImpression` fires once per display, not on every re-render.

### Edge cases
- Prompts should name concrete objects and data the product really holds; a starter whose `uses` sources are not connected should be omitted by the parent, and the card shows its sources so a mismatch is visible.
- Prompt text with placeholders like `[ticket]`: show them as visible blanks rather than sending them literally.
- More than 6 starters passed in: show 6 and do not paginate the empty state.
- Very long prompt text: wrap to 3 lines, then truncate with the full text in the accessible name.

## Must avoid
Generic filler prompts nobody wants ("Write a poem") that teach the wrong ceiling for a serious tool.

## Engineering constraint
Serve from a config, not the model. Log which cards get clicked and rotate on that signal.

## Accessibility
- Cards are buttons in a labelled list; the accessible name is the full prompt text plus its sources.
- After picking, focus moves to the composer.

## House rules
- Real `<button>`/`<input>` elements, full keyboard use, visible focus; announce status changes with `aria-live="polite"`; respect `prefers-reduced-motion`.
- All user-facing text comes from props (or a `labels` prop) so it can be translated.
- One consistent accent marks anything the AI made or is doing; amber means "needs a person", red means risky, green means done. Never rely on colour alone.
- Fits a 360 px wide container without horizontal scrolling.

## Acceptance checks
- [ ] Every state above can be rendered by passing props, with no internal fake data.
- [ ] Every interaction and edge case above behaves as described.
- [ ] Nothing in "Must avoid" can happen with this component.

## Deliver
1. The component file with its exported prop types.
2. A short usage example that renders each state.