# Tear (tear)

> A sheet torn into strips along seams: controlled progress moves each strip to its own destination, with frayed, seeded edges at every seam.

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

## Install

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

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

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

## API

### `Tear` (component)

A w × h Paper-style sheet cut at `seams` into strips. At progress 0 the strips tile the sheet exactly and no seam shows; as progress rises each strip parts from its neighbours and then drifts and turns toward its destination (tearMotion), its frayed seam edges fade in over its first 5% of travel, and the sheet's shadow hands over to per-strip shadows. A seam that has not opened yet shows no line and no shadow, even while other strips move. Writing is laid out once on the whole sheet and clipped to each strip. Strips travel past the w × h root: reserve tearBounds. Pure React, controlled, and deterministic per frame.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Sheet width in stage px. |
| `h` | `number` | required | Sheet height in stage px. |
| `seams` | `number[]` | required | Seam y positions in stage px from the top; n usable seams make n + 1 strips. Non-finite values, seams closer than frayReach(fray) + 4 to an edge, and seams closer than twice that to the previous seam are dropped (see tearSeams). |
| `progress` | `number` | required | 0 = the whole sheet, 1 = every strip at its destination. Clamped and not eased; ease it yourself. |
| `pieces` | `TearPiece[]` | `[]` | Destinations top to bottom: `{ to: { x, y, rotate } }`, an offset in stage px from the strip's place in the whole sheet and a turn in degrees about the strip's centre. A missing entry or field stays put. `y` follows the strip's progress and `x` and `rotate` its square (tearMotion). With a stagger, give every strip but the last a y at or above the one below it (the last may move down), so no strip slides back into its neighbour. |
| `stagger` | `number` | `0` | Delay between strips as a share of progress: strip i starts at i × stagger and all finish at 1. Capped at 0.9 / (strips − 1). |
| `seed` | `number` | `1` | Fray pattern. Paper's starting tear with the same seed, seam y, and w follows the same edge. |
| `fray` | `number` | `FRAY` | Fray amplitude in stage px (default FRAY, 6); edges stay within 1.8 × fray of the seam. |
| `tone` | `PaperTone` | `"paper"` | "paper" (card fill, ink edge), "accent", or "ink", as in Paper. |
| `radius` | `number` | none | Corner radius of the sheet's four outer corners in stage px; strips keep square corners at seams. Default sheetRadius(w) from Register (6 px on a 360 px sheet, 6 × w / 360, at least 4), so a torn page keeps the corners of the Register sheet it was. |
| `edge` | `boolean` | `true` | Draws the shared outline (stroke.outline) on straight edges and, once torn, on frayed edges. |
| `shadow` | `boolean` | `true` | Paper shadow for the sheet and then each strip. |
| `children` | `ReactNode \| ((piece: TearPieceInfo) => ReactNode)` | none | The sheet's writing on the whole w × h sheet, clipped to each strip. A node is repeated in every strip; a function `({ index, top, bottom, progress }) => node` is called per strip (coordinates are the sheet's). Copies after the first strip are aria-hidden. |
| `contentStyle` | `CSSProperties` | none | Styles for the w × h content layer each strip clips, for padding or layout. |
| `style` | `CSSProperties` | none | Inline styles merged onto the w × h root. |

### `tearGeometry` (function)

Outlines for every strip in sheet coordinates. Neighbouring strips share the identical frayed polyline, so together they cover the sheet exactly; with an edge the straight sides sit half the shared outline (1.5px) in, on the centreline of Paper's border.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Sheet width in stage px. |
| `h` | `number` | required | Sheet height in stage px. |
| `seams` | `number[]` | required | Seam y positions; filtered by tearSeams. |
| `seed` | `number` | `1` | Fray pattern; default 1. |
| `fray` | `number` | `FRAY` | Fray amplitude; default FRAY. |
| `radius` | `number` | none | Outer corner radius; default sheetRadius(w), Register's sheet corner. |
| `edge` | `boolean` | `true` | Insets the straight sides by half the shared outline, on its centreline; default true. |

