makersclaw 0.2.0 → 0.3.1

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

@@ -0,0 +1,333 @@
+"use client";
+
+// SettingsList in each of its shapes — the gallery's and the smoke test's
+// surface. Not installed into apps. Saves are pretend: pick whether they
+// succeed or fail, and watch the row that changed.
+import { useState } from "react";
+import { Button, Field, InputGroup, Notice, Select, toast } from "../components/ui";
+import { SettingsList } from "../components/blocks/settings-list";
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const PREFERENCES = [
+  { key: "digest", icon: "mail", label: "Weekly digest", description: "A summary of the week's numbers, every Monday at 8:00.", control: { type: "switch", value: true } },
+  { key: "sounds", icon: "bell", label: "Sounds", description: "Play a sound when a message arrives.", control: { type: "switch", value: false } },
+  {
+    key: "theme",
+    icon: "palette",
+    label: "Appearance",
+    description: "How the app looks on this device.",
+    control: {
+      type: "select",
+      value: "system",
+      options: [
+        { value: "system", label: "Match the system" },
+        { value: "light", label: "Light" },
+        { value: "dark", label: "Dark" },
+      ],
+    },
+  },
+  {
+    key: "week",
+    icon: "calendar",
+    label: "Week starts on",
+    control: {
+      type: "select",
+      value: "mon",
+      options: [
+        { value: "mon", label: "Monday" },
+        { value: "sun", label: "Sunday" },
+        { value: "sat", label: "Saturday" },
+      ],
+    },
+  },
+  { key: "export", icon: "download", label: "Export your data", description: "Everything you own, as a zip of CSV files.", control: { type: "button", label: "Export", icon: "download" } },
+];
+
+const METHODS = [
+  {
+    key: "keys",
+    icon: "key",
+    label: "Security keys",
+    badge: { label: "Recommended", tone: "success" },
+    description: "A hardware key you touch to sign in. The strongest option.",
+    value: "No keys added",
+    control: { type: "button", label: "Add", variant: "primary" },
+  },
+  {
+    key: "app",
+    icon: "smartphone",
+    label: "Authenticator app",
+    badge: { label: "Recommended", tone: "success" },
+    description: "Six-digit codes from an app on your phone.",
+    value: "Not set up",
+    control: { type: "button", label: "Set up", variant: "primary" },
+  },
+  {
+    key: "sms",
+    icon: "message-square",
+    label: "Text message",
+    description: "Codes sent to your phone by SMS.",
+    value: "+44 7700 900 461",
+    valueTone: "set",
+    control: { type: "button", label: "Edit" },
+  },
+];
+
+const SESSIONS = [
+  { key: "s1", icon: "laptop", label: "MacBook Pro", badge: { label: "This device", tone: "info" }, meta: [{ icon: "globe", text: "Lisbon, Portugal" }, { icon: "clock", text: "Active now" }, "Safari 18 on macOS 15"] },
+  {
+    key: "s2",
+    icon: "smartphone",
+    label: "iPhone 15",
+    meta: [{ icon: "globe", text: "Porto, Portugal" }, { icon: "clock", text: "Yesterday, 18:40" }, "Makersclaw for iOS"],
+    control: { type: "remove", label: "Sign out iPhone 15", confirm: { title: "Sign out this iPhone?", body: "It will need your password to come back.", confirmLabel: "Sign out" } },
+  },
+  {
+    key: "s3",
+    icon: "monitor",
+    label: "Windows desktop",
+    meta: [{ icon: "globe", text: "Madrid, Spain" }, { icon: "clock", text: "3 days ago" }, "Firefox 131 on Windows 11"],
+    control: { type: "remove", label: "Sign out Windows desktop", confirm: { title: "Sign out this desktop?", body: "It will need your password to come back.", confirmLabel: "Sign out" } },
+  },
+];
+
+const INTEGRATIONS = [
+  { key: "github", icon: "github", label: "GitHub", badge: { label: "Development", hue: 1 }, description: "Link commits and pull requests to tasks.", control: { type: "switch", value: false } },
+  {
+    key: "slack",
+    icon: "message-square",
+    label: "Slack",
+    badge: { label: "Messaging", hue: 2 },
+    description: "Post a note to a channel when a deal moves.",
+    control: { type: "switch", value: true },
+    connected: { account: "ops@quillhouse.com", code: "QH-4417-208" },
+  },
+  { key: "google", icon: "google", label: "Google Calendar", badge: { label: "Calendar", hue: 3 }, description: "Put booked calls on your calendar.", control: { type: "switch", value: false } },
+];
+
+const BILLING = [
+  {
+    key: "b1",
+    icon: "building",
+    label: "Harbourline Ltd",
+    description: "Main account",
+    meta: ["Contact: Tomas Kowalski", "tomas@harbourline.co", "VAT GB 204 1187 63"],
+    control: { type: "actions", items: [{ key: "edit", label: "Edit", icon: "pencil" }, { key: "delete", label: "Delete", icon: "trash", tone: "danger", confirm: { title: "Delete this billing profile?", body: "Invoices already sent keep it.", confirmLabel: "Delete" } }] },
+  },
+  {
+    key: "b2",
+    icon: "building",
+    label: "Harbourline GmbH",
+    description: "Germany",
+    meta: ["Contact: Lena Vogt", "lena@harbourline.de", "VAT DE 318 552 904"],
+    control: { type: "actions", items: [{ key: "edit", label: "Edit", icon: "pencil" }, { key: "delete", label: "Delete", icon: "trash", tone: "danger", confirm: { title: "Delete this billing profile?", body: "Invoices already sent keep it.", confirmLabel: "Delete" } }] },
+  },
+];
+
+const CHANNELS = [
+  { key: "email", label: "Email", icon: "mail" },
+  { key: "push", label: "Push", icon: "smartphone" },
+  { key: "sms", label: "SMS", icon: "message-square" },
+];
+
+const EVENTS = [
+  { key: "mentions", group: "Conversations", label: "Mentions", description: "Someone mentions you in a comment.", values: { email: true, push: true, sms: false } },
+  { key: "replies", group: "Conversations", label: "Replies", description: "Someone answers a thread you are in.", values: { email: true, push: false, sms: false } },
+  { key: "signin", group: "Security", label: "New sign-in", description: "Your account is used on a new device.", values: { email: true, push: true, sms: true }, locked: ["email"] },
+  { key: "password", group: "Security", label: "Password changed", description: "Sent the moment it happens.", values: { email: true, push: true, sms: false }, locked: ["email"] },
+  { key: "product", group: "Product", label: "What's new", description: "New features, once a month.", values: { email: false, push: false, sms: null } },
+];
+
+const VARIANTS = {
+  preferences: { label: "Preferences" },
+  methods: { label: "Two-step sign-in" },
+  sessions: { label: "Signed-in devices" },
+  integrations: { label: "Integrations" },
+  details: { label: "Billing profiles" },
+  matrix: { label: "Notifications" },
+};
+
+/** Rows in memory with a pretend save that honours the chosen outcome. */
+function useRows(initial, outcome) {
+  const [rows, setRows] = useState(initial);
+  async function save(fn) {
+    await wait(800);
+    if (outcome === "fail") return { ok: false, error: "The server did not answer." };
+    fn?.();
+    return { ok: true };
+  }
+  return { rows, setRows, save };
+}
+
+function setControl(rows, key, value) {
+  return rows.map((r) => (r.key === key ? { ...r, control: { ...r.control, value } } : r));
+}
+
+export default function SettingsListDemo() {
+  const [variant, setVariant] = useState("preferences");
+  const [outcome, setOutcome] = useState("ok");
+  const [state, setState] = useState("ready");
+
+  const prefs = useRows(PREFERENCES, outcome);
+  const methods = useRows(METHODS, outcome);
+  const sessions = useRows(SESSIONS, outcome);
+  const integrations = useRows(INTEGRATIONS, outcome);
+  const billing = useRows(BILLING, outcome);
+  const events = useRows(EVENTS, outcome);
+
+  const common = {
+    loading: state === "loading",
+    error: state === "error" ? "The settings service is not answering." : undefined,
+    onRetry: () => setState("ready"),
+  };
+  const pick = (rows) => (state === "empty" ? [] : rows);
+
+  let list;
+  if (variant === "preferences") {
+    list = (
+      <SettingsList
+        {...common}
+        title="Preferences"
+        description="Saved as you change them."
+        rows={pick(prefs.rows)}
+        onChange={(row, value) => prefs.save(() => prefs.setRows((rs) => setControl(rs, row.key, value)))}
+        onAction={() => prefs.save(() => toast("Your export is on its way by email."))}
+      />
+    );
+  } else if (variant === "methods") {
+    list = (
+      <SettingsList
+        {...common}
+        icon="shield"
+        title="Two-step sign-in"
+        description="A second step after your password, so a leaked password is not enough."
+        badge={{ label: "On", tone: "success", icon: "circle-check" }}
+        rows={pick(methods.rows)}
+        onAction={(row) => methods.save(() => toast(`${row.label}: the setup would open here.`))}
+        footer={<Notice tone="info">Keep at least two methods, so losing a phone never locks you out.</Notice>}
+      />
+    );
+  } else if (variant === "sessions") {
+    list = (
+      <SettingsList
+        {...common}
+        icon="shield-check"
+        title="Signed-in devices"
+        description="Where your account is open now. Sign out anything you do not recognise."
+        rows={pick(sessions.rows)}
+        onAction={(row) => sessions.save(() => sessions.setRows((rs) => rs.filter((r) => r.key !== row.key)))}
+        emptyTitle="No other devices"
+        footer={<Notice tone="warning" title="Something you don't recognise?">Sign it out, then change your password.</Notice>}
+      />
+    );
+  } else if (variant === "integrations") {
+    list = (
+      <SettingsList
+        {...common}
+        icon="layers"
+        title="Integrations"
+        description="Tools this workspace talks to."
+        rows={pick(integrations.rows).map((r) => ({
+          ...r,
+          details: r.control.value
+            ? () => (
+                <div className="grid gap-3">
+                  <p>
+                    Connected as <span className="font-medium">{r.connected?.account ?? "ops@quillhouse.com"}</span>
+                  </p>
+                  <Field id={`code-${r.key}`} label="Verification code" hint="Paste it in the other tool to finish linking.">
+                    <InputGroup
+                      id={`code-${r.key}`}
+                      readOnly
+                      value={r.connected?.code ?? "QH-0000-000"}
+                      action={{
+                        label: "Copy",
+                        icon: "copy",
+                        onClick: () => {
+                          navigator.clipboard?.writeText(r.connected?.code ?? "").catch(() => {});
+                          toast("Copied");
+                        },
+                      }}
+                    />
+                  </Field>
+                </div>
+              )
+            : undefined,
+        }))}
+        onChange={(row, value) => integrations.save(() => integrations.setRows((rs) => setControl(rs, row.key, value)))}
+      />
+    );
+  } else if (variant === "details") {
+    list = (
+      <SettingsList
+        {...common}
+        title="Billing profiles"
+        description="Who invoices are addressed to."
+        actions={
+          <Button size="sm" icon="plus" onClick={() => toast("A billing form would open here.")}>
+            Add profile
+          </Button>
+        }
+        rows={pick(billing.rows)}
+        onAction={(row, action) =>
+          billing.save(() => {
+            if (action === "delete") billing.setRows((rs) => rs.filter((r) => r.key !== row.key));
+            else toast(`Editing ${row.label}`);
+          })
+        }
+        emptyTitle="No billing profiles"
+        emptyBody="Add one so invoices carry your company's details."
+      />
+    );
+  } else {
+    list = (
+      <SettingsList
+        {...common}
+        variant="matrix"
+        title="Notifications"
+        description="Choose where each kind of news reaches you. Security emails always go out."
+        channels={CHANNELS}
+        rows={pick(events.rows)}
+        onChange={(row, value, channel) =>
+          events.save(() => events.setRows((rs) => rs.map((r) => (r.key === row.key ? { ...r, values: { ...r.values, [channel]: value } } : r))))
+        }
+      />
+    );
+  }
+
+  return (
+    <div className="grid max-w-3xl gap-4">
+      <div className="grid gap-3 sm:grid-cols-3">
+        <Field id="sl-variant" label="Shape">
+          <Select id="sl-variant" value={variant} onChange={(e) => setVariant(e.target.value)} options={Object.entries(VARIANTS).map(([value, v]) => ({ value, label: v.label }))} />
+        </Field>
+        <Field id="sl-outcome" label="Saving">
+          <Select
+            id="sl-outcome"
+            value={outcome}
+            onChange={(e) => setOutcome(e.target.value)}
+            options={[
+              { value: "ok", label: "Succeeds" },
+              { value: "fail", label: "Fails" },
+            ]}
+          />
+        </Field>
+        <Field id="sl-state" label="State">
+          <Select
+            id="sl-state"
+            value={state}
+            onChange={(e) => setState(e.target.value)}
+            options={[
+              { value: "ready", label: "Loaded" },
+              { value: "loading", label: "Loading" },
+              { value: "error", label: "Load failed" },
+              { value: "empty", label: "Empty" },
+            ]}
+          />
+        </Field>
+      </div>
+      {list}
+    </div>
+  );
+}

