makersclaw 0.1.0 → 0.3.0

package/registry/blocks/approval-request/demo.jsx

@@ -0,0 +1,127 @@
+"use client";
+
+// ApprovalRequest with the request in memory — the gallery's and the
+// smoke test's surface. Not installed into apps: `makersclaw add
+// approval-request` lays index.js and approval-request.jsx only.
+import { useState } from "react";
+import { Button, Field, Select, Switch, ToggleGroup } from "../components/ui";
+import { ApprovalRequest } from "../components/blocks/approval-request";
+
+const VARIANTS = [
+  { value: "card", label: "Card — the request alone" },
+  { value: "page", label: "Page — details beside the card" },
+  { value: "refund", label: "Card — a refund, no reason needed" },
+];
+
+const PURCHASE = {
+  title: "Linear Business",
+  kind: "Per seat",
+  details: [
+    { label: "Starts", value: "1 October 2026", icon: "calendar" },
+    { label: "Seats", value: "24 people", icon: "users" },
+    { label: "Billed", value: "Yearly, by invoice", icon: "credit-card" },
+    { label: "Yearly cost", value: "$4,608", icon: "dollar", emphasis: true },
+  ],
+  requester: { name: "Priya Raman", role: "Head of Engineering" },
+  requestedAt: "2026-09-21",
+  justification:
+    "The team has outgrown the free plan's issue limit, and Business adds the triage queue we keep building by hand. 24 seats covers engineering and design through Q2.",
+  sections: [
+    {
+      title: "What is bought",
+      fields: [
+        { label: "Product", value: "Linear Business" },
+        { label: "Vendor", value: "Linear Orbit, Inc." },
+        { label: "Licence", value: "Per seat, cancel at renewal" },
+        { label: "Term", value: "12 months" },
+      ],
+    },
+    {
+      title: "Billing",
+      fields: [
+        { label: "Cycle", value: "Yearly" },
+        { label: "Paid by", value: "Invoice, 30 days" },
+        { label: "Cost centre", value: "Engineering" },
+        { label: "Yearly total", value: "$4,608", emphasis: true },
+      ],
+    },
+  ],
+};
+
+const REFUND = {
+  title: "Refund for order 20931",
+  kind: "Refund",
+  details: [
+    { label: "Customer", value: "Harbor & Pine Coffee", icon: "building" },
+    { label: "Reason given", value: "Charged twice for September", icon: "receipt" },
+    { label: "Amount", value: "€149.00", icon: "dollar", emphasis: true },
+  ],
+  requester: { name: "Tomás Ferreira", role: "Support" },
+  requestedAt: "2026-09-23",
+};
+
+export default function ApprovalRequestDemo() {
+  const [variant, setVariant] = useState("card");
+  const [state, setState] = useState("request");
+  const [failNext, setFailNext] = useState(false);
+  const [round, setRound] = useState(0);
+
+  async function decide() {
+    await new Promise((r) => setTimeout(r, 800));
+    if (failNext) {
+      setFailNext(false);
+      return { ok: false, error: "The decision was not saved: the server did not answer. Try again." };
+    }
+    return { ok: true };
+  }
+
+  const data = variant === "refund" ? REFUND : PURCHASE;
+  const decided = state === "approved" || state === "rejected";
+
+  return (
+    <div className="grid gap-4">
+      <div className="flex flex-wrap items-end gap-x-4 gap-y-2">
+        <Field id="ar-variant" label="Variant" className="w-full sm:w-72">
+          <Select id="ar-variant" value={variant} onChange={(e) => setVariant(e.target.value)} options={VARIANTS} />
+        </Field>
+        <ToggleGroup
+          size="sm"
+          aria-label="Demo state"
+          value={state}
+          onChange={setState}
+          items={[
+            { value: "request", label: "Pending" },
+            { value: "rejected", label: "Decided" },
+            { value: "loading", label: "Loading" },
+            { value: "empty", label: "Empty" },
+          ]}
+        />
+      </div>
+      <div className="flex flex-wrap items-center gap-x-4">
+        <Switch id="ar-fail" checked={failNext} onChange={(e) => setFailNext(e.target.checked)} label="Fail the next decision" />
+        <Button variant="quiet" size="sm" icon="refresh" onClick={() => setRound((n) => n + 1)}>
+          Start over
+        </Button>
+      </div>
+      <div className={variant === "page" ? "w-full" : "mx-auto grid w-full max-w-md"}>
+        <ApprovalRequest
+          key={`${variant}-${state}-${round}`}
+          variant={variant === "page" ? "page" : "card"}
+          heading={variant === "page" ? "Software purchase request" : undefined}
+          description={variant === "page" ? "Check the details, then approve or reject it." : undefined}
+          {...(state === "empty" ? {} : data)}
+          status={decided ? "rejected" : "pending"}
+          decidedBy={decided ? "Maya Okafor" : undefined}
+          decidedAt={decided ? "2026-09-22" : undefined}
+          decisionNote={decided ? "Over this quarter's tools budget. Ask again in January with the Q1 plan." : undefined}
+          loading={state === "loading"}
+          onApprove={decide}
+          onReject={decide}
+          reasonRequired={variant !== "refund"}
+          rejectLabel={variant === "refund" ? "Decline" : "Reject"}
+          approveLabel={variant === "refund" ? "Refund €149.00" : "Approve"}
+        />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/approval-request/index.js

@@ -0,0 +1,4 @@
+// The ApprovalRequest block — `makersclaw add approval-request`. Fixed:
+// compose it through its props (README.md beside this file); a request it
+// cannot be is your own component in components/.
+export { ApprovalRequest } from "./approval-request";

package/registry/blocks/audio-player/README.md

@@ -0,0 +1,167 @@
+# AudioPlayer
+
+A waveform audio player in the workspace theme. Play, skip back and
+forward 15 seconds, change speed, mute. Hover the waveform to read the
+time; click it to jump; drag across it to mark a region. **Regions** are
+spans of the audio in a theme tone — a topic, a speaker turn, a clip —
+tinted on the waveform and labelled in a lane under it; click a label to
+play just that span. **Markers** are moments — a comment, a flag — shown
+as pins above the waveform; click one to jump there. "Marker" adds one at
+the playhead. It loads with a skeleton waveform, says so plainly when a
+file will not play, and shows a friendly empty state when there is no
+audio yet.
+
+It is [wavesurfer.js](https://wavesurfer.xyz) (BSD-3-Clause) underneath:
+it decodes, plays and paints the waveform. Regions, markers, the hover
+line, the controls and every state are ours, in the kit. The blocks built
+on this one — `call-review` — import it, never `wavesurfer.js`.
+
+```jsx
+import { AudioPlayer, useAudioPlayer } from "../components/blocks/audio-player";   // a Makersclaw app ("./blocks/audio-player" from components/)
+import { AudioPlayer, useAudioPlayer } from "@/components/makersclaw/blocks/audio-player";   // a shadcn project
+```
+
+`AudioPlayer` is a client component: render it from a `"use client"`
+component. `formatTime`, `formatRange`, `spokenTime` and `regionAt` are
+plain functions and work on the server.
+
+`makersclaw add audio-player` adds `wavesurfer.js` and
+`@wavesurfer/react` (pinned, exact) to package.json: run `npm install`
+after. Both load with the page (no `import()`); the player itself starts
+in the browser, and until then the frame shows a skeleton waveform.
+
+## The data
+
+Times are **seconds** from the start of the audio (numbers, fractions
+allowed).
+
+```js
+// a region: a span of the audio
+{ id: "pricing", start: 12.4, end: 25.6, label: "Pricing and SSO", tone: "chart-3" }
+
+// a marker: a moment
+{ id: "m1", time: 17.2, label: "Asked whether SSO is on every plan", tone: "warning" }
+```
+
+- `id` — unique within its list; it comes back to you in the callbacks.
+- `label` — shown in the lane (a region) or the tooltip (both), and read
+  to a screen reader. Keep it short.
+- `tone` — a theme token, never a colour: `primary` (the default),
+  `chart-2` … `chart-5`, `success`, `warning`, `info`, `destructive`,
+  `muted`. `TONES` lists them. Use the `chart-*` tones for kinds (topics,
+  speakers) and the status tones for meaning (a risk, a win).
+- Any other keys ride along untouched (a comment's author, a transcript
+  line's id…) and come back in `onRegionClick`, `onMarkerClick` and
+  `onActiveRegionChange`.
+- Regions may overlap; where they do, the one that started last is the
+  active one. Anything past the end of the audio is clipped to it.
+
+## Props
+
+- `src` — the audio: a URL (`https://…`, `/api/recordings/123`, a
+  `data:` URL) or a `Blob` / `File` (from an upload, a recording). A Blob
+  plays through an object URL the player makes and revokes. Nothing
+  (`null`) shows the empty state.
+- `peaks` — optional precomputed waveform (`[Float32Array | number[]]`,
+  one per channel) with `duration`: the waveform draws at once without
+  decoding the file — use it for long calls. Keep the array's identity
+  stable (state or `useMemo`); a new array rebuilds the player.
+- `duration` — seconds, with `peaks`. Otherwise it is read from the file.
+- `title`, `description` — the heading over the waveform and the muted
+  line under it ("Discovery call · Northwind", "Maya and Leo · Sep 18").
+- `regions` — `[{ id, start, end, label?, tone? }]` (default none).
+- `markers` — `[{ id, time, label?, tone? }]` (default none).
+- `onAddMarker({ time })` — shows the "Marker" button (and the M key); the
+  new pin appears at once, dimmed, while you save. Add the marker to
+  `markers` and return `{ ok: true }`; return `{ ok: false, error }` (or
+  throw) and the pin goes, with a notice that says why. Without it there
+  is no button.
+- `onRegionCreate({ start, end })` — makes a drag across the waveform
+  mark a region (a crosshair cursor, the span and its times shown while
+  dragging; shorter than half a second counts as a click). Same promise
+  as `onAddMarker`: add it to `regions`, return `{ ok }`. Without it a
+  drag scrubs.
+- `onMarkerClick(marker)` — after the jump to it.
+- `onRegionClick(region)` — after it starts playing (it stops at its end).
+- `onActiveRegionChange(region | null)` — once each time the region under
+  the playhead changes (a transcript highlighting the line being said).
+- `onTimeUpdate(seconds)` — continuously while playing (every frame):
+  keep it cheap.
+- `onSeek(seconds)` — every jump: a click, a key, a skip, a pin, the handle.
+- `onReady({ duration })`, `onPlay()`, `onPause()`, `onFinish()`,
+  `onError(error)` — as named.
+- `rates` — the speeds offered, default `[0.75, 1, 1.25, 1.5, 2]`.
+- `defaultRate` — the starting speed, default `1`.
+- `skipSeconds` — the skip buttons' step (and J / L, Page Up / Down),
+  default `15`.
+- `emptyTitle`, `emptyBody`, `emptyAction` — the empty state's words and
+  one action (a node: an upload button). Defaults: "No recording yet",
+  "When there is audio to play, it shows up here.", none.
+- `bare` — no card around it (no border, background or padding), for a
+  player inside your own card or row. Default `false`.
+- `playerRef` — a ref from `useAudioPlayer()` for the handle below.
+- `className` — on the outer element.
+
+### The handle
+
+```jsx
+const player = useAudioPlayer();
+<AudioPlayer src={url} playerRef={player} />;
+player.current?.seek(84);
+```
+
+`play()`, `pause()`, `toggle()`, `seek(seconds)`, `skip(±seconds)`,
+`playRange(start, end?)` (stops at `end`), `playRegion(id)`,
+`setRate(n)`, `setMuted(bool)`, `addMarker()` (as the button),
+`getTime()`, `getDuration()`, `isPlaying()`, `isReady()`. Calls before
+the audio is ready do nothing.
+
+### Keys
+
+On the waveform (a slider, one Tab stop): ← / → 5 seconds, Page Down /
+Page Up `skipSeconds`, Home / End, Space or Enter to play or pause.
+Anywhere in the player (not while typing, not with ⌘ / Ctrl / Alt): K
+play / pause, J / L back / forward `skipSeconds`, M add a marker. Pins
+and region labels are buttons in Tab order.
+
+## Example
+
+A call recording with its topics and comments, saved with
+`lib/actions.js` in a Makersclaw app.
+
+```jsx
+"use client";
+import { useState } from "react";
+import { insertRow } from "../lib/actions";
+import { AudioPlayer } from "./blocks/audio-player";
+
+export default function CallRecording({ call, topics, comments: initial }) {
+  const [comments, setComments] = useState(initial);
+  return (
+    <AudioPlayer
+      src={call.recording_url}
+      title={call.title}
+      description={`${call.participants} · ${call.date}`}
+      regions={topics.map((t) => ({ id: t.id, start: t.start_s, end: t.end_s, label: t.name, tone: "chart-2" }))}
+      markers={comments.map((c) => ({ id: c.id, time: c.at_s, label: c.body, tone: "primary" }))}
+      onAddMarker={async ({ time }) => {
+        const values = { call_id: call.id, at_s: time, body: "New comment" };
+        const res = await insertRow({ source: "public.call_comments", values });
+        if (res.ok) setComments((cs) => [...cs, { ...values, id: res.id }]);
+        return res;
+      }}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Record from the microphone, or play video.
+- Zoom or scroll the waveform: the whole recording always fits the
+  width (a long call reads as an overview; use `peaks` so it draws fast).
+- Move, resize, rename or delete a region, or edit a marker, inside the
+  player: those are your list's actions — change `regions` / `markers`.
+- Show a volume slider (mute only; the device's volume does the rest).
+- Stream: the file is fetched and decoded in the browser (pass `peaks`
+  and `duration` for long files).