makersclaw 0.2.0 → 0.3.0

package/registry/blocks/setup-checklist/demo.jsx

@@ -0,0 +1,159 @@
+"use client";
+
+// SetupChecklist with its steps in memory — the gallery's and the smoke
+// test's surface. Not installed into apps: `makersclaw add
+// setup-checklist` lays index.js and setup-checklist.jsx only.
+import { useState } from "react";
+import { Button, Empty, Field, Select, Switch, ToggleGroup, toast } from "../components/ui";
+import { SetupChecklist } from "../components/blocks/setup-checklist";
+
+const VARIANTS = [
+  { value: "collapsible", label: "Collapsible — folding rows" },
+  { value: "cards", label: "Cards — numbered steps" },
+  { value: "list", label: "List — step n of N" },
+  { value: "accordion", label: "Accordion — locked in order" },
+];
+
+const SETS = {
+  collapsible: {
+    title: "Get started with Northwind CRM",
+    steps: [
+      { key: "profile", title: "Complete your profile", description: "Your name, photo and role, so teammates know who they are talking to.", actionLabel: "Edit profile", done: true },
+      { key: "workspace", title: "Name your workspace", description: "Pick a name and an icon, and the currency your deals are in.", actionLabel: "Open settings" },
+      { key: "invite", title: "Invite your team", description: "Sales works better together: bring in the people who own accounts.", actionLabel: "Send invites" },
+      { key: "email", title: "Connect your inbox", description: "Emails with a contact land on their record without copying anything.", actionLabel: "Connect inbox" },
+      { key: "pipeline", title: "Build your first pipeline", description: "The stages a deal moves through, from first call to signed.", actionLabel: "Create pipeline" },
+      { key: "alerts", title: "Choose your alerts", description: "Hear about replies and stalled deals where you already work.", actionLabel: "Pick alerts" },
+    ],
+  },
+  cards: {
+    title: "Set up your team space",
+    description: "Four steps and your team can start planning here.",
+    steps: [
+      { key: "space", title: "Create the space", description: "A name and an address for everything your team shares.", icon: "sparkles", actionLabel: "Create it", done: true },
+      { key: "invite", title: "Invite your team", description: "Add teammates by email; they get a link to join.", icon: "users", actionLabel: "Send invites" },
+      { key: "project", title: "Start a project", description: "Tasks, notes and dates for one piece of work, in one place.", icon: "folder", actionLabel: "New project" },
+      { key: "tools", title: "Connect your tools", description: "Bring in your calendar and chat so updates find you.", icon: "zap", actionLabel: "Browse tools" },
+    ],
+  },
+  list: {
+    title: "Open your shop",
+    description: "Each step brings the shop closer to its first order.",
+    steps: [
+      { key: "name", title: "Name your shop", description: "The name buyers see, your address on the web, and your currency.", actionLabel: "Name it", done: true },
+      { key: "products", title: "Add your products", description: "Photos, prices and how many you have of each.", actionLabel: "Add a product" },
+      { key: "payments", title: "Turn on payments", description: "Checkout through Paddle, so cards and taxes are handled for you.", actionLabel: "Connect Paddle" },
+      { key: "launch", title: "Go live", description: "Look it over once more, then open the doors.", actionLabel: "Launch the shop" },
+    ],
+  },
+  accordion: {
+    title: "Quick start",
+    description: "Your backend in four steps, in order.",
+    steps: [
+      { key: "env", title: "Set up the environment", summary: "Environment ready", description: "Keys and defaults for development and production.", icon: "settings", actionLabel: "Edit settings", done: true },
+      { key: "db", title: "Connect a database", summary: "Add a connection", description: "Point it at your Postgres; the tables are read, never changed.", icon: "database", actionLabel: "Add database" },
+      { key: "schema", title: "Describe your data", summary: "Draw the schema", description: "Types, links between them, and the rules each field follows.", icon: "layers", actionLabel: "Open the editor" },
+      { key: "api", title: "Publish the API", summary: "Make endpoints", description: "Read and write endpoints from the schema, with keys for each app.", icon: "code", actionLabel: "Generate the API" },
+    ],
+  },
+};
+
+export default function SetupChecklistDemo() {
+  const [variant, setVariant] = useState("collapsible");
+  const [state, setState] = useState("steps");
+  const [failNext, setFailNext] = useState(false);
+  const [dismissed, setDismissed] = useState(false);
+  const [done, setDone] = useState(() =>
+    Object.fromEntries(Object.entries(SETS).map(([k, set]) => [k, set.steps.filter((s) => s.done).map((s) => s.key)])),
+  );
+
+  const set = SETS[variant];
+  const steps = set.steps.map((s) => ({ ...s, done: done[variant].includes(s.key) }));
+
+  async function onAction(step) {
+    await new Promise((r) => setTimeout(r, 700));
+    if (failNext) {
+      setFailNext(false);
+      return { ok: false, error: `"${step.title}" could not be saved. Check your connection and try again.` };
+    }
+    setDone((d) => ({ ...d, [variant]: d[variant].includes(step.key) ? d[variant] : [...d[variant], step.key] }));
+    return { ok: true };
+  }
+
+  function reset() {
+    setDone((d) => ({ ...d, [variant]: SETS[variant].steps.filter((s) => s.done).map((s) => s.key) }));
+    setDismissed(false);
+  }
+
+  let body;
+  if (dismissed) {
+    body = <Empty icon="archive" title="Checklist hidden" body="It stays out of the way until you bring it back." action={<Button onClick={() => setDismissed(false)}>Show it again</Button>} />;
+  } else {
+    body = (
+      <SetupChecklist
+        key={variant}
+        variant={variant}
+        title={set.title}
+        description={set.description}
+        steps={state === "empty" ? [] : steps}
+        loading={state === "loading"}
+        error={state === "error" ? "We could not reach the server. Your progress is safe." : undefined}
+        onRetry={() => setState("steps")}
+        onAction={onAction}
+        sequential={variant === "accordion"}
+        onDismiss={
+          variant === "collapsible"
+            ? async () => {
+                setDismissed(true);
+                return { ok: true };
+              }
+            : undefined
+        }
+        menuItems={variant === "collapsible" ? [{ label: "Send feedback", icon: "mail", onSelect: () => toast("Thanks — feedback opens here.") }] : undefined}
+        footer={
+          variant === "list" ? (
+            <>
+              <p className="font-medium text-foreground">Need a hand?</p>
+              <p className="mt-1 text-muted-foreground">
+                Write to{" "}
+                <Button variant="link" size="inherit" href="mailto:help@example.com">
+                  help@example.com
+                </Button>{" "}
+                and a person answers within a day.
+              </p>
+            </>
+          ) : undefined
+        }
+      />
+    );
+  }
+
+  return (
+    <div className="grid gap-4">
+      <div className="flex flex-wrap items-end gap-x-4 gap-y-2">
+        <Field id="sc-variant" label="Variant" className="w-full sm:w-64">
+          <Select id="sc-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: "steps", label: "Steps" },
+            { value: "loading", label: "Loading" },
+            { value: "error", label: "Error" },
+            { value: "empty", label: "Empty" },
+          ]}
+        />
+      </div>
+      <div className="flex flex-wrap items-center gap-x-4">
+        <Switch id="sc-fail" checked={failNext} onChange={(e) => setFailNext(e.target.checked)} label="Fail the next step" />
+        <Button variant="quiet" size="sm" icon="refresh" onClick={reset}>
+          Start over
+        </Button>
+      </div>
+      <div className="mx-auto w-full max-w-lg">{body}</div>
+    </div>
+  );
+}

