makersclaw 0.2.0 → 0.3.0

package/registry/blocks/settings-list/settings-list.jsx

@@ -0,0 +1,349 @@
+"use client";
+
+import { useId, useState } from "react";
+import { Badge, Button, Card, Confirm, Empty, Icon, IconButton, Kicker, Menu, Notice, Select, Skeleton, Switch, cx } from "../../ui";
+import { Failure, Saving, useSaves } from "./row-state";
+import { SettingsMatrix } from "./settings-matrix";
+
+// SettingsList — a card of settings, one row each: an icon, a label, a
+// description, meta lines, a badge, and the row's control (a Switch, a
+// Select, a Button, or a menu of actions). Every change saves on its own
+// through an async callback; the row shows its new value at once, a
+// spinner while it saves, and — when the save fails — the old value back
+// and why, with Try again. `variant="matrix"` is the notification grid:
+// events down the side, channels across the top.
+
+/** A badge from a string or { label, tone, hue, icon }. */
+function RowBadge({ badge }) {
+  if (!badge) return null;
+  const b = typeof badge === "string" ? { label: badge } : badge;
+  return (
+    <Badge tone={b.tone} hue={b.hue} variant={b.variant ?? "soft"}>
+      {b.icon ? <Icon name={b.icon} size={12} className="-ml-0.5 mr-1 inline-block align-[-0.125em]" /> : null}
+      {b.label}
+    </Badge>
+  );
+}
+
+/** The meta lines: strings, or { icon, text } for "globe London". */
+function Meta({ meta }) {
+  const list = (Array.isArray(meta) ? meta : [meta]).filter(Boolean);
+  if (list.length === 0) return null;
+  return (
+    <ul className="mt-1 flex flex-wrap gap-x-4 gap-y-1 text-xs text-muted-foreground">
+      {list.map((m, i) => {
+        const item = typeof m === "object" && !Array.isArray(m) && m !== null && "text" in m ? m : { text: m };
+        return (
+          <li key={i} className="inline-flex min-w-0 items-center gap-1.5">
+            {item.icon ? <Icon name={item.icon} size={14} className="shrink-0" /> : null}
+            <span className="min-w-0 break-words">{item.text}</span>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+function Header({ title, description, icon, badge, actions }) {
+  if (!title && !description && !actions && !badge) return null;
+  return (
+    <div className="flex flex-wrap items-start justify-between gap-3 px-4 pb-3 pt-4">
+      <div className="flex min-w-0 flex-1 items-start gap-3">
+        {icon ? (
+          <span className="grid size-10 shrink-0 place-items-center rounded-md bg-muted text-muted-foreground">
+            <Icon name={icon} size={18} />
+          </span>
+        ) : null}
+        <div className="min-w-0">
+          {title ? <h2 className="text-base font-semibold leading-tight">{title}</h2> : null}
+          {description ? <p className="mt-0.5 text-sm text-muted-foreground">{description}</p> : null}
+        </div>
+      </div>
+      {badge || actions ? (
+        <div className="flex shrink-0 flex-wrap items-center gap-2">
+          <RowBadge badge={badge} />
+          {actions}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** Rows under their `group` headings, in the order groups first appear. */
+export function grouped(rows) {
+  const out = [];
+  for (const r of rows) {
+    const g = r.group ?? null;
+    let bucket = out.find((b) => b.group === g);
+    if (!bucket) out.push((bucket = { group: g, rows: [] }));
+    bucket.rows.push(r);
+  }
+  return out;
+}
+
+export function GroupHeading({ children }) {
+  return (
+    <li className="border-t border-border bg-muted/50 px-4 py-2" role="presentation">
+      <Kicker>{children}</Kicker>
+    </li>
+  );
+}
+
+function Row({ row, saves, onChange, onAction, ask, disabled }) {
+  const id = useId();
+  const [open, setOpen] = useState(row.defaultOpen ?? false);
+  const c = row.control ?? null;
+  const key = row.key;
+  const busy = saves.isBusy(key);
+  const failure = saves.failure(key);
+  const off = disabled || row.disabled;
+  const detailsId = `${id}-details`;
+  const details = typeof row.details === "function" ? row.details(row) : row.details;
+  const inline = c?.type === "switch";
+  const switchId = `${id}-switch`;
+  const noAction = !onAction;
+
+  function change(value) {
+    if (!onChange) return;
+    saves.run(key, () => onChange(row, value), { value, stored: c.value });
+  }
+
+  function act(action) {
+    const go = () => saves.run(key, () => onAction(row, action.key ?? action.label), { fallback: `${action.label} did not go through.` });
+    if (action.confirm) ask({ ...action.confirm, run: go, tone: action.confirm.tone ?? (action.tone === "danger" ? "danger" : undefined) });
+    else go();
+  }
+
+  let control = null;
+  if (c?.type === "switch") {
+    const on = saves.valueOf(key, c.value) === true;
+    control = (
+      <Switch id={switchId} checked={on} disabled={off || busy || !onChange} onChange={(e) => change(e.target.checked)} />
+    );
+  } else if (c?.type === "select") {
+    control = (
+      <Select
+        aria-label={row.label}
+        value={saves.valueOf(key, c.value) ?? ""}
+        options={c.options}
+        disabled={off || busy || !onChange}
+        onChange={(e) => change(e.target.value)}
+        className="sm:w-48"
+      />
+    );
+  } else if (c?.type === "button") {
+    const action = { key: c.key ?? "button", label: c.label, tone: c.tone, confirm: c.confirm };
+    control = (
+      <Button
+        size="sm"
+        icon={c.icon}
+        variant={c.variant ?? (c.tone === "danger" ? "danger" : "secondary")}
+        loading={busy}
+        disabled={off || noAction}
+        onClick={() => act(action)}
+      >
+        {c.label}
+      </Button>
+    );
+  } else if (c?.type === "actions") {
+    const items = (c.items ?? []).filter(Boolean);
+    control = (
+      <div className="flex items-center gap-1">
+        {busy ? <Saving label="Working" /> : null}
+        {c.menu || items.length > 2 ? (
+          <Menu
+            label={`${row.label}, actions`}
+            items={items.map((a) => ({ label: a.label, icon: a.icon, tone: a.tone, disabled: off || busy || noAction, onSelect: () => act(a) }))}
+          />
+        ) : (
+          items.map((a) => (
+            <Button key={a.key ?? a.label} size="sm" variant={a.tone === "danger" ? "danger" : "quiet"} icon={a.icon} disabled={off || busy || noAction} onClick={() => act(a)}>
+              {a.label}
+            </Button>
+          ))
+        )}
+      </div>
+    );
+  } else if (c?.type === "remove") {
+    control = (
+      <IconButton
+        icon="x"
+        label={c.label ?? `Remove ${row.label}`}
+        variant="secondary"
+        size="sm"
+        disabled={off || busy || noAction}
+        onClick={() => act({ key: "remove", label: c.label ?? "Remove", tone: "danger", confirm: c.confirm })}
+      />
+    );
+  }
+
+  return (
+    <li className="border-t border-border px-4 py-4">
+      <div className={cx("flex items-start gap-3", !inline && "flex-wrap")}>
+        {row.media ? (
+          <span className="shrink-0">{row.media}</span>
+        ) : row.icon ? (
+          <span className="grid size-10 shrink-0 place-items-center rounded-md bg-muted text-muted-foreground">
+            <Icon name={row.icon} size={18} />
+          </span>
+        ) : null}
+        <div className={cx("min-w-0 flex-1", !inline && "basis-52")}>
+          <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+            {inline ? (
+              <label htmlFor={switchId} className="font-medium leading-tight text-foreground">
+                {row.label}
+              </label>
+            ) : (
+              <p className="font-medium leading-tight text-foreground">{row.label}</p>
+            )}
+            <RowBadge badge={row.badge} />
+          </div>
+          {row.description ? <p className="mt-1 text-sm text-muted-foreground">{row.description}</p> : null}
+          {row.value ? (
+            <p className={cx("mt-1 inline-flex items-center gap-1.5 text-sm", row.valueTone === "set" ? "font-medium text-foreground" : "text-muted-foreground")}>
+              {row.valueTone === "set" ? <Icon name="circle-check" size={14} className="shrink-0 text-success" /> : null}
+              {row.value}
+            </p>
+          ) : null}
+          <Meta meta={row.meta} />
+        </div>
+        {control || details ? (
+          <div className={cx("flex shrink-0 items-center gap-2", !inline && (row.icon || row.media) && "max-sm:ml-13")}>
+            {busy && c?.type !== "button" && c?.type !== "actions" ? <Saving /> : null}
+            {control}
+            {details ? (
+              <IconButton
+                icon={open ? "chevron-up" : "chevron-down"}
+                label={`${open ? "Hide" : "Show"} details for ${row.label}`}
+                size="sm"
+                aria-expanded={open}
+                aria-controls={detailsId}
+                onClick={() => setOpen((v) => !v)}
+              />
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+      <Failure failure={failure} className="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-destructive" />
+      {details ? (
+        <div id={detailsId} hidden={!open} className="mt-3 rounded-md border border-border bg-muted/40 p-3 text-sm">
+          {details}
+        </div>
+      ) : null}
+    </li>
+  );
+}
+
+export function SettingsList({
+  rows = [],
+  variant = "list",
+  channels = [],
+  onChange,
+  onAction,
+  title,
+  description,
+  icon,
+  badge,
+  actions,
+  footer,
+  loading = false,
+  error,
+  onRetry,
+  emptyTitle = "Nothing here yet",
+  emptyBody,
+  emptyAction,
+  disabled = false,
+  failedText = "Not saved. The old value is back.",
+  className,
+}) {
+  const saves = useSaves(failedText);
+  const [asking, setAsking] = useState(null);
+  const [confirming, setConfirming] = useState(false);
+
+  async function confirmNow() {
+    if (!asking) return;
+    setConfirming(true);
+    await asking.run();
+    setConfirming(false);
+    setAsking(null);
+  }
+
+  let body;
+  if (error) {
+    body = (
+      <div className="border-t border-border p-4">
+        <Notice tone="danger" title="These settings could not be loaded" action={onRetry ? <Button size="sm" onClick={onRetry}>Try again</Button> : null}>
+          {error}
+        </Notice>
+      </div>
+    );
+  } else if (loading) {
+    body = (
+      <ul aria-busy="true" aria-label="Loading">
+        {[0, 1, 2].map((i) => (
+          <li key={i} className="flex items-center gap-3 border-t border-border px-4 py-4">
+            <Skeleton shape="rect" className="size-10 shrink-0" />
+            <div className="grid min-w-0 flex-1 gap-2">
+              <Skeleton className="w-1/3" />
+              <Skeleton className="w-2/3" />
+            </div>
+            <Skeleton shape="rect" className="h-6 w-10 shrink-0 rounded-full" />
+          </li>
+        ))}
+      </ul>
+    );
+  } else if (rows.length === 0) {
+    body = (
+      <div className="border-t border-border p-4">
+        <Empty icon={icon ?? "settings"} title={emptyTitle} body={emptyBody} action={emptyAction} />
+      </div>
+    );
+  } else if (variant === "matrix") {
+    body = <SettingsMatrix rows={rows} channels={channels} onChange={onChange} saves={saves} disabled={disabled} />;
+  } else {
+    body = (
+      <ul>
+        {grouped(rows).map((b) => (
+          <GroupRows key={b.group ?? "_"} bucket={b}>
+            {b.rows.map((row) => (
+              <Row key={row.key} row={row} saves={saves} onChange={onChange} onAction={onAction} ask={setAsking} disabled={disabled} />
+            ))}
+          </GroupRows>
+        ))}
+      </ul>
+    );
+  }
+
+  const headed = Boolean(title || description || actions || badge);
+  return (
+    <Card padding="none" className={cx(!headed && "[&>ul>li:first-child]:border-t-0", className)}>
+      <Header title={title} description={description} icon={icon} badge={badge} actions={actions} />
+      {body}
+      {footer ? <div className="border-t border-border p-4">{footer}</div> : null}
+      <Confirm
+        open={Boolean(asking)}
+        onClose={() => {
+          if (!confirming) setAsking(null);
+        }}
+        onConfirm={confirmNow}
+        busy={confirming}
+        tone={asking?.tone ?? "neutral"}
+        title={asking?.title ?? "Are you sure?"}
+        body={asking?.body}
+        confirmLabel={asking?.confirmLabel ?? "Confirm"}
+        consequences={asking?.consequences}
+        requireText={asking?.requireText}
+        acknowledge={asking?.acknowledge}
+      />
+    </Card>
+  );
+}
+
+function GroupRows({ bucket, children }) {
+  return (
+    <>
+      {bucket.group ? <GroupHeading>{bucket.group}</GroupHeading> : null}
+      {children}
+    </>
+  );
+}

package/registry/blocks/settings-list/settings-matrix.jsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { useId } from "react";
+import { Icon, Kicker, Switch, cx } from "../../ui";
+import { Failure, Saving } from "./row-state";
+
+// The notification grid of a SettingsList (variant="matrix"): events down
+// the side, grouped; channels (email, push, SMS…) across the top; a Switch
+// in every cell that saves on its own. From 768px it is a grid with the
+// channels as column heads. On a phone each event's switches stack under
+// it, each one named by its channel, so nothing scrolls sideways.
+
+function groupsOf(rows) {
+  const out = [];
+  for (const r of rows) {
+    const g = r.group ?? null;
+    let b = out.find((x) => x.group === g);
+    if (!b) out.push((b = { group: g, rows: [] }));
+    b.rows.push(r);
+  }
+  return out;
+}
+
+// The grid's columns: the event, then one fixed column per channel. The
+// count comes in as a custom property so one class serves any number.
+const GRID = "md:grid md:items-center md:gap-x-2 md:[grid-template-columns:minmax(0,1fr)_repeat(var(--channels),5.5rem)]";
+
+function Cell({ row, channel, saves, onChange, disabled }) {
+  const id = useId();
+  const key = `${row.key}:${channel.key}`;
+  const stored = row.values?.[channel.key];
+  if (stored === undefined || stored === null) {
+    // This event cannot be sent on this channel.
+    return (
+      <div className="flex min-h-11 items-center gap-2 text-sm text-muted-foreground md:justify-center">
+        <span className="md:sr-only">{channel.label}</span>
+        <span aria-hidden="true">—</span>
+        <span className="sr-only">not offered</span>
+      </div>
+    );
+  }
+  const locked = (row.locked ?? []).includes(channel.key);
+  const busy = saves.isBusy(key);
+  const on = saves.valueOf(key, stored) === true;
+  return (
+    <div className="flex min-h-11 items-center gap-2 md:justify-center">
+      <Switch
+        id={id}
+        checked={on}
+        disabled={disabled || locked || busy || !onChange}
+        onChange={(e) => {
+          const value = e.target.checked;
+          saves.run(key, () => onChange(row, value, channel.key), { value, stored });
+        }}
+        label={
+          <span className="md:sr-only">
+            {channel.label}
+            {locked ? <span className="sr-only"> (always on)</span> : null}
+          </span>
+        }
+      />
+      {locked ? <Icon name="lock" size={12} className="shrink-0 text-muted-foreground" /> : null}
+      {busy ? <Saving /> : null}
+    </div>
+  );
+}
+
+export function SettingsMatrix({ rows, channels, onChange, saves, disabled }) {
+  const base = useId();
+  return (
+    <div style={{ "--channels": channels.length }}>
+      <div className={cx("hidden border-t border-border px-4 py-2", GRID)} aria-hidden="true">
+        <Kicker>Event</Kicker>
+        {channels.map((c) => (
+          <span key={c.key} className="inline-flex items-center justify-center gap-1.5 text-xs font-medium text-muted-foreground">
+            {c.icon ? <Icon name={c.icon} size={14} /> : null}
+            {c.label}
+          </span>
+        ))}
+      </div>
+      {groupsOf(rows).map((g) => (
+        <section key={g.group ?? "_"} aria-label={g.group ?? undefined}>
+          {g.group ? (
+            <div className="border-t border-border bg-muted/50 px-4 py-2">
+              <Kicker>{g.group}</Kicker>
+            </div>
+          ) : null}
+          <ul>
+            {g.rows.map((row) => {
+              const labelId = `${base}-${row.key}`;
+              const failures = channels.map((c) => ({ c, f: saves.failure(`${row.key}:${c.key}`) })).filter((x) => x.f);
+              return (
+                <li key={row.key} role="group" aria-labelledby={labelId} className="border-t border-border px-4 py-3">
+                  <div className={GRID}>
+                    <div className="min-w-0 pb-1 md:pb-0">
+                      <p id={labelId} className="text-sm font-medium text-foreground">
+                        {row.label}
+                      </p>
+                      {row.description ? <p className="text-sm text-muted-foreground">{row.description}</p> : null}
+                    </div>
+                    <div className="flex flex-wrap gap-x-5 md:contents">
+                      {channels.map((c) => (
+                        <Cell key={c.key} row={row} channel={c} saves={saves} onChange={onChange} disabled={disabled} />
+                      ))}
+                    </div>
+                  </div>
+                  {failures.map(({ c, f }) => (
+                    <Failure key={c.key} failure={{ ...f, error: `${c.label}: ${f.error}` }} className="mt-1 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-destructive" />
+                  ))}
+                </li>
+              );
+            })}
+          </ul>
+        </section>
+      ))}
+    </div>
+  );
+}

package/registry/blocks/setup-checklist/README.md

@@ -0,0 +1,142 @@
+# SetupChecklist
+
+The steps to get set up, which of them are done, how far along the whole
+is, and the button for the next one. The steps are yours: their `done`
+comes from the app's data (the profile has a name, a teammate was
+invited), so the list is never a second record of the truth. A step's
+button goes out through `onAction`; while it runs the button spins, and
+when it fails the step says why.
+
+```jsx
+import { SetupChecklist } from "../components/blocks/setup-checklist";   // a Makersclaw app ("./blocks/setup-checklist" from components/)
+import { SetupChecklist } from "@/components/makersclaw/blocks/setup-checklist";   // a shadcn project
+```
+
+A client component. Work out `done` for each step in the server surface
+(README §4) and pass the steps in.
+
+## The data
+
+`steps` — in order:
+`[{ key, title, description?, actionLabel?, href?, icon?, summary?, done }]`.
+
+- `key` — unique, stable.
+- `actionLabel` — the step's button ("Send invites"); default "Start"
+  ("Open" once done).
+- `href` — the button is a link to the page where the step is done;
+  `onAction` still hears about the click.
+- `icon` — a kit `Icon` name: on the right of a card and in its button
+  (`cards`), above the text (`accordion`).
+- `summary` — `accordion`: the bold line in the step's panel.
+
+The next step is the first one not done.
+
+## Props
+
+- `steps` — as above. Required.
+- `variant` — default `"collapsible"`:
+  - `collapsible` — a card: the title, a ring with "2 of 6 done", a "⋯"
+    menu (Dismiss and `menuItems`), then each step a folding row with its
+    description and button. The next step starts open, and when the open
+    step gets done the next one opens.
+  - `cards` — the title, "1 of 4 done" and a bar, then a numbered card
+    per step. Only the next step shows its button.
+  - `list` — the title, "Step 2 of 4" and a short bar, then a row per
+    step, numbered "1.", "2."; the next one is outlined and shows its
+    button. `footer` sits in a filled panel below ("Need a hand?").
+  - `accordion` — each step a bordered folding row; its panel is centred:
+    icon, `summary`, description, button. Pair it with `sequential`.
+- `onAction(step)` — the step's button (or a click on its link). Do the
+  thing, or open your `Sheet` for it; return `{ ok: true }` or
+  `{ ok: false, error }` (a throw counts as failed) and the step shows the
+  error under its button. Mark it done by passing the step back with
+  `done: true`; the block never marks a step itself. Without `onAction`
+  only steps with an `href` have a button.
+- `sequential` — a step's button stays disabled, with "Finish the steps
+  before this one first", until every step before it is done. Default
+  `false`: any step can be done in any order.
+- `title` — default "Get set up". `description` — a line under it.
+- `onDismiss()` — adds Dismiss to the "⋯" menu (`collapsible` shows the
+  menu in its header, the others beside the title). Hide the checklist
+  and remember that you did; return `{ ok: false, error }` to show why it
+  could not.
+- `menuItems` — more "⋯" items, kit `Menu` shape: `[{ label, onSelect,
+  icon? }]` ("Send feedback").
+- `footer` — a node under the steps: help, a link to the docs.
+- `doneLabel` — what the header says when every step is done, default
+  "All set" (the bar turns to the success tone).
+- `loading` — skeleton rows while the steps load.
+- `error` — a string: the steps did not load. Shown in a notice with
+  Retry when `onRetry` is given.
+- `className` — layout around it (width, margin). Never colour.
+
+With no steps it says "Nothing to set up".
+
+## Example
+
+```jsx
+// surfaces/home.jsx — server: work out what is done
+import { loadRows } from "../lib/data";
+import GettingStarted from "../components/GettingStarted";
+
+export default async function Home() {
+  const [{ rows: members }, { rows: deals }] = await Promise.all([
+    loadRows({ source: "public.members" }),
+    loadRows({ source: "public.deals", limit: 1 }),
+  ]);
+  return <GettingStarted invited={members.length > 1} hasDeal={deals.length > 0} />;
+}
+```
+
+```jsx
+// components/GettingStarted.jsx — client
+"use client";
+import { SetupChecklist } from "./blocks/setup-checklist";
+
+export default function GettingStarted({ invited, hasDeal, onHide }) {
+  return (
+    <SetupChecklist
+      title="Get started"
+      steps={[
+        { key: "invite", title: "Invite your team", description: "Bring in the people who own accounts.", actionLabel: "Invite", href: "/team", done: invited },
+        { key: "deal", title: "Add your first deal", description: "One deal is enough to see the pipeline work.", actionLabel: "Add a deal", href: "/deals?new=1", done: hasDeal },
+      ]}
+      onDismiss={onHide}
+    />
+  );
+}
+```
+
+In order, with buttons that do the work in place:
+
+```jsx
+<SetupChecklist
+  variant="accordion"
+  sequential
+  title="Quick start"
+  steps={steps}
+  onAction={async (step) => {
+    const res = await runSetupStep(step.key); // your server action, { ok, error }
+    if (res.ok) router.refresh(); // the step comes back done
+    return res;
+  }}
+/>
+```
+
+## What it will not do
+
+- Decide a step is done: `done` is yours, from your data.
+- Remember that it was dismissed: `onDismiss` is where you save that.
+- Nest steps inside steps, or show a running job's stages: that is the kit
+  `Steps` or the `job-panel` block.
+- Page through a wizard of forms: each step's button goes where the work
+  is.
+
+A checklist 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 setup-checklist` restores
+them.
+
+## Credits
+
+Ported from blocks.so (https://blocks.so, onboarding 01–04, MIT), rewritten on the Makersclaw kit.

package/registry/blocks/setup-checklist/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "setup-checklist",
+  "title": "SetupChecklist",
+  "description": "The steps to get set up: which are done, how far along the whole is (a ring, a bar, or \"Step 2 of 4\"), and the button for the next one, sent out through an async onAction that can fail on the step. Four shapes: folding rows in a card with a dismiss menu, numbered step cards, a plain step list with a help panel, and bordered accordion rows that can be locked until the step before is done.",
+  "useWhen": "A new account, workspace or shop has a few things to do before it is useful (complete the profile, invite the team, connect a tool, launch) and the founder should see what is left. Not for a running job's stages (kit Steps or job-panel), and not for a multi-page form wizard.",
+  "tags": ["onboarding", "checklist", "setup", "getting started", "steps", "progress", "tasks", "welcome", "quick start", "wizard", "dismiss"],
+  "exports": ["SetupChecklist"],
+  "files": ["index.js", "setup-checklist.jsx"],
+  "requires": []
+}