# Ejes (ejes)

> Two ink axes that split an area into four named quadrants, with quiet labels and a focus quadrant.

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

## Install

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

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/ejes.json, files[].content).

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

## API

### `Ejes` (component)

SVG <g> of two crossing ink axes with a name on each side: top and bottom flank the horizontal axis at its left end, left and right flank the vertical axis at its top end. Each axis draws by its own progress; labels arrive with their axis and can shrink to quiet. One or more quadrants can be called out by a rounded outline or light fill. Vermilion appears only with focusTone accent. Controlled; no internal timer. Render inside an <svg>, usually over DeskTop.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `box` | `Box` | required | Area the axes span { x, y, w, h }, in the parent SVG's user units; usually DeskTop's surface. |
| `center` | `Pt` | none | Where the axes cross. Defaults to the centre of box. Clamped to the range (ejesLayout().range) that keeps every label inside the box, the top and bottom labels left of the vertical axis, the right label right of it, and the top label below the left/right labels; a box too small for its labels crosses at its centre. |
| `h` | `number` | required | Horizontal axis draw progress, 0–1. Clamped. |
| `v` | `number` | required | Vertical axis draw progress, 0–1. Clamped. |
| `labels` | `EjesLabels` | required | Half-plane names { top, bottom, left, right }. An empty string hides that label. |
| `quiet` | `boolean \| number` | `false` | Label size: false or 0 is full (36 units, weight 650), true or 1 is quiet (22 units, weight 500) at the same axis ends; numbers between interpolate the size and the (variable) weight together, so an animated shrink never pops. |
| `reveal` | `Partial<Record<EjesSide, number>>` | none | Per-label opacity, 0–1, keyed top, bottom, left, right. A label left out fades in over 60 units as its axis's drawing tip passes it. |
| `origin` | `"center" \| "start"` | `"center"` | Axes grow out from the crossing (center, default) or from the left and top edges (start). |
| `focus` | `Quadrant \| readonly Quadrant[]` | none | Quadrant or quadrants to call out: tl, tr, bl, br, or an array (all four together for the "cuatro" beat). Omit for none. |
| `focusTone` | `EjesFocusTone` | `"ink"` | ink (default): ink outline. fill: light ink wash, no outline. accent: a vermilion outline on the first focused quadrant only (any others stay ink), opt-in for the one deliberate stamp (the board's @advina answer quadrant); never the default. |
| `focusProgress` | `number` | `1` | Focus draw progress, 0–1 (default 1): outlines draw around their perimeter, fills fade in. Clamped. |
| `focusInset` | `number` | `16` | Gap between a focus outline and the box edges and axes, in parent units (default 16). The four outlines are one size and hug the crossing, symmetric about both axes: as tall as the shorter row allows once the labels are cleared (the strip for the left/right labels at the top, the strips either side of the horizontal axis for the top and bottom labels) and as wide as the narrower column. An outline under 40 units on a side is not drawn. |
| `weight` | `number` | `2` | Axis and outline stroke width in parent units (default 2, the desk's line weight). |

### `ejesLayout` (function)

Axis, label, and quadrant geometry, for placing a sheet in each quadrant or a hand at an axis end.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `center` | `Pt` | none | Where the axes cross. Defaults to the centre of box. Clamped to the range (ejesLayout().range) that keeps every label inside the box, the top and bottom labels left of the vertical axis, the right label right of it, and the top label below the left/right labels; a box too small for its labels crosses at its centre. |
| `h` | `number` | required | Horizontal axis draw progress, 0–1. Clamped. |
| `box` | `Box` | required | Area the axes span { x, y, w, h }, in the parent SVG's user units; usually DeskTop's surface. |
| `v` | `number` | required | Vertical axis draw progress, 0–1. Clamped. |
| `quiet` | `boolean \| number` | `false` | Label size: false or 0 is full (36 units, weight 650), true or 1 is quiet (22 units, weight 500) at the same axis ends; numbers between interpolate the size and the (variable) weight together, so an animated shrink never pops. |
| `reveal` | `Partial<Record<EjesSide, number>>` | `{}` | Per-label opacity, 0–1, keyed top, bottom, left, right. A label left out fades in over 60 units as its axis's drawing tip passes it. |
| `origin` | `"center" \| "start"` | `"center"` | Axes grow out from the crossing (center, default) or from the left and top edges (start). |
| `focusInset` | `number` | `16` | Gap between a focus outline and the box edges and axes, in parent units (default 16). The four outlines are one size and hug the crossing, symmetric about both axes: as tall as the shorter row allows once the labels are cleared (the strip for the left/right labels at the top, the strips either side of the horizontal axis for the top and bottom labels) and as wide as the narrower column. An outline under 40 units on a side is not drawn. |
| `labels` | `Partial<EjesLabels>` | none | Optional; when given, an empty label frees its strip so focus outlines can reach the axis. |

Returns: { box, center, horizontal: { x1, x2, y }, vertical: { x, y1, y2 }, type: { size, quiet }, labels: { top|bottom|left|right: { x, y, anchor, baseline, opacity } }, quadrants: { tl|tr|bl|br: Box }, range: { x: [min, max], y: [min, max] }, focus: { tl|tr|bl|br: Box } }, in parent SVG units; a focus box too small to draw has w and h 0.

### `quadrants` (constant)

["tl", "tr", "bl", "br"]: the four quadrant keys in spoken order of the board's readers.

### `EJES_TYPE` (constant)

Label sizes in parent units: { full: 36, quiet: 22 }.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 1680 | 830 |
| Vertical (1080×1920) | 936 | 1340 |

The axes span their box exactly (parent SVG units = stage pixels); labels and focus outlines stay inside it. The numbers are the act 2 desk surface at the safe area: landscape 1920 − 2 × 120 by 920 − 90, vertical 1080 − 2 × 72 by 1440 − 100.

## Examples

### Four places on the desk, labels quiet, answer quadrant outlined

```tsx
import { Ejes } from "@/jbm/ui/ejes"

<svg viewBox="0 0 1920 1080">
  <Ejes box={{ x: 120, y: 90, w: 1680, h: 830 }} h={1} v={1} quiet
    labels={{ top: "hacer", bottom: "entender", left: "aprender", right: "trabajar" }}
    focus="tl" />
</svg>
```

### Draw the axes on a timeline (Remotion)

```tsx
import { useCurrentFrame, interpolate } from "remotion"
import { Ejes } from "@/jbm/ui/ejes"

function Brujula() {
  const frame = useCurrentFrame()
  const h = interpolate(frame, [120, 168], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" })
  const v = interpolate(frame, [204, 240], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" })
  return (
    <svg viewBox="0 0 1920 1080">
      <Ejes box={{ x: 120, y: 90, w: 1680, h: 830 }} h={h} v={v}
        labels={{ top: "hacer", bottom: "entender", left: "aprender", right: "trabajar" }} />
    </svg>
  )
}
```

### The one vermilion answer quadrant (opt-in)

```tsx
import { Ejes } from "@/jbm/ui/ejes"

<svg viewBox="0 0 1920 1080">
  <Ejes box={{ x: 120, y: 90, w: 1680, h: 830 }} h={1} v={1} quiet
    labels={{ top: "hacer", bottom: "entender", left: "aprender", right: "trabajar" }}
    focus="tr" focusTone="accent" focusProgress={0.6} />
</svg>
```

## QA

- Drag Horizontal and Vertical independently from Hidden to Drawn in both Grow from modes: each axis grows only by its own control, and each label fades in as the line reaches it, not before.
- Drag Quiet from Full to Quiet: labels shrink toward the axis ends without moving off them; at Quiet they are small but readable.
- Step Focus through each quadrant and All four with every Tone: outlines never cross a label or an axis, and all four are the same size, mirrored about both axes; Light fill has no outline; with Accent only one quadrant (the first) is vermilion, the rest ink.
- Drag Outline: the rounded outline draws around its perimeter; at 0 nothing shows.
- Check a narrow screen: the labels stay inside the box and stay legible at quiet size.
- Pass a center near a corner (e.g. { x: 90, y: 300 } in a 580 × 380 box): the crossing moves only as far as its labels allow, no label leaves the box or crosses an axis, and focus outlines too small to read are not drawn.

## 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)
- [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
