# Burbuja (burbuja)

> Chat bubble whose selected words sweep to vermilion with a controlled 0–1 highlight.

- Entry: component
- Category: UI
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/burbuja
- JSON: https://jbm-ui.bns.studio/catalog/burbuja.json
- Registry item: https://jbm-ui.bns.studio/r/burbuja.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/burbuja
```

Also installs @jbm/tokens, @jbm/chat-bubble, @jbm/text-fill (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/burbuja.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/burbuja.tsx` | `src/jbm/motion/burbuja.tsx` | `@/jbm/motion/burbuja` |

## API

### `Burbuja` (component)

Composes ChatBubble and TextFill: the message is a list of words joined by single spaces, and the words at the `highlight` indices sweep from the surrounding text color to the vermilion accent as `progress` goes from 0 to 1. Pure React with no timer; ordinary HTML handles wrapping.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `"start" \| "end"` | none | Which side the bubble aligns to and where its tail sits: `start` or `end`. |
| `tone` | `"paper" \| "ink" \| "accent"` | none | Bubble fill: `paper` (card with ink text and ChatBubble's ink outline), `ink`, or `accent` (both with cream text). Highlighted words always end in the vermilion accent, so avoid `accent` tone when they must stand out. |
| `tail` | `boolean` | none | Shows ChatBubble's tail under the bubble, outlined with the body as one line on paper, and reserves 13px of bottom margin for it. |
| `speaker` | `React.ReactNode` | none | Optional mono label above the message, e.g. the speaker's name. |
| `words` | `readonly string[]` | required | Message words in order; rendered joined by single spaces. |
| `highlight` | `readonly number[]` | required | Zero-based indices into `words` that receive the TextFill sweep. Out-of-range indices are ignored. |
| `progress` | `number` | `1` | Highlight progress from 0 (highlighted words in the bubble's text color) to 1 (fully vermilion). Clamped by TextFill; non-finite values render as 0. |

Also accepts Omit<ChatBubbleProps, "children">.

## Stage

fluid: ChatBubble is fit-content up to 100% of its container, so width follows the words and height follows wrapping. At 18px type with line-height 1.5 it adds 16px/20px of padding and edge, an optional ~20px speaker line, and 13px for the tail.

## Examples

### Highlight one word

```tsx
import { Burbuja } from "@/jbm/motion/burbuja"

<Burbuja words={["Podemos", "reutilizar", "componentes."]}
  highlight={[1]} progress={1} speaker="Tú" />
```

### Drive the highlight from a Remotion timeline

```tsx
import { Burbuja } from "@/jbm/motion/burbuja"
import { useProgress } from "@/jbm/motion/hooks" // install @jbm/motion-hooks separately

// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.
export function SpeakingBubble() {
  const progress = useProgress(0.5, 1, 0.8)
  return <Burbuja side="end" words={["Una", "pieza", "a", "la", "vez."]} highlight={[1, 4]} progress={progress} />
}
```

## QA

- Drag Highlight through 0, 0.5, and 1: only the selected words change color, the sweep runs left to right, and at 1 they rest in vermilion.
- Check spacing and wrapping are unchanged by the highlight: highlighted words keep the bubble's font size, weight, and line height.
- Compare paper, ink, and accent tones and both sides; note that the accent tone hides an accent highlight.
- Verify at a narrow width that long words wrap inside the bubble and the tail stays attached.

## Docs

- [Desk illustrations guide](https://jbm-ui.bns.studio/docs/desk-components.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [ChatBubble (chat-bubble)](https://jbm-ui.bns.studio/catalog/chat-bubble.md)
- [TextFill (text-fill)](https://jbm-ui.bns.studio/catalog/text-fill.md)

Imported in examples:

- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
