# PaperLine (paper-line)

> Line of text with controlled grapheme reveal, ink lift, strike-through, and dotted underline.

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

## Install

```sh
npx shadcn@latest add @jbm/paper-line
```

Also installs @jbm/tokens, @jbm/scene-geometry (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/paper-line.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/paper-line.tsx` | `src/jbm/ui/paper-line.tsx` | `@/jbm/ui/paper-line` |

## API

### `PaperLine` (component)

Inline-block line of handwritten-on-paper text. Every progress input is controlled 0–1 (clamped; non-finite values count as 0) with no timer, so a slider or video timeline drives it. Hidden graphemes keep their space, and a visually hidden copy exposes the full text to assistive technology.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | required | The line's text; revealed by whole graphemes (emoji and combined characters stay intact). |
| `reveal` | `number` | `1` | Share of graphemes shown, 0–1; visible count is ceil(reveal × graphemes). The full footprint is reserved at every value. |
| `lift` | `number` | `0` | Ink lift 0–1: the line moves up to 60px right and 40px up, rotates up to −9°, and fades (opacity 1 − lift²). |
| `strike` | `number` | `0` | Vermilion 2px strike-through across the middle, drawn left to right as 0–1 of the line width. Meant for single short lines. |
| `dotted` | `boolean` | `false` | Adds a 2px dotted underline in the dim color. |
| `accent` | `boolean` | `false` | Uses the vermilion accent for the text instead of ink. |
| `mono` | `boolean` | `false` | Uses the mono font stack instead of sans. |
| `style` | `CSSProperties` | none | Inline styles merged last onto the outer span, e.g. fontSize or fontWeight (both inherit by default). |

## Stage

fluid: Inline-block text at the inherited font size with line-height 1.4; width follows the text up to 100% of the container and height grows when it wraps. Lift translates up to 60px right and 40px up without affecting layout, so leave headroom (the gallery pads 32px above).

## Examples

### Partly written line

```tsx
import { PaperLine } from "@/jbm/ui/paper-line"

<PaperLine text="Una idea clara." reveal={0.7} lift={0} strike={0} />
```

### Crossed-out mono note

```tsx
import { PaperLine } from "@/jbm/ui/paper-line"

<PaperLine text="v1 descartada" mono dotted strike={1} style={{ fontSize: 22 }} />
```

## QA

- Drag Reveal from 0 to 1: graphemes appear left to right, the line never changes width, and 0 shows nothing.
- Drag Lift ink to 1: the line drifts up-right, tilts, and fades out completely without overlapping controls.
- Drag Strike to 1 on a single line; on a wrapped line the stroke sits at the block's vertical middle, so keep struck lines short.
- Toggle Dotted underline and Accent ink independently, and check each combination with mono.

## Docs

- [Paper and filing illustrations guide](https://jbm-ui.bns.studio/docs/design-video-components.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [SceneGeometry (scene-geometry)](https://jbm-ui.bns.studio/catalog/scene-geometry.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