package/registry/blocks/setup-checklist/index.js

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

package/registry/blocks/setup-checklist/setup-checklist.jsx

@@ -0,0 +1,446 @@
+"use client";
+
+import { useEffect, useId, useRef, useState } from "react";
+import { Accordion, Button, Card, Collapsible, Empty, Icon, Menu, Meter, Notice, Progress, Skeleton, cx } from "../../ui";
+
+// SetupChecklist — the steps to get set up: which are done, how far along
+// the whole is, and the button for the next one. The steps are the app's
+// (their `done` comes from its data); the block draws them and sends each
+// step's button out through `onAction`, showing a failure on the step.
+
+/* ------------------------------------------------------------------------
+   Pieces
+   ------------------------------------------------------------------------ */
+
+function Marker({ state, index, shape }) {
+  if (state === "done") {
+    return <Icon name="circle-check" size={shape === "number" ? 24 : 20} className="shrink-0 text-success" />;
+  }
+  if (shape === "number") {
+    return (
+      <span
+        aria-hidden="true"
+        data-nums
+        className={cx(
+          "flex size-6 shrink-0 items-center justify-center rounded-full text-xs font-semibold",
+          state === "current" ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground",
+        )}
+      >
+        {index + 1}
+      </span>
+    );
+  }
+  if (shape === "ring") {
+    return <span aria-hidden="true" className="size-5 shrink-0 rounded-full border border-border" />;
+  }
+  return <Icon name="circle-dashed" size={20} className="shrink-0 text-muted-foreground" />;
+}
+
+// What a reader hears after the title.
+const SAID = { done: "done", current: "next", pending: "not started", locked: "not started" };
+
+function StepTitle({ step, state }) {
+  return (
+    <span className={cx(state === "done" ? "text-muted-foreground line-through" : state === "locked" ? "text-muted-foreground" : "text-foreground")}>
+      {step.title}
+      <span className="sr-only">, {SAID[state]}</span>
+    </span>
+  );
+}
+
+function StepError({ message }) {
+  if (!message) return null;
+  return (
+    <p role="alert" className="mt-2 text-sm text-destructive">
+      {message}
+    </p>
+  );
+}
+
+/* ------------------------------------------------------------------------
+   SetupChecklist
+   ------------------------------------------------------------------------ */
+
+export function SetupChecklist({
+  steps,
+  variant = "collapsible",
+  title = "Get set up",
+  description,
+  onAction,
+  onDismiss,
+  menuItems,
+  footer,
+  sequential = false,
+  doneLabel = "All set",
+  loading = false,
+  error,
+  onRetry,
+  className,
+}) {
+  const list = (steps ?? []).filter(Boolean);
+  const total = list.length;
+  const doneCount = list.filter((s) => s.done).length;
+  const current = list.findIndex((s) => !s.done);
+  const allDone = total > 0 && current < 0;
+
+  const uid = useId();
+  const [busy, setBusy] = useState(null);
+  const [errors, setErrors] = useState({});
+  const [dismissError, setDismissError] = useState(null);
+  const [open, setOpen] = useState(() => list[current]?.key ?? null);
+
+  // When the open step gets done, the next one opens.
+  const doneSig = list.map((s) => (s.done ? 1 : 0)).join("");
+  const lastSig = useRef(doneSig);
+  useEffect(() => {
+    if (lastSig.current === doneSig) return;
+    lastSig.current = doneSig;
+    const openStep = list.find((s) => s.key === open);
+    if (!openStep || openStep.done) setOpen(list[current]?.key ?? null);
+    // The steps' done flags are what moved.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [doneSig]);
+
+  const stateOf = (i) => (list[i].done ? "done" : i === current ? "current" : sequential ? "locked" : "pending");
+
+  async function run(step) {
+    if (!onAction) return;
+    setBusy(step.key);
+    setErrors((e) => ({ ...e, [step.key]: null }));
+    let res;
+    try {
+      res = await onAction(step);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    setBusy(null);
+    if (res && res.ok === false) setErrors((e) => ({ ...e, [step.key]: res.error || "That did not work. Try again." }));
+  }
+
+  async function dismiss() {
+    setDismissError(null);
+    let res;
+    try {
+      res = await onDismiss();
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    if (res && res.ok === false) setDismissError(res.error || "The checklist could not be hidden.");
+  }
+
+  // A render helper, not a component: a component declared in here would
+  // remount on every render and drop the focus from its button.
+  function action(step, i, look) {
+    const state = stateOf(i);
+    const label = step.actionLabel ?? (state === "done" ? "Open" : "Start");
+    const variant = state === "done" || look === "secondary" ? "secondary" : "primary";
+    const disabled = state === "locked";
+    if (!step.href && !onAction) return null;
+    return (
+      <Button
+        size="sm"
+        variant={variant}
+        icon={look === "icon" ? step.icon : undefined}
+        href={disabled ? undefined : step.href}
+        onClick={step.href ? () => onAction?.(step) : () => run(step)}
+        loading={busy === step.key}
+        disabled={disabled || (busy !== null && busy !== step.key)}
+        aria-describedby={disabled ? `${uid}-${step.key}-locked` : undefined}
+      >
+        {label}
+      </Button>
+    );
+  }
+
+  const menu = [onDismiss && { label: "Dismiss", icon: "archive", onSelect: dismiss }, ...(menuItems ?? [])].filter(Boolean);
+
+  /* ---- states that replace the steps -------------------------------- */
+
+  if (loading) {
+    return (
+      <div aria-busy="true" aria-label={title} className={cx("grid gap-3 rounded-lg border border-border bg-card p-4", className)}>
+        <Skeleton className="w-1/2" />
+        <Skeleton className="h-1.5 w-full" shape="rect" />
+        {[0, 1, 2, 3].map((i) => (
+          <div key={i} className="flex items-center gap-3 py-2">
+            <Skeleton shape="circle" className="size-5" />
+            <Skeleton className="w-2/3" />
+          </div>
+        ))}
+      </div>
+    );
+  }
+  if (error) {
+    return (
+      <Notice
+        tone="danger"
+        title="The checklist did not load"
+        className={className}
+        action={
+          onRetry ? (
+            <Button size="sm" icon="refresh" onClick={onRetry}>
+              Retry
+            </Button>
+          ) : null
+        }
+      >
+        {error}
+      </Notice>
+    );
+  }
+  if (total === 0) {
+    return <Empty icon="circle-check" title="Nothing to set up" body="Every step is taken care of." className={className} />;
+  }
+
+  const bar = (
+    <Progress
+      value={doneCount}
+      max={total}
+      tone={allDone ? "success" : "neutral"}
+      aria-label={`${title}: ${doneCount} of ${total} steps done`}
+      valueText={`${doneCount} of ${total}`}
+    />
+  );
+  const menuButton = menu.length ? <Menu items={menu} label={`${title} options`} /> : null;
+  const dismissNotice = dismissError ? (
+    <Notice tone="danger" onDismiss={() => setDismissError(null)}>
+      {dismissError}
+    </Notice>
+  ) : null;
+  const lockedNote = (step) =>
+    stateOf(list.indexOf(step)) === "locked" ? (
+      <p id={`${uid}-${step.key}-locked`} className="mt-2 text-xs text-muted-foreground">
+        Finish the steps before this one first.
+      </p>
+    ) : null;
+
+  /* ---- collapsible: a card of folding rows, a ring in the header ----- */
+
+  if (variant === "collapsible") {
+    return (
+      <Card className={cx("grid gap-2", className)}>
+        <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
+          <div className="min-w-0">
+            <h2 className="font-semibold leading-tight">{title}</h2>
+            {description ? <p className="mt-0.5 text-sm text-muted-foreground">{description}</p> : null}
+          </div>
+          <div className="ml-auto flex items-center gap-1">
+            <Meter
+              shape="ring"
+              size="sm"
+              value={doneCount}
+              max={total}
+              tone={allDone ? "success" : "neutral"}
+              center={null}
+              valueText={null}
+              aria-label={`${doneCount} of ${total} steps done`}
+            />
+            <span data-nums className="ml-1.5 mr-1 text-sm text-muted-foreground">
+              {allDone ? (
+                doneLabel
+              ) : (
+                <>
+                  <span className="font-medium text-foreground">{doneCount}</span> of <span className="font-medium text-foreground">{total}</span> done
+                </>
+              )}
+            </span>
+            {menuButton}
+          </div>
+        </div>
+        {dismissNotice}
+        <Accordion
+          aria-label={title}
+          chevron="right"
+          value={open}
+          onChange={setOpen}
+          items={list.map((step, i) => {
+            const state = stateOf(i);
+            return {
+              key: step.key,
+              title: (
+                <span className="flex items-center gap-3">
+                  <Marker state={state} />
+                  <StepTitle step={step} state={state} />
+                </span>
+              ),
+              content: (
+                <div className="pl-8">
+                  {step.description ? <p className="max-w-prose text-muted-foreground">{step.description}</p> : null}
+                  <div className="mt-3">
+                    {action(step, i)}
+                  </div>
+                  {lockedNote(step)}
+                  <StepError message={errors[step.key]} />
+                </div>
+              ),
+            };
+          })}
+        />
+        {footer ? <div className="border-t border-border pt-3 text-sm">{footer}</div> : null}
+      </Card>
+    );
+  }
+
+  const header = (right) => (
+    <div className="grid gap-3">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <h2 className="text-lg font-semibold leading-tight">{title}</h2>
+          {description ? <p className="mt-1 text-sm text-muted-foreground">{description}</p> : null}
+        </div>
+        {menuButton}
+      </div>
+      {right}
+      {dismissNotice}
+    </div>
+  );
+
+  /* ---- accordion: bordered folding rows, a panel in each ------------- */
+
+  if (variant === "accordion") {
+    return (
+      <div className={cx("grid gap-4", className)}>
+        {header(null)}
+        <div className="grid gap-2" role="list" aria-label={title}>
+          {list.map((step, i) => {
+            const state = stateOf(i);
+            return (
+              <div role="listitem" key={step.key}>
+                <Collapsible
+                  variant="outline"
+                  open={open === step.key}
+                  onOpenChange={(next) => setOpen(next ? step.key : null)}
+                  title={
+                    <span className="flex items-center gap-3">
+                      <Marker state={state} shape="ring" />
+                      <StepTitle step={step} state={state} />
+                    </span>
+                  }
+                >
+                  <div className="grid justify-items-center gap-1 rounded-md bg-muted px-4 py-5 text-center">
+                    {step.icon ? <Icon name={step.icon} size={24} className="mb-2 text-muted-foreground" /> : null}
+                    {step.summary ? <p className="font-medium text-foreground">{step.summary}</p> : null}
+                    {step.description ? <p className="max-w-xs text-muted-foreground">{step.description}</p> : null}
+                    <div className="mt-4">
+                      {action(step, i)}
+                    </div>
+                    {lockedNote(step)}
+                    <StepError message={errors[step.key]} />
+                  </div>
+                </Collapsible>
+              </div>
+            );
+          })}
+        </div>
+        {footer ? <div className="text-sm">{footer}</div> : null}
+      </div>
+    );
+  }
+
+  /* ---- cards: numbered step cards, a bar over them ------------------- */
+
+  if (variant === "cards") {
+    return (
+      <div className={cx("grid gap-4", className)}>
+        {header(
+          <div className="grid gap-2">
+            <p data-nums className="text-sm text-muted-foreground">
+              {allDone ? (
+                <span className="font-medium text-success">{doneLabel}</span>
+              ) : (
+                <>
+                  <span className="font-medium text-foreground">{doneCount}</span> of {total} done
+                </>
+              )}
+            </p>
+            {bar}
+          </div>,
+        )}
+        <ol className="grid gap-3" aria-label={title}>
+          {list.map((step, i) => {
+            const state = stateOf(i);
+            return (
+              <li
+                key={step.key}
+                aria-current={state === "current" ? "step" : undefined}
+                className={cx("rounded-lg border p-4", state === "current" ? "border-primary/40 bg-muted" : "border-border bg-card")}
+              >
+                <div className="flex gap-3">
+                  <Marker state={state} index={i} shape="number" />
+                  <div className="min-w-0 flex-1">
+                    <p className="font-medium">
+                      <StepTitle step={step} state={state} />
+                    </p>
+                    {step.description ? (
+                      <p className={cx("mt-0.5 text-sm", state === "current" ? "text-muted-foreground" : "text-muted-foreground/80")}>{step.description}</p>
+                    ) : null}
+                    {state === "current" ? (
+                      <div className="mt-3">
+                        {action(step, i, "icon")}
+                      </div>
+                    ) : null}
+                    <StepError message={errors[step.key]} />
+                  </div>
+                  {step.icon ? (
+                    <Icon name={step.icon} size={20} className={cx("shrink-0", state === "current" ? "text-primary" : "text-muted-foreground/60")} />
+                  ) : null}
+                </div>
+              </li>
+            );
+          })}
+        </ol>
+        {footer ? <div className="text-sm">{footer}</div> : null}
+      </div>
+    );
+  }
+
+  /* ---- list: plain step rows, "Step n of N" and a short bar ---------- */
+
+  return (
+    <div className={cx("grid gap-4", className)}>
+      {header(
+        <div className="flex items-center justify-end gap-3">
+          <span data-nums className="text-sm text-muted-foreground">
+            {allDone ? doneLabel : `Step ${current + 1} of ${total}`}
+          </span>
+          <div className="w-32">{bar}</div>
+        </div>,
+      )}
+      <ol className="grid gap-3" aria-label={title}>
+        {list.map((step, i) => {
+          const state = stateOf(i);
+          return (
+            <li
+              key={step.key}
+              aria-current={state === "current" ? "step" : undefined}
+              className={cx("rounded-lg border bg-card p-4", state === "current" ? "border-foreground/25" : "border-border")}
+            >
+              <div className="flex items-start gap-3">
+                {state === "done" ? (
+                  <Marker state="done" />
+                ) : (
+                  <span aria-hidden="true" data-nums className="flex size-5 shrink-0 items-center justify-center text-sm font-medium text-muted-foreground">
+                    {i + 1}.
+                  </span>
+                )}
+                <div className="min-w-0 flex-1">
+                  <p className="font-medium">
+                    <StepTitle step={step} state={state} />
+                  </p>
+                  {step.description ? <p className="mt-1 text-sm text-muted-foreground">{step.description}</p> : null}
+                  {state === "current" ? (
+                    <div className="mt-3">
+                      {action(step, i)}
+                    </div>
+                  ) : null}
+                  <StepError message={errors[step.key]} />
+                </div>
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+      {footer ? <div className="rounded-lg bg-muted p-4 text-sm">{footer}</div> : null}
+    </div>
+  );
+}