makersclaw 0.7.0 → 0.8.1

package/registry/blocks/time-strip/README.md

@@ -0,0 +1,141 @@
+# TimeStrip
+
+One bar for a span that has a length, with marks at the times that matter.
+
+A four-minute client call is a bar from `00:00` to `04:12`. Nine things were
+cut from it, and each is a thin post on the bar at the time it was said, in the
+colour of its kind. A person sees *where in the call* the sensitive things
+happened, and presses one to go there. The stretch before the client joined is
+hatched. The same bar sits small under a record's title and large as a
+screen's signature.
+
+It draws marks the app has already placed. It plays nothing, cuts nothing and
+measures nothing. For a chain of dated phases with gates use `schedule-ruler`;
+for progress against a clock `pace-bar`; for events on an hour grid
+`time-grid`; for a waveform with a playhead `audio-player`.
+
+Born in a minutes app that drew it by hand on three screens: a call's cuts under
+its title, the same strip large with the transcript, and a part of the call
+picked out to minute.
+
+```jsx
+import { TimeStrip, toSeconds, clockOf } from "../components/blocks/time-strip";   // a Makersclaw app ("./blocks/time-strip" from components/)
+import { TimeStrip } from "@/components/makersclaw/blocks/time-strip";   // a shadcn project
+```
+
+A client component. No other block and no npm package. Positions are
+percentages of the length, so the server and the browser draw the same picture;
+nothing is measured except at the moment a person drags.
+
+## Times
+
+A time is a number of seconds from the start, or a string: `"76"`, `"01:16"`,
+`"1:02:03"`. A time that is none of these has no place on the bar: its mark is
+left out, never rounded into one. A time past the end sits at the end.
+`toSeconds("01:16")` is `76`; `clockOf(3723)` is `"1:02:03"` and `clockOf(252)`
+is `"04:12"`.
+
+## Props
+
+- `length` — how long the span is: seconds, or a time string. Required. With no
+  length the bar is empty and says "Nothing to show".
+- `marks` — `[{ id, at, hue?, tone?, label? }]`. `at` is the mark's time.
+  - `hue` — `1` to `5`: a category colour (a reason, a speaker, a kind).
+  - `tone` — `neutral` · `primary` · `info` · `success` · `warning` ·
+    `danger`: a status. `hue` wins over `tone`. Neither: ink.
+  - `label` — what a reader hears: "Pricing". Spoken as "Pricing, mark at
+    00:12".
+  - Any other key is kept and handed back to `onMark`.
+- `away` — stretches somebody was away, hatched: `[[from, to]]` or `[{ from, to,
+  label? }]`. A stretch with nothing inside the bar is dropped.
+- `selection` — `{ from, to }`: the part picked, drawn with a frame and a handle
+  at each end.
+- `onSelect(range | null)` — makes the bar pick-able: drag across it to pick a
+  part (`{ from, to }`, in seconds, snapped to `step`); a press that goes nowhere
+  clears it (`null`). The two handles are sliders: ← → move one by `step`, with
+  Shift by ten steps, Home and End go to the ends, Esc clears. **Give a keyboard
+  path of your own as well** (two time fields) for a person who cannot drag.
+- `selected` — the id of the mark to show pressed (taller, ringed).
+- `onMark(mark)` — makes the marks buttons. Called with the mark as laid out
+  (`{ ...yours, seconds, share, pct }`). ← → on a focused mark moves to the next
+  or the one before. Without it the marks are plain pictures with a label.
+- `size` — `sm` (22 px, default) or `lg` (44 px).
+- `axis` — `true` (default): about `ticks` labels under the bar on whole steps,
+  always the start and the end. `false`: none. Or your own labels,
+  `[{ at, label? }]`: `[{ at: 0, label: "00:00 · before the client joined" },
+  { at: 252, label: "after they left · 04:12" }]`. The first label keeps to the
+  left edge and the last to the right, so a long word never leaves the bar.
+- `ticks` — how many labels `axis: true` aims for (2 to 12). Default 5.
+- `step` — seconds a drag snaps to and a key moves by. Default 1.
+- `noun` — what a mark is called in the words a reader hears. Default `mark`.
+- `label` — the bar's name for a reader. Default "Timeline".
+- `status` — `ready` (default), `loading` (a grey bar) or `failed` (a notice
+  with `error` and, if you pass `onRetry`, Try again).
+- `className` — layout: width and margin. Never colour.
+
+## Helpers
+
+Plain functions from the same folder, safe on the server:
+
+- `toSeconds(value)` → seconds or `null`; `clockOf(seconds)` → `"04:12"`.
+- `marksOf(marks, length)` — the marks as laid out, in time order, each with
+  `seconds`, `share` (0..1) and `pct`.
+- `rangeOf(a, b, length)` — two times as an ordered range kept inside the bar,
+  or `null` when they enclose nothing. `rangesOf(ranges, length)` for a list.
+- `ticksFor(length, count)` — the axis ticks. `shareOf`, `pctOf`, `secondsAt`.
+- `nextMark(marks, currentId, dir)` — where a key goes.
+- `stripWords({ length, marks, noun })` — "9 marks in 04:12".
+
+## Example
+
+A call's cuts under its title, large with the transcript, and a part to pick.
+
+```jsx
+"use client";
+import { useState } from "react";
+import { TimeStrip } from "../components/blocks/time-strip";
+
+const FAMILY = { pricing: 1, third_party: 2, off_record: 3, joke: 4 };
+
+export function CallStrip({ call, cuts, onGoTo }) {
+  const [part, setPart] = useState(null);
+  return (
+    <>
+      <TimeStrip
+        label="The call, with every cut where it was said"
+        noun="cut"
+        length={call.length}
+        away={[[0, call.joinedAt], [call.leftAt, call.length]]}
+        marks={cuts.map((c) => ({ id: c.id, at: c.at, hue: FAMILY[c.reason] ?? 4, label: c.reasonLabel }))}
+        onMark={(m) => onGoTo(m.id)}
+        axis={[
+          { at: 0, label: "00:00 · before the client joined" },
+          { at: call.length, label: `after they left · ${call.lengthWords}` },
+        ]}
+        size="lg"
+      />
+      <TimeStrip length={call.length} selection={part} onSelect={setPart} step={5} />
+    </>
+  );
+}
+```
+
+## States
+
+Drawn in `demo.jsx`: a call with nine marks in four colours, large and small; a
+stretch away at each end; a pressed mark; marks pressable and read-only; a part
+picked, and the bar to pick one; an hour-long call with twenty marks; marks on
+the same second; a mark past the end and one with a bad time; a call with no
+marks; no length; the app's own axis labels; loading; failed; a 320 px
+container.
+
+## What it will not do
+
+- Play, scrub or cut the thing it shows. It is a picture of marks.
+- Keep the marks. Add, move and remove them in your own data and pass the list.
+- Draw two rows (one lane per speaker): use one strip per lane.
+- Colour a mark by anything but `hue` or `tone`.
+
+A strip it cannot be is your own component in `components/`, built from the
+kit, not an edit to this block. Its files are fixed: `npm run check` refuses a
+change, and `makersclaw add time-strip` restores them.

