jbmui

Register

  • UI Bits
  • adjustable

Paper sheet of drawn writing whose shape says who reads it: steps, lists, tables, sourced prose, or a mixed page.

Count7 steps

Install

npx shadcn@latest add @jbm/register

Needs the @jbm entry in components.json; see Install once.

Also installs @jbm/tokens, @jbm/scene-geometry, @jbm/paper.

Docs

Usage

Four readers, four registers
import { Register } from "@/jbm/ui/register"<div style={{ display: "flex", gap: 24 }}>  <Register kind="mono" n={7} w={300} h={380} />  <Register kind="plain" n={10} w={300} h={380} />  <Register kind="grid" n={7} w={300} h={380} />  <Register kind="prose" sources={8} w={300} h={380} /></div>
Long mixed page with seams and source anchors
import { Register, registerSeams, registerAnchors } from "@/jbm/ui/register"const page = { kind: "mixed", w: 380, h: 840 } as constconst seams = registerSeams(page) // three y positions: tear linesconst anchors = registerAnchors(page) // prose source ticks: thread origins<Register {...page} reveal={0.6} />
A destination making room
import { Register, registerGap } from "@/jbm/ui/register"const reflow = 0.5 // from a slider or frameconst sheet = { kind: "prose", n: 3, w: 250, h: 300, gapAt: 4, gap: 66 } as constconst landing = registerGap({ ...sheet, reflow: 1 }) // where the slip settles<Register {...sheet} reflow={reflow} />

API

Stage px
Declared at the documented defaults
Landscape
300 by 380
Vertical
300 by 380
Basis