Returns: One `{ index, top, bottom, outline, edges, seamAbove, seamBelow, center }` per strip: SVG path data for the closed outline, the straight edges, and each frayed seam (null at the sheet's top or bottom), plus the rotation centre.

### `tearMotion` (function)

Where a strip is at its own progress: it parts along the seam first and drifts and turns as it travels, so the two torn edges of a seam separate as parallel copies and never cross while close.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `to` | `TearDestination` | `{}` | The strip's destination `{ x?, y?, rotate? }`. |
| `progress` | `number` | required | The strip's own 0–1 progress (tearPieceProgress); clamped. |

Returns: `{ x, y, rotate }`: to.x × p², to.y × p, to.rotate × p².

### `tearBounds` (function)

The box every strip, and with `shadow` its shadow, stays inside at every progress, in the sheet's px (origin at its top-left, so x and y can be negative). Tear's root is only w × h; reserve this box around it.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Sheet width in stage px, as passed to Tear. |
| `h` | `number` | required | Sheet height in stage px. |
| `seams` | `number[]` | required | Seam y positions; filtered by tearSeams. |
| `pieces` | `TearPiece[]` | `[]` | The strips' destinations, as passed to Tear. |
| `fray` | `number` | `FRAY` | Fray amplitude; default FRAY. |
| `shadow` | `boolean` | `true` | Includes the shadows' room (default true): 16px at the sides, 8px above, and 34px below. |

Returns: `{ x, y, w, h }` in stage px.

### `tearSeams` (function)

The seams Tear uses, from the ones you pass.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `h` | `number` | required | Sheet height in stage px. |
| `seams` | `number[]` | required | Candidate seam y positions. |
| `fray` | `number` | `FRAY` | Fray amplitude; default FRAY. |

Returns: Finite seams, sorted, at least frayReach(fray) + 4 inside the sheet and at least twice that apart, so frayed edges never cross each other or the sheet's edge.

### `tearPieceProgress` (function)

One strip's own travel after stagger.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `progress` | `number` | required | 0–1 overall progress. |
| `index` | `number` | required | Strip index, top to bottom. |
| `count` | `number` | required | Number of strips. |
| `stagger` | `number` | `0` | Share of progress between strip starts; default 0. |

Returns: 0–1: clamp((progress − index × stagger) / (1 − stagger × (count − 1))).

### `TearProps` (type)

Props of Tear.

### `TearPiece` (type)

`{ to?: TearDestination }`, one entry of `pieces`.

### `TearDestination` (type)

`{ x?: number; y?: number; rotate?: number }`: offset in stage px and turn in degrees.

### `TearPieceInfo` (type)

`{ index, top, bottom, progress }`, what a render-prop child receives per strip.

### `TearGeometry` (type)

One strip from tearGeometry.

## Stage

fluid: The root is exactly w × h stage px, the size of the whole sheet; strips move by their destinations beyond it without changing layout. tearBounds(props) returns the box, relative to the root, that every strip and its shadow stays inside at any progress; give the stage at least that. The gallery sizes its stage as the union of tearBounds over every seam count it offers (a 520 × 760 sheet on a stage about 640 × 1000), so no strip or shadow is ever clipped.

## Examples

### A long page tearing into four register strips

```tsx
import { Tear } from "@/jbm/ui/tear"

// progress comes from your timeline, e.g. interpolate(frame, [0, 45], [0, 1]).
<Tear
  w={520}
  h={760}
  seams={[190, 380, 570]}
  progress={0.6}
  stagger={0.1}
  pieces={[
    { to: { x: -40, y: -70, rotate: -5 } },
    { to: { x: 36, y: -24, rotate: 3 } },
    { to: { x: -30, y: 24, rotate: -2 } },
    { to: { x: 34, y: 72, rotate: 3 } },
  ]}
>
  {({ index, top }) => (
    <div style={{ position: "absolute", left: 40, top: top + 32 }}>strip {index + 1}</div>
  )}
</Tear>
```

### Continue a Paper's starting tear

```tsx
import { Paper } from "@/jbm/ui/paper"
import { sheetRadius } from "@/jbm/ui/register"
import { Tear } from "@/jbm/ui/tear"

// The same seed, seam, and width give the same frayed edge in both; Tear defaults to the sheetRadius(w) corner.
export function Page({ torn }: { torn: boolean }) {
  return torn ? (
    <Tear w={520} h={760} seams={[380]} progress={0.4} pieces={[{ to: { y: -40, rotate: -3 } }, { to: { y: 40, rotate: 4 } }]} />
  ) : (
    <Paper w={520} h={760} radius={sheetRadius(520)} tension={1} seam={380} />
  )
}
```

## QA

- At Tear 0 the sheet must look whole: no seam line, hairline, or shadow between strips. Compare it with a plain Paper of the same size and radius.
- Drag Tear through 0.02, 0.05, 0.5, and 1: seam edges fade in as the strips part, each strip keeps its frayed edges, and later strips overlap earlier ones.
- At 8× zoom check where a frayed seam meets a straight side: the lines join on one centreline with the same 2px width, and each seam side is one clean frayed edge of irregular grain, not a regular zig-zag or two offset rows of teeth.
- Drag Tear through 0.03 and 0.1 with Stagger 0.1 and 0.3: the parting strips' torn edges run as parallel copies and never cross, and the seams that have not opened yet show no line or shadow; the sheet's straight sides stay unbroken there.
- Step Seams from 1 to 4 and Fray seed from 1 to 9: seams run only through clear rows of the page (a fray reach from every bar, header, numeral, and chevron, 8px from every box edge and table rule), so no torn edge cuts a table header or a bar into a black zig-zag or grazes a rule, frayed edges never cross each other or the sheet's edge, the pattern changes only with the seed, and every strip and shadow stays inside the stage.
- Set Stagger to 0 and 0.3: every strip still reaches its destination at progress 1.

## Family

Paper & writing

## 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)
- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)
- [Register (register)](https://jbm-ui.bns.studio/catalog/register.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