package/registry/blocks/time-strip/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "time-strip",
+  "title": "TimeStrip",
+  "description": "One bar for a span that has a length (a call, a recording, a shift), from 0 to its end, with marks at the times that matter on it. Each mark is a thin coloured post at its time (a category colour 1 to 5, or a status tone); a pressed mark is taller and ringed, and arrow keys walk from one mark to the next. Stretches somebody was away are hatched; a part can be dragged out on the bar and its two ends nudged with the arrow keys (a slider each), and the bar says it back in words. An axis under it names the start, the end and the whole steps between (00:00, 15:00, 30:00, 58:40), or the app's own labels (\"before the client joined\"). A small bar (22 px) sits under a record's title; a large one (44 px) is the screen's signature. Positions are percentages of the length, so it draws the same on the server. Loading and failed are drawn; the sums (toSeconds, clockOf, marksOf, rangeOf, ticksFor, nextMark) are exported as plain functions.",
+  "useWhen": "A thing that has a length in time and events at moments inside it: the cuts, decisions and comments on a recorded call or meeting, the chapters of a video, the notes pinned to a recording, the incidents in a shift or a day, the stops in a route. It draws marks the app already placed; it does not play, cut or measure anything. Not a dated chain with gates (schedule-ruler), progress against a clock (pace-bar), a calendar of events on an hour grid (time-grid, calendar-view), or an audio waveform with a playhead (audio-player).",
+  "tags": ["time", "strip", "timeline", "marks", "markers", "call", "meeting", "recording", "transcript", "chapters", "cuts", "range", "select a part", "scrubber", "minutes", "duration", "axis", "agent"],
+  "exports": ["TimeStrip", "clockOf", "countMarks", "lengthOf", "marksOf", "nextMark", "pctOf", "rangeOf", "rangesOf", "secondsAt", "shareOf", "stripWords", "ticksFor", "toSeconds"],
+  "files": ["index.js", "time-strip.jsx", "strip-model.js"],
+  "requires": []
+}