package/registry/blocks/settings-list/index.js

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

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

@@ -0,0 +1,93 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { Button, Icon, Spinner } from "../../ui";
+
+// Each control in a SettingsList saves on its own. This keeps, per control
+// (a row, or a row × channel in the matrix), what it shows while its save
+// runs (the new value, at once), that it is saving, and why its last save
+// failed — with the attempt kept so "Try again" repeats it.
+
+/** Run `save()` → { ok } | { ok: false, error }; a throw counts as failed. */
+async function attempt(save) {
+  try {
+    const res = await save();
+    return res?.ok ? { ok: true } : { ok: false, error: res?.error };
+  } catch (e) {
+    return { ok: false, error: e?.message };
+  }
+}
+
+function sameValue(a, b) {
+  return a === b || (a == null && b == null);
+}
+
+export function useSaves(failedText = "Not saved.") {
+  const [shown, setShown] = useState({}); // key → { value, from }: the new value, over the stored `from`
+  const [busy, setBusy] = useState({}); // key → true
+  const [failed, setFailed] = useState({}); // key → { error, retry }
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+
+  const drop = (setter, key) =>
+    setter((m) => {
+      if (!(key in m)) return m;
+      const { [key]: _gone, ...rest } = m;
+      return rest;
+    });
+
+  /** Save `key`: show `value` (optional; `stored` is what the rows hold
+   *  now) at once, run `save`, put the stored value back on failure.
+   *  `fallback` words a failure that came back without an error. */
+  async function run(key, save, { value, stored, fallback } = {}) {
+    const retry = () => run(key, save, { value, stored, fallback });
+    if (value !== undefined) setShown((m) => ({ ...m, [key]: { value, from: stored } }));
+    setBusy((m) => ({ ...m, [key]: true }));
+    drop(setFailed, key);
+    const res = await attempt(save);
+    if (!alive.current) return res;
+    drop(setBusy, key);
+    // Good: the new value stays on screen until the rows catch up (see
+    // valueOf). Bad: the stored one returns.
+    if (!res.ok) {
+      drop(setShown, key);
+      setFailed((m) => ({ ...m, [key]: { error: res.error || fallback || failedText, retry } }));
+    }
+    return res;
+  }
+
+  return {
+    run,
+    // The new value while the rows still hold what they held before the
+    // save; once they change (the save landed, or anything else moved
+    // them) the rows are the truth again.
+    valueOf: (key, stored) => (key in shown && sameValue(shown[key].from, stored) ? shown[key].value : stored),
+    isBusy: (key) => Boolean(busy[key]),
+    failure: (key) => failed[key] ?? null,
+    dismiss: (key) => drop(setFailed, key),
+  };
+}
+
+/** The line under a row whose save failed: why, and Try again. */
+export function Failure({ failure, id, className }) {
+  if (!failure) return null;
+  return (
+    <p id={id} role="alert" className={className ?? "flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-destructive"}>
+      <Icon name="warning" size={14} className="shrink-0" />
+      <span className="min-w-0">{failure.error}</span>
+      <Button variant="link" size="sm" onClick={failure.retry}>
+        Try again
+      </Button>
+    </p>
+  );
+}
+
+/** A small spinner that says what is happening. */
+export function Saving({ label = "Saving" }) {
+  return <Spinner size="sm" label={label} className="text-muted-foreground" />;
+}