Exactly w × h stage px (the gallery uses 300 × 380, and 300 × 700 for mixed, near the board's long-page proportions); n, reveal, gap, and reflow never change the box. Rotation and the paper shadow draw outside it. On a 1920 × 1080 stage the board's quadrant sheets are about 440 × 280 and the long mixed page about 460 × 1000.

Registercomponent

A Paper sheet (ink edge at the shared outline weight, house paper shadow) carrying one register of drawn writing: bars, boxes, and rules, never legible prose. mono is a prompt chevron, prompt bar, and outlined result box per step; plain short numbered lists in two columns; grid ruled tables with an ink header; prose a justified block with paragraph ends (every fifth line and the last, never two in a row and never the first line after a gap) and a block of source ticks; mixed stacks registers on one long page. Every quantity is a prop (no timer), so a slider or video frame drives it. Anchors, seams, and the gap are in the sheet's px from its outer top-left corner, the same space children draw in.

PropTypeDefaultDescription
kindRegisterKindrequiredRegister: mono, plain, grid, prose, or mixed.
nnumbernoneSteps (mono, 0–24, default 7), list groups (plain, 0–24, default 10), tables (grid, 0–12, default 7; one column up to 4, then two, then three), source ticks (prose, 0–16, default 8), or bands (mixed, 0–4 of mono, plain, grid, prose; default 4). 0 draws a blank sheet (prose keeps its lines). Rounded and clamped. More items tighten the packing; the sheet never grows. List numerals set at 12 × scale; source ticks sit 14 × scale apart.
wnumberrequiredSheet width in stage px.
hnumberrequiredSheet height in stage px.
sourcesnumbernoneProse only: source ticks, overriding n. In mixed, the prose band's ticks (default 3).
bandsreadonly RegisterBand[]noneMixed only: the stacked registers, top to bottom, each { kind, n?, weight? } (weight sets its share of the page before row pitches are capped; each band then sits at the height its writing actually uses, bands follow each other with even separators at least 2 × (frayReach() + 2) + 8 px tall so a Tear's fray or Paper's starting notch at a seam never reaches the writing, and any leftover height collects at the foot of the page; at most 8 bands). Overrides n. Give a mixed page about the board's proportions (460 × 1000): a squatter sheet compresses every band.
gapAtnumbernoneRow index where a gap opens: mono steps, plain and grid rows of cells, prose lines then the spacer then source rows; for mixed, the band index (0 = above the first band, bands.length = below the last). Rows from here down move to make room; omit for no gap.
gapnumbernoneGap height in px when fully open. Defaults to a quarter of the writing height; clamped to 60% of it. Marks are sized for the open gap at every reflow value, so reflow moves writing without resizing it.
reflownumbernoneHow open the gap is, 0–1 (default 1): run 1 → 0 on the sheet a slip leaves (it closes) and 0 → 1 on the sheet it lands on (it makes room).
scalenumbernoneMark scale: bar thickness, strokes, and spacing. Defaults to w / 360 (clamped 0.4–4), so a 360 px sheet draws 6 px prompt bars and 1.5 px outlines.
padnumbernoneInset from the sheet edge to the writing in px (default 20 × scale).
revealnumbernoneWriting drawn so far, 0–1: cells ink in reading order, each one left to right; 0 is a blank sheet. The sheet itself is always there.
tonePaperTonenoneThe stock the writing sits on (Paper's tone, default paper): ink writing on paper; on ink or vermilion stock the writing is card-coloured and dim marks cream at 62%. Result boxes and tables are filled with the stock, so whatever lies under the writing (Paper's creases) never shows through them.
accentreadonly number[]noneCell indices (reading order, see registerLayout) whose lead mark is vermilion: the prompt bar, list heading, table header, prose line, or source tick. Everything else stays ink.
rotatenumber0Sheet rotation in degrees (Paper's rotate).
labelstringnoneAccessible name of the drawing; defaults to “Page of <kind> writing”.
childrenReactNodenoneLaid over the sheet in sheet px (a Slip at registerGap, a tab, a thread origin).
styleCSSPropertiesnoneStyles merged onto the Paper sheet, e.g. position.

RegisterInkcomponent

The writing alone as an SVG <g> in sheet px, for SVG scenes, tear pieces, or any other surface. Takes the RegisterSpec props plus reveal and accent. Render inside an <svg>.

PropTypeDefaultDescription
kindRegisterKindrequiredRegister: mono, plain, grid, prose, or mixed.
nnumbernoneSteps (mono, 0–24, default 7), list groups (plain, 0–24, default 10), tables (grid, 0–12, default 7; one column up to 4, then two, then three), source ticks (prose, 0–16, default 8), or bands (mixed, 0–4 of mono, plain, grid, prose; default 4). 0 draws a blank sheet (prose keeps its lines). Rounded and clamped. More items tighten the packing; the sheet never grows. List numerals set at 12 × scale; source ticks sit 14 × scale apart.
wnumberrequiredSheet width in stage px.
hnumberrequiredSheet height in stage px.
sourcesnumbernoneProse only: source ticks, overriding n. In mixed, the prose band's ticks (default 3).
bandsreadonly RegisterBand[]noneMixed only: the stacked registers, top to bottom, each { kind, n?, weight? } (weight sets its share of the page before row pitches are capped; each band then sits at the height its writing actually uses, bands follow each other with even separators at least 2 × (frayReach() + 2) + 8 px tall so a Tear's fray or Paper's starting notch at a seam never reaches the writing, and any leftover height collects at the foot of the page; at most 8 bands). Overrides n. Give a mixed page about the board's proportions (460 × 1000): a squatter sheet compresses every band.
gapAtnumbernoneRow index where a gap opens: mono steps, plain and grid rows of cells, prose lines then the spacer then source rows; for mixed, the band index (0 = above the first band, bands.length = below the last). Rows from here down move to make room; omit for no gap.
gapnumbernoneGap height in px when fully open. Defaults to a quarter of the writing height; clamped to 60% of it. Marks are sized for the open gap at every reflow value, so reflow moves writing without resizing it.
reflownumbernoneHow open the gap is, 0–1 (default 1): run 1 → 0 on the sheet a slip leaves (it closes) and 0 → 1 on the sheet it lands on (it makes room).
scalenumbernoneMark scale: bar thickness, strokes, and spacing. Defaults to w / 360 (clamped 0.4–4), so a 360 px sheet draws 6 px prompt bars and 1.5 px outlines.
padnumbernoneInset from the sheet edge to the writing in px (default 20 × scale).
revealnumber1Writing drawn so far, 0–1: cells ink in reading order, each one left to right; 0 is a blank sheet. The sheet itself is always there.
tonePaperTone"paper"The stock the writing sits on (Paper's tone, default paper): ink writing on paper; on ink or vermilion stock the writing is card-coloured and dim marks cream at 62%. Result boxes and tables are filled with the stock, so whatever lies under the writing (Paper's creases) never shows through them.
accentreadonly number[][]Cell indices (reading order, see registerLayout) whose lead mark is vermilion: the prompt bar, list heading, table header, prose line, or source tick. Everything else stays ink.

registerLayoutfunction

Pure geometry for a register: every cell (reading order, band, row, kind, box, lead point, anchor, marks), row slots, band boxes, mixed seams, prose anchors, and the gap box, in sheet px. Register and RegisterInk draw exactly this, so hosts can attach threads and tears to the same points.

ParamTypeDefaultDescription
specRegisterSpecrequiredRegisterSpec: kind, n, w, h, sources, bands, gapAt, gap, reflow, scale, pad.

Returns RegisterLayout { w, h, scale, cells, rows, bands, seams, anchors, gap }.

registerAnchorsfunction

Prose source tick centres (prose kind or the prose band of mixed), top to bottom, in sheet px: where threads leave the sheet.

ParamTypeDefaultDescription
specRegisterSpecrequiredRegisterSpec.

Returns Pt[]; empty when there is no prose.

registerSeamsfunction

Mixed only: the y of each seam between bands, top to bottom, in sheet px, halfway through the space between bands. Tear lines follow them.

ParamTypeDefaultDescription
specRegisterSpecrequiredRegisterSpec.

Returns number[] (bands − 1 values); empty for single registers.

registerGapfunction

The gap's box in sheet px: full writing width, height gap × reflow. Place a slip at the fully open gap (reflow 1) so its resting place does not move while the gap animates.

ParamTypeDefaultDescription
specRegisterSpecrequiredRegisterSpec with gapAt.

Returns Box, or null without gapAt.

sheetRadiusfunction

The corner radius of a writing sheet: SHEET_RADIUS × its mark scale, never under 4 px. Register draws its Paper with it and Tear defaults to it, so a torn page keeps the corners of the sheet it was; pass it to a Paper that stands in for a page.

ParamTypeDefaultDescription
wnumberrequiredSheet width in stage px.
scalenumbernoneThe sheet's mark scale, when set; defaults to w / 360 clamped to 0.4–4, as Register's.

Returns Radius in stage px (6 on a 360 px sheet).

SHEET_RADIUSconstant

6: a writing sheet's corner radius per unit of mark scale (6 px on a 360 px sheet).

RegisterKindtype

"mono" | "plain" | "grid" | "prose" | "mixed".

RegisterBandtype

One band of a mixed page: { kind, n?, weight? }.

RegisterSpectype

The geometry props shared by Register, RegisterInk, and the layout helpers.

RegisterTonetype

"ink" | "dim" | "accent": the fill of a bar mark.

RegisterMarktype

One drawn mark: bar, outlined box, rule, chevron, or numeral, in sheet px.

RegisterCelltype

One unit of writing: index, band, row, kind, box, lead, optional anchor, marks.

RegisterLayouttype

registerLayout's result.

RegisterInkPropstype

RegisterSpec plus reveal and accent.

RegisterPropstype

RegisterInkProps plus rotate, label, children, style.

QA checks

  • Switch Kind through all five: each reads as one register at a glance (steps with result boxes, numbered lists, ruled tables, a justified block with source ticks, a stacked page) and no mark forms a legible word.
  • Step Count from 0 to its maximum for every kind: 0 is a blank sheet (no steps, lists, tables, or bands; prose keeps its lines), marks pack tighter inside the same sheet, nothing crosses the pad or the sheet edge, and grid switches to two columns above 4 tables.
  • Mixed: every band keeps readable proportions (list numerals at 12 × scale, tables with open rows, not squeezed), and the seams sit in the even gaps between bands.
  • Drag Reveal 0 → 1: a blank sheet, then cells ink in reading order, each left to right; no mark appears early or pops.
  • Turn on Gap and drag Reflow 1 → 0 → 1: rows below the gap slide while every mark keeps its size; at 0 the writing is evenly spaced again.
  • Show seams, anchors, gap: seams sit between mixed bands, anchor rings sit on the source ticks without touching each other or the sheet edge, and the gap box is empty.
  • Accent first mark: only that lead mark turns vermilion.
  • Check 2× zoom: chevrons, result-box corners, and table rules are crisp and consistent; outlines never exceed the prompt bar's weight.