package/registry/blocks/time-strip/demo.jsx

@@ -0,0 +1,129 @@
+"use client";
+
+// TimeStrip in every state — the gallery's and the smoke test's surface. Not
+// installed into apps: `makersclaw add time-strip` lays index.js,
+// time-strip.jsx and strip-model.js only.
+//   A call        nine cuts in four colours, small and large, the stretch
+//                 before the client joined and after they left hatched, a
+//                 pressed mark, the app's own axis labels.
+//   Pressable     onMark: the marks are buttons, one is pressed; read-only
+//                 without it.
+//   A part        the bar to pick one (drag, or the handles' keys), the part
+//                 said back.
+//   An hour       twenty marks on a 58:40 call; marks on the same second.
+//   Odd times     a mark past the end, a mark with a bad time, no marks, no
+//                 length.
+//   Loading, failed, and a 320 px container.
+import { useState } from "react";
+import { Button } from "../components/ui";
+import { TimeStrip, clockOf, toSeconds } from "../components/blocks/time-strip";
+
+const CALL = 252;
+const CUTS = [
+  { id: "c1", at: "00:04", hue: 1, label: "Pricing" },
+  { id: "c2", at: "00:12", hue: 1, label: "Pricing" },
+  { id: "c3", at: "00:20", hue: 4, label: "Small talk" },
+  { id: "c4", at: "00:31", hue: 2, label: "Third party" },
+  { id: "c5", at: "00:58", hue: 2, label: "Another client" },
+  { id: "c6", at: "01:02", hue: 4, label: "Joke" },
+  { id: "c7", at: "02:44", hue: 2, label: "Third party" },
+  { id: "c8", at: "03:05", hue: 3, label: "Off the record" },
+  { id: "c9", at: "04:02", hue: 1, label: "Internal" },
+];
+const AWAY = [
+  [0, 18],
+  [232, 252],
+];
+const HOUR = 3520;
+const MANY = Array.from({ length: 20 }, (_, i) => ({ id: `h${i}`, at: 30 + i * 172, hue: (i % 4) + 1, label: "Cut" }));
+
+function Section({ title, note, children }) {
+  return (
+    <section className="grid min-w-0 gap-2">
+      <h2 className="text-sm font-semibold">{title}</h2>
+      {note ? <p className="text-xs text-muted-foreground">{note}</p> : null}
+      {children}
+    </section>
+  );
+}
+
+export default function Demo() {
+  const [on, setOn] = useState("c4");
+  const [part, setPart] = useState({ from: 0, to: 120 });
+  const [lastPart, setLastPart] = useState(null);
+  return (
+    <div className="grid min-w-0 gap-8 p-4">
+      <Section title="A call, small" note="Nine cuts in four colours; the first and last stretch away are hatched.">
+        <TimeStrip label="The call, with every cut where it was said" noun="cut" length={CALL} marks={CUTS} away={AWAY} />
+      </Section>
+
+      <Section title="A call, large, with the app's own axis" note="Press a cut: it stands taller, and ← → walk to the next.">
+        <TimeStrip
+          size="lg"
+          label="The call, large"
+          noun="cut"
+          length="04:12"
+          marks={CUTS}
+          away={AWAY}
+          selected={on}
+          onMark={(m) => setOn(m.id)}
+          axis={[
+            { at: 0, label: "00:00 · before the client joined" },
+            { at: 60 },
+            { at: 120 },
+            { at: 180 },
+            { at: CALL, label: "after they left · 04:12" },
+          ]}
+        />
+        <p className="text-xs text-muted-foreground">Pressed: {CUTS.find((c) => c.id === on)?.label} at {clockOf(toSeconds(CUTS.find((c) => c.id === on)?.at))}</p>
+      </Section>
+
+      <Section title="Read-only" note="No onMark: the marks are pictures with a label.">
+        <TimeStrip noun="cut" length={CALL} marks={CUTS} away={AWAY} />
+      </Section>
+
+      <Section title="Pick a part" note="Drag across the bar. The handles are sliders (← → one step, Shift ten, Esc clears).">
+        <TimeStrip length={CALL} marks={CUTS} selection={part} onSelect={(r) => { setPart(r); setLastPart(r); }} step={5} noun="cut" />
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <span>{part ? `Part: ${clockOf(part.from)} to ${clockOf(part.to)}` : "The whole call"}</span>
+          <Button size="sm" onClick={() => setPart(null)}>Whole call</Button>
+          {lastPart === null ? <span>(cleared)</span> : null}
+        </div>
+      </Section>
+
+      <Section title="An hour, twenty marks" note="58:40 on one bar.">
+        <TimeStrip noun="cut" length={HOUR} marks={MANY} away={[[0, 60], [3400, HOUR]]} axis ticks={5} />
+      </Section>
+
+      <Section title="Two marks on the same second">
+        <TimeStrip noun="cut" length={CALL} marks={[{ id: "a", at: 90, hue: 1 }, { id: "b", at: 90, hue: 3 }, { id: "c", at: "01:31", hue: 2 }]} onMark={() => {}} />
+      </Section>
+
+      <Section title="Odd times" note="A mark past the end sits at the end; a mark with a bad time is left out.">
+        <TimeStrip noun="mark" length={CALL} marks={[{ id: "a", at: 9999, tone: "danger", label: "After the end" }, { id: "b", at: "soon", tone: "warning" }, { id: "c", at: 60, tone: "success" }, { id: "d", at: "1:02:03", tone: "info" }]} />
+      </Section>
+
+      <Section title="No marks">
+        <TimeStrip length={CALL} marks={[]} noun="cut" />
+      </Section>
+
+      <Section title="No length">
+        <TimeStrip length={0} marks={CUTS} />
+      </Section>
+
+      <Section title="Loading">
+        <TimeStrip status="loading" length={CALL} />
+      </Section>
+
+      <Section title="Failed">
+        <TimeStrip status="failed" error="The call's times could not be read." onRetry={() => {}} />
+      </Section>
+
+      <Section title="Narrow (320 px)">
+        <div className="w-80 max-w-full">
+          <TimeStrip size="lg" noun="cut" length={CALL} marks={CUTS} away={AWAY} onMark={() => {}} axis={[{ at: 0, label: "00:00 · before" }, { at: CALL, label: "after · 04:12" }]} />
+        </div>
+      </Section>
+    </div>
+  );
+}

