# Clock (clock)

> A deterministic analog clock and time label. Supply time explicitly for web or video.

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

## Install

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

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

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

## API

### `Clock` (component)

Analog face (dim ring, four quarter ticks, ink hour hand, vermilion minute hand) beside a mono HH:MM label. No timers: the time is (hours × 60 + minutes) wrapped to 24 hours, the hour hand moves continuously with the minutes, and the face is aria-hidden so the label carries the time. Throws RangeError for non-finite values or size ≤ 0.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `hours` | `number` | required | Hours on a 24-hour day; fractions and values outside 0–23 wrap. |
| `minutes` | `number` | `0` | Minutes added to hours; may exceed 59 (e.g. hours 0, minutes 510 is 08:30) and wraps across days. |
| `size` | `number` | `64` | Width and height of the clock face in stage pixels. |
| `label` | `string` | none | Text shown instead of the zero-padded 24-hour HH:MM derived from the time. |

Also accepts React.HTMLAttributes<HTMLDivElement>.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | auto | 64 |
| Vertical (1080×1920) | auto | 64 |

Inline-flex row: a size × size face (64 by default), a 16px gap, and the label in 22px mono. Height equals size while it exceeds the text line; width follows the label. The row wraps when its container is narrower, putting the label below the face.

## Examples

### Half past eight

```tsx
import { Clock } from "@/jbm/ui/clock"

<Clock hours={8} minutes={30} size={64} />
// Explicit time keeps rendering deterministic. No autoplay.
```

### Drive it from minutes of the day

```tsx
import { Clock } from "@/jbm/ui/clock"

const minutes = 510 // e.g. from a slider or a video frame
<Clock hours={0} minutes={minutes} size={96} label="Mañana" />
```

## QA

- Sweep the time control from 00:00 to 23:59: the minute hand completes each hour, the hour hand advances smoothly, and the label matches.
- Check 12:00 and 00:00 both point straight up and 06:00 straight down.
- At a narrow width the label wraps below the face without clipping.

## Docs

- [Visual primitives guide](https://jbm-ui.bns.studio/docs/visual-primitives.md)

## Related

Installs:

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