package/registry/blocks/time-strip/index.js

@@ -0,0 +1,19 @@
+// The TimeStrip block — `makersclaw add time-strip`. Fixed: compose it
+// through its props (README.md beside this file). The model's helpers are
+// plain functions; they work on the server too.
+export { TimeStrip } from "./time-strip";
+export {
+  clockOf,
+  countMarks,
+  lengthOf,
+  marksOf,
+  nextMark,
+  pctOf,
+  rangeOf,
+  rangesOf,
+  secondsAt,
+  shareOf,
+  stripWords,
+  ticksFor,
+  toSeconds,
+} from "./strip-model";

package/registry/blocks/time-strip/strip-model.js

@@ -0,0 +1,178 @@
+// time-strip: the arithmetic (registry/blocks/time-strip/strip-model.js).
+//
+// The block draws one bar for a span that has a length (a call, a recording,
+// a shift) and puts marks on it. What has to be right is where a mark lands
+// (a share of the length, clamped), how a time is read and said ("04:12",
+// "1:02:03"), which ticks the axis shows, how a dragged range is ordered
+// and kept inside the bar, and which mark a key moves to. All plain
+// functions, no React, so the server draws what the browser draws.
+//
+// A time is a number of seconds from the start, or a string "mm:ss",
+// "h:mm:ss" or "hh:mm:ss". Anything else is null: a bad time is never
+// rounded into a place on the bar.
+
+const MAX_LENGTH = 7 * 24 * 3600;
+
+/** Seconds in a time: 76, "01:16", "1:02:03", "76" → 76, 76, 3723, 76. null when it is not a time. */
+export function toSeconds(value) {
+  if (typeof value === "number") return Number.isFinite(value) && value >= 0 ? value : null;
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (!text) return null;
+  if (/^\d+(\.\d+)?$/.test(text)) return Number(text);
+  const parts = text.split(":");
+  if (parts.length < 2 || parts.length > 3 || !parts.every((p) => /^\d{1,2}(\.\d+)?$/.test(p))) return null;
+  const nums = parts.map(Number);
+  if (nums.slice(1).some((n) => n >= 60)) return null;
+  return nums.reduce((total, n) => total * 60 + n, 0);
+}
+
+/** A span's length in whole seconds, or 0 when it has none. */
+export function lengthOf(value) {
+  const s = toSeconds(value);
+  if (s == null || s <= 0) return 0;
+  return Math.min(MAX_LENGTH, Math.round(s));
+}
+
+const two = (n) => String(n).padStart(2, "0");
+
+/** Seconds as a clock: 252 → "04:12"; 3723 → "1:02:03". `long` forces hours: 252 → "0:04:12". */
+export function clockOf(seconds, { long = false } = {}) {
+  const s = toSeconds(seconds);
+  if (s == null) return "";
+  const whole = Math.round(s);
+  const h = Math.floor(whole / 3600);
+  const m = Math.floor((whole % 3600) / 60);
+  const sec = whole % 60;
+  return h > 0 || long ? `${h}:${two(m)}:${two(sec)}` : `${two(m)}:${two(sec)}`;
+}
+
+/** Where a time sits on the bar, as a share 0..1 of `length`. null when it is not a time or there is no length. */
+export function shareOf(at, length) {
+  const s = toSeconds(at);
+  const total = lengthOf(length);
+  if (s == null || total <= 0) return null;
+  return Math.min(1, Math.max(0, s / total));
+}
+
+/** A share as a percent of the bar, rounded to a thousandth so the markup is steady. */
+export function pctOf(share) {
+  if (share == null) return null;
+  return Math.round(share * 100000) / 1000;
+}
+
+/**
+ * The marks a bar draws: `[{ id, at, ... }]` in time order, each with its
+ * `seconds`, `share` and `pct`. A mark with no readable time is left out (it
+ * has no place); a time past the end sits at the end. Ties keep the order
+ * given. `id` falls back to its index.
+ */
+export function marksOf(marks, length) {
+  const total = lengthOf(length);
+  if (!Array.isArray(marks) || total <= 0) return [];
+  const out = [];
+  marks.forEach((m, index) => {
+    if (!m || typeof m !== "object") return;
+    const seconds = toSeconds(m.at);
+    if (seconds == null) return;
+    const share = shareOf(seconds, total);
+    out.push({ ...m, id: m.id ?? `m${index}`, index, seconds: Math.min(seconds, total), share, pct: pctOf(share) });
+  });
+  return out.sort((a, b) => a.seconds - b.seconds || a.index - b.index);
+}
+
+/**
+ * Stretches laid on the bar (the part the person was away, a selection):
+ * `[[from, to]]` or `[{ from, to, label? }]`. Each is ordered, kept inside
+ * [0, length] and dropped when nothing is left of it.
+ */
+export function rangesOf(ranges, length) {
+  const total = lengthOf(length);
+  if (!Array.isArray(ranges) || total <= 0) return [];
+  const out = [];
+  for (const r of ranges) {
+    const raw = Array.isArray(r) ? { from: r[0], to: r[1] } : r;
+    const r2 = rangeOf(raw?.from, raw?.to, total);
+    if (r2) out.push({ ...(Array.isArray(r) ? {} : raw), ...r2 });
+  }
+  return out;
+}
+
+/** Two times as a range kept inside the bar and in order: { from, to, fromPct, widthPct } or null when they enclose nothing. */
+export function rangeOf(a, b, length, { min = 0 } = {}) {
+  const total = lengthOf(length);
+  const x = toSeconds(a);
+  const y = toSeconds(b);
+  if (x == null || y == null || total <= 0) return null;
+  const from = Math.min(total, Math.max(0, Math.min(x, y)));
+  const to = Math.min(total, Math.max(0, Math.max(x, y)));
+  if (to - from <= min) return null;
+  return { from, to, fromPct: pctOf(from / total), widthPct: pctOf((to - from) / total) };
+}
+
+/** A pointer's place on the bar (0..1 across it) as a time, snapped to `step` seconds. */
+export function secondsAt(fraction, length, step = 1) {
+  const total = lengthOf(length);
+  if (total <= 0 || !Number.isFinite(fraction)) return 0;
+  const raw = Math.min(1, Math.max(0, fraction)) * total;
+  const s = Math.max(1, Number(step) || 1);
+  return Math.min(total, Math.round(raw / s) * s);
+}
+
+/** A nice step under `want` seconds: 1, 2, 5, 10, 15, 30 s; 1, 2, 5, 10, 15, 30 min; 1, 2, 3, 6, 12 h. */
+const STEPS = [1, 2, 5, 10, 15, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200, 10800, 21600, 43200];
+
+/**
+ * Axis ticks for a bar: about `count` evenly spaced labels, always the start
+ * and the end. `[{ at, label, share, pct, edge }]`; `edge` is "start" or
+ * "end" for the two ends so a label can be kept inside the bar. The inner
+ * ticks fall on whole steps (a quarter hour, a minute) and are dropped when
+ * they would crowd the end.
+ */
+export function ticksFor(length, count = 5) {
+  const total = lengthOf(length);
+  if (total <= 0) return [];
+  const want = Math.max(2, Math.min(12, Math.round(count)));
+  const raw = total / (want - 1);
+  // The whole step nearest the even spacing, a little over at most: 63 s apart is a minute, not two.
+  const step = [...STEPS].reverse().find((s) => s <= raw * 1.25) ?? STEPS[0];
+  const at = [0];
+  for (let t = step; t < total; t += step) {
+    if (total - t < step * 0.4) break;
+    at.push(t);
+  }
+  at.push(total);
+  return at.map((t, i) => ({ at: t, label: clockOf(t), share: t / total, pct: pctOf(t / total), edge: i === 0 ? "start" : i === at.length - 1 ? "end" : null }));
+}
+
+/**
+ * The mark a key moves to from `current` (an id, or null): `dir` 1 the next
+ * in time, -1 the one before; at either end it stays. With nothing current,
+ * 1 goes to the first and -1 to the last.
+ */
+export function nextMark(marks, current, dir) {
+  if (!marks.length) return null;
+  const at = marks.findIndex((m) => m.id === current);
+  if (at < 0) return (dir < 0 ? marks[marks.length - 1] : marks[0]).id;
+  const to = Math.min(marks.length - 1, Math.max(0, at + (dir < 0 ? -1 : 1)));
+  return marks[to].id;
+}
+
+/** How many marks of each hue / tone: { 1: 2, danger: 1, none: 3 }, for the words a screen reader hears. */
+export function countMarks(marks) {
+  const out = {};
+  for (const m of marks) {
+    const key = m.hue ? String(m.hue) : (m.tone ?? "none");
+    out[key] = (out[key] ?? 0) + 1;
+  }
+  return out;
+}
+
+/** One line for a reader: "9 marks on a 04:12 call", "No marks". */
+export function stripWords({ length, marks, noun = "mark" }) {
+  const total = lengthOf(length);
+  const n = marks.length;
+  if (total <= 0) return "Nothing to show";
+  const word = n === 1 ? noun : `${noun}s`;
+  return n ? `${n} ${word} in ${clockOf(total)}` : `No ${noun}s in ${clockOf(total)}`;
+}