makersclaw 0.2.0 → 0.3.1

package/registry/blocks/page-builder/tokens.js

@@ -0,0 +1,329 @@
+// The token choices — the only styles the Design panel can set, and how a
+// page keeps the workspace theme.
+//
+// A page's CSS never holds a colour. Every colour it can carry is a theme
+// token written as `var(--color-<name>)`, the same variables the app's
+// Tailwind utilities read; fonts and corners read `--theme-font-*` and
+// `--theme-radius`. So a saved page repaints when the theme changes: the
+// values live in the theme, the page only names them.
+//
+// Two places need the tokens defined:
+//   the app    Tailwind emits a theme variable only when some source names
+//              it. KEEP_TOKENS below names every token a page can use (as
+//              no-op arbitrary properties on the editor and PageView roots),
+//              so installing this block is enough for them to exist.
+//   a frame    the editor's canvas is an iframe and does not see the app's
+//              stylesheet. tokenCss(root) resolves each token where the
+//              editor sits (its own light/dark and [data-theme] scope) and
+//              the editor writes the result into the frame; it re-runs when
+//              the theme changes. pageDocument() uses the same string for a
+//              standalone HTML export.
+
+/** Every colour token a page may name, in the order the pickers show. */
+export const COLOR_TOKENS = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "border",
+  "destructive",
+  "success",
+  "warning",
+  "info",
+];
+
+/** The non-colour theme variables a page reads (always present: globals.css sets them). */
+export const THEME_VARS = ["--theme-font-sans", "--theme-font-display", "--theme-font-mono", "--theme-radius"];
+
+// Written out whole so Tailwind reads each var() and emits the variable.
+export const KEEP_TOKENS = [
+  "[--pb-k1:var(--color-background)]",
+  "[--pb-k2:var(--color-foreground)]",
+  "[--pb-k3:var(--color-card)]",
+  "[--pb-k4:var(--color-card-foreground)]",
+  "[--pb-k5:var(--color-primary)]",
+  "[--pb-k6:var(--color-primary-foreground)]",
+  "[--pb-k7:var(--color-secondary)]",
+  "[--pb-k8:var(--color-secondary-foreground)]",
+  "[--pb-k9:var(--color-muted)]",
+  "[--pb-k10:var(--color-muted-foreground)]",
+  "[--pb-k11:var(--color-accent)]",
+  "[--pb-k12:var(--color-accent-foreground)]",
+  "[--pb-k13:var(--color-border)]",
+  "[--pb-k14:var(--color-destructive)]",
+  "[--pb-k15:var(--color-success)]",
+  "[--pb-k16:var(--color-warning)]",
+  "[--pb-k17:var(--color-info)]",
+].join(" ");
+
+const v = (name) => `var(--color-${name})`;
+
+/**
+ * The Design panel's groups. Each option is a plain CSS patch; `match`
+ * is the property read back to show which option is on. A consumer can
+ * pass its own list (the `styles` prop) built from the same shape; keep
+ * colours as tokens (`var(--color-…)`) so the page repaints with the theme.
+ */
+export const STYLE_GROUPS = [
+  {
+    id: "color",
+    label: "Text colour",
+    kind: "swatch",
+    for: ["text", "link", "box"],
+    match: "color",
+    options: [
+      { value: "", label: "Default", css: { color: "" } },
+      { value: "foreground", label: "Text", css: { color: v("foreground") } },
+      { value: "muted-foreground", label: "Muted", css: { color: v("muted-foreground") } },
+      { value: "primary", label: "Primary", css: { color: v("primary") } },
+      { value: "primary-foreground", label: "On primary", css: { color: v("primary-foreground") } },
+      { value: "background", label: "Page", css: { color: v("background") } },
+      { value: "destructive", label: "Alert", css: { color: v("destructive") } },
+    ],
+  },
+  {
+    id: "fill",
+    label: "Background",
+    kind: "swatch",
+    for: ["link", "box"],
+    match: "background-color",
+    options: [
+      { value: "", label: "Default", css: { "background-color": "" } },
+      { value: "transparent", label: "None", css: { "background-color": "transparent" } },
+      { value: "background", label: "Page", css: { "background-color": v("background") } },
+      { value: "card", label: "Card", css: { "background-color": v("card") } },
+      { value: "muted", label: "Muted", css: { "background-color": v("muted") } },
+      { value: "accent", label: "Accent", css: { "background-color": v("accent") } },
+      { value: "primary", label: "Primary", css: { "background-color": v("primary") } },
+      { value: "foreground", label: "Inverted", css: { "background-color": v("foreground") } },
+    ],
+  },
+  {
+    id: "size",
+    label: "Text size",
+    kind: "select",
+    for: ["text", "link"],
+    match: "font-size",
+    options: [
+      { value: "", label: "Default", css: { "font-size": "", "line-height": "" } },
+      { value: "0.875rem", label: "Small", css: { "font-size": "0.875rem", "line-height": "1.5" } },
+      { value: "1rem", label: "Body", css: { "font-size": "1rem", "line-height": "1.6" } },
+      { value: "1.25rem", label: "Large", css: { "font-size": "1.25rem", "line-height": "1.5" } },
+      { value: "1.75rem", label: "Title", css: { "font-size": "1.75rem", "line-height": "1.25" } },
+      { value: "2.5rem", label: "Headline", css: { "font-size": "2.5rem", "line-height": "1.1" } },
+      { value: "3.5rem", label: "Display", css: { "font-size": "3.5rem", "line-height": "1.05" } },
+    ],
+  },
+  {
+    id: "weight",
+    label: "Weight",
+    kind: "segmented",
+    for: ["text", "link"],
+    match: "font-weight",
+    options: [
+      { value: "", label: "Default", css: { "font-weight": "" } },
+      { value: "400", label: "Regular", css: { "font-weight": "400" } },
+      { value: "500", label: "Medium", css: { "font-weight": "500" } },
+      { value: "700", label: "Bold", css: { "font-weight": "700" } },
+    ],
+  },
+  {
+    id: "font",
+    label: "Typeface",
+    kind: "segmented",
+    for: ["text"],
+    match: "font-family",
+    options: [
+      { value: "", label: "Default", css: { "font-family": "" } },
+      { value: "var(--theme-font-display)", label: "Display", css: { "font-family": "var(--theme-font-display)" } },
+      { value: "var(--theme-font-mono)", label: "Mono", css: { "font-family": "var(--theme-font-mono)" } },
+    ],
+  },
+  {
+    id: "align",
+    label: "Align",
+    kind: "segmented",
+    for: ["text", "box"],
+    match: "text-align",
+    options: [
+      { value: "", label: "Default", css: { "text-align": "" } },
+      { value: "left", label: "Left", icon: "align-left", css: { "text-align": "left" } },
+      { value: "center", label: "Centre", icon: "align-center", css: { "text-align": "center" } },
+      { value: "right", label: "Right", icon: "align-right", css: { "text-align": "right" } },
+    ],
+  },
+  {
+    id: "spaceY",
+    label: "Space above and below",
+    kind: "segmented",
+    for: ["text", "link", "box"],
+    match: "padding-top",
+    options: [
+      { value: "", label: "Default", css: { "padding-top": "", "padding-bottom": "" } },
+      { value: "0px", label: "None", css: { "padding-top": "0px", "padding-bottom": "0px" } },
+      { value: "12px", label: "S", css: { "padding-top": "12px", "padding-bottom": "12px" } },
+      { value: "32px", label: "M", css: { "padding-top": "32px", "padding-bottom": "32px" } },
+      { value: "64px", label: "L", css: { "padding-top": "64px", "padding-bottom": "64px" } },
+      { value: "112px", label: "XL", css: { "padding-top": "112px", "padding-bottom": "112px" } },
+    ],
+  },
+  {
+    id: "spaceX",
+    label: "Space at the sides",
+    kind: "segmented",
+    for: ["link", "box"],
+    match: "padding-left",
+    options: [
+      { value: "", label: "Default", css: { "padding-left": "", "padding-right": "" } },
+      { value: "0px", label: "None", css: { "padding-left": "0px", "padding-right": "0px" } },
+      { value: "12px", label: "S", css: { "padding-left": "12px", "padding-right": "12px" } },
+      { value: "24px", label: "M", css: { "padding-left": "24px", "padding-right": "24px" } },
+      { value: "48px", label: "L", css: { "padding-left": "48px", "padding-right": "48px" } },
+    ],
+  },
+  {
+    id: "width",
+    label: "Width",
+    kind: "segmented",
+    for: ["box", "image"],
+    match: "max-width",
+    options: [
+      { value: "", label: "Default", css: { "max-width": "", "margin-left": "", "margin-right": "" } },
+      { value: "640px", label: "Narrow", css: { "max-width": "640px", "margin-left": "auto", "margin-right": "auto" } },
+      { value: "960px", label: "Normal", css: { "max-width": "960px", "margin-left": "auto", "margin-right": "auto" } },
+      { value: "none", label: "Full", css: { "max-width": "none", "margin-left": "", "margin-right": "" } },
+    ],
+  },
+  {
+    id: "radius",
+    label: "Corners",
+    kind: "segmented",
+    for: ["link", "box", "image"],
+    match: "border-radius",
+    options: [
+      { value: "", label: "Default", css: { "border-radius": "" } },
+      { value: "0px", label: "Square", css: { "border-radius": "0px" } },
+      { value: "var(--theme-radius)", label: "Theme", css: { "border-radius": "var(--theme-radius)" } },
+      { value: "calc(var(--theme-radius) * 2.5)", label: "Soft", css: { "border-radius": "calc(var(--theme-radius) * 2.5)" } },
+      { value: "9999px", label: "Pill", css: { "border-radius": "9999px" } },
+    ],
+  },
+  {
+    id: "border",
+    label: "Border",
+    kind: "swatch",
+    for: ["link", "box", "image"],
+    match: "border-color",
+    options: [
+      { value: "", label: "Default", css: { "border-width": "", "border-style": "", "border-color": "" } },
+      { value: "transparent", label: "None", css: { "border-width": "0px", "border-style": "none", "border-color": "transparent" } },
+      { value: "border", label: "Hairline", css: { "border-width": "1px", "border-style": "solid", "border-color": v("border") } },
+      { value: "primary", label: "Primary", css: { "border-width": "1px", "border-style": "solid", "border-color": v("primary") } },
+    ],
+  },
+];
+
+/** The token name a swatch option paints, for its colour dot ("" for
+ *  Default and None). */
+export function swatchVar(option) {
+  if (!option?.value || option.value === "transparent") return "";
+  return `var(--color-${option.value})`;
+}
+
+/** The groups that apply to a kind of element: text · link · image · box.
+ *  A group with no `for` applies to every kind. */
+export function groupsFor(groups, kind) {
+  return (groups ?? []).filter((g) => !g.for || g.for.includes(kind));
+}
+
+/** Which option of a group is on, from a component's own style object. */
+export function currentOption(group, style = {}) {
+  const raw = String(style?.[group.match] ?? "").replace(/\s*!important\s*$/, "").trim();
+  if (!raw) return "";
+  for (const o of group.options) {
+    const css = o.css?.[group.match];
+    if (css && css === raw) return o.value;
+  }
+  return "custom";
+}
+
+/** The patch for choosing `value` in `group`: every prop the group owns,
+ *  set or cleared ("" clears). */
+export function patchFor(group, value) {
+  const option = group.options.find((o) => o.value === value) ?? group.options[0];
+  const props = new Set();
+  for (const o of group.options) for (const k of Object.keys(o.css ?? {})) props.add(k);
+  const patch = {};
+  for (const k of props) patch[k] = option.css?.[k] ?? "";
+  return patch;
+}
+
+/** Browser only: the tokens resolved where `root` sits, as one `:root{…}`
+ *  rule — for the canvas frame and for a standalone export. Each colour is
+ *  read off a hidden probe (`color: var(--color-x)`), so light-dark(),
+ *  color-mix() and a [data-theme] scope all resolve as the app paints them. */
+export function tokenCss(root) {
+  if (typeof document === "undefined") return "";
+  const host = root ?? document.body;
+  const probe = document.createElement("span");
+  probe.setAttribute("aria-hidden", "true");
+  probe.style.position = "absolute";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  host.appendChild(probe);
+  const lines = [];
+  try {
+    for (const name of COLOR_TOKENS) {
+      probe.style.color = "";
+      probe.style.color = `var(--color-${name})`;
+      const value = getComputedStyle(probe).color;
+      if (value) lines.push(`--color-${name}:${value}`);
+    }
+    const cs = getComputedStyle(host);
+    for (const name of THEME_VARS) {
+      const value = cs.getPropertyValue(name).trim();
+      if (value) lines.push(`${name}:${value}`);
+    }
+    const scheme = cs.colorScheme;
+    if (scheme && scheme !== "normal") lines.push(`color-scheme:${scheme}`);
+  } finally {
+    probe.remove();
+  }
+  return `:root{${lines.join(";")}}`;
+}
+
+/** Browser only: the @font-face rules the app has loaded (next/font and
+ *  friends), so the canvas frame draws the theme's typefaces. Rules in a
+ *  stylesheet from another origin cannot be read and are skipped. */
+export function fontFaceCss() {
+  if (typeof document === "undefined") return "";
+  const out = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    for (const rule of Array.from(rules ?? [])) {
+      if (rule.type === 5 /* CSSRule.FONT_FACE_RULE */) out.push(rule.cssText);
+    }
+  }
+  return out.join("\n");
+}
+
+/** Browser only: the href of every font stylesheet link (Google Fonts…). */
+export function fontLinks() {
+  if (typeof document === "undefined") return [];
+  return Array.from(document.querySelectorAll('link[rel="stylesheet"]'))
+    .map((l) => l.href)
+    .filter((h) => /fonts\.(googleapis|bunny)\.|typekit|fontshare/.test(h));
+}

package/registry/blocks/payment-methods/README.md

@@ -0,0 +1,104 @@
+# PaymentMethods
+
+The payment methods a customer has saved, as a grid of cards. Each card
+shows the brand, the last four digits, the expiry and, on one of them, a
+Default badge. An expired card is marked in the danger tone, one that
+expires this month or next in the warning tone.
+
+The actions are Make default, Remove (behind a Confirm) and Add. Add is
+the app's: it opens the payment provider (Paddle), which collects the
+card. **The block never shows a card-number field.** Every action goes out
+through a callback that returns `{ ok }`, and a failed one is shown on the
+card it was for.
+
+```jsx
+import { PaymentMethods } from "../components/blocks/payment-methods";   // a Makersclaw app ("./blocks/payment-methods" from components/)
+import { PaymentMethods } from "@/components/makersclaw/blocks/payment-methods";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the methods in the server surface (README §4).
+
+## The data
+
+One saved method, as the provider reports it:
+
+```js
+{ id: "pm_1", brand: "visa", last4: "4242", expMonth: 8, expYear: 2028, isDefault: true, holder: "Maya Chen" }
+```
+
+- `brand` — `visa`, `mastercard`, `amex`, `discover`, `jcb`, `unionpay`,
+  `maestro`, `paypal`, `apple_pay`, `google_pay`, `bank` or `card`. Any
+  other word is shown as written. Apple Pay and Google Pay get their
+  marks; every card brand gets the card glyph and its name in words (the
+  kit draws no card-brand logos).
+- `last4` — the last four digits. Nothing more of the number ever comes in.
+- `expMonth` (1–12) · `expYear` (2028 or 28) — optional; a wallet has none.
+- `isDefault` — true on one method.
+- `holder` — the name on it; `label` — call it something else ("Company
+  Amex"); `email` — for a wallet with no last four (PayPal).
+
+## Props
+
+- `methods` — the saved methods. An empty list shows the empty state.
+- `onAdd()` — the Add button (in the header, and in the empty state).
+  Open Paddle's update-payment-method checkout here; return
+  `{ ok: false, error }` if it could not open. Without it there is no Add.
+- `onSetDefault(method)` — Make default on every other card; return
+  `{ ok: true }` or `{ ok: false, error }`. An expired card cannot be made
+  the default. Without it, no button.
+- `onRemove(method)` — Remove, asked through a Confirm; same return. The
+  default cannot be removed while there are others: make another the
+  default first (the button says why on hover). Without it, no button.
+- `loading` — skeleton cards. `error` — a line above the list (the
+  methods did not load).
+- `title` · `description` · `addLabel` · `emptyTitle` · `emptyBody` — words.
+- `today` — `"YYYY-MM-DD"`, the day expiry is judged against; default
+  today.
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/Billing.jsx — client
+"use client";
+import { PaymentMethods } from "./blocks/payment-methods";
+
+export default function Billing({ methods, error }) {
+  const post = (path, body) =>
+    fetch(path, { method: "POST", body: JSON.stringify(body) }).then((r) =>
+      r.ok ? { ok: true } : { ok: false, error: "That did not save. Try again." },
+    );
+  return (
+    <PaymentMethods
+      methods={methods}
+      error={error}
+      onAdd={async () => {
+        const res = await fetch("/api/billing/update-method", { method: "POST" });
+        if (!res.ok) return { ok: false, error: "Could not open the payment form." };
+        const { transactionId } = await res.json();
+        window.Paddle?.Checkout.open({ transactionId });
+        return { ok: true };
+      }}
+      onSetDefault={(m) => post("/api/billing/default-method", { id: m.id })}
+      onRemove={(m) => post("/api/billing/remove-method", { id: m.id })}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Take or show a full card number, a CVC or an expiry field. Adding and
+  editing a card is the provider's form, opened from `onAdd`.
+- Draw card-brand logos: brands are named in words beside a card glyph.
+- Edit a saved card in place: providers replace a card; add the new one,
+  make it the default, remove the old.
+
+A list 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 payment-methods` restores them.
+
+## Credits
+
+Shape and behaviour from Creative Tim UI (https://github.com/creativetimofficial/ui), MIT; this is a rewrite on the Makersclaw kit.

package/registry/blocks/payment-methods/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "payment-methods",
+  "title": "PaymentMethods",
+  "description": "A customer's SAVED payment methods as cards: brand, last four digits, expiry (expired and expiring soon flagged) and a Default badge; Make default, Remove behind a Confirm, and Add, which hands off to the payment provider (Paddle). Never a card-number field. Empty, loading and error states built in.",
+  "useWhen": "A billing or account page where a customer manages the cards and wallets on file. Not for taking a payment (cart's checkout step hands off to Paddle) or for a list of charges (transaction-list).",
+  "tags": ["payment", "payment methods", "cards", "credit card", "wallet", "billing", "default card", "saved cards", "paddle", "account", "commerce"],
+  "exports": ["PaymentMethods"],
+  "files": ["index.js", "payment-methods.jsx"],
+  "requires": []
+}

package/registry/blocks/payment-methods/demo.jsx

@@ -0,0 +1,71 @@
+"use client";
+
+// PaymentMethods with methods in memory — the gallery's and the smoke
+// test's surface. Not installed into apps.
+import { useState } from "react";
+import { Switch, ToggleGroup } from "../components/ui";
+import { PaymentMethods } from "../components/blocks/payment-methods";
+
+const START = [
+  { id: "pm_1", brand: "visa", last4: "4242", expMonth: 8, expYear: 2028, isDefault: true, holder: "Maya Chen" },
+  { id: "pm_2", brand: "mastercard", last4: "5100", expMonth: 10, expYear: 2026, holder: "Maya Chen" },
+  { id: "pm_3", brand: "amex", last4: "0005", expMonth: 3, expYear: 2026, label: "Company Amex" },
+  { id: "pm_4", brand: "apple_pay" },
+];
+
+const VIEWS = [
+  { value: "list", label: "Saved" },
+  { value: "empty", label: "Empty" },
+  { value: "loading", label: "Loading" },
+];
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export default function PaymentMethodsDemo() {
+  const [view, setView] = useState("list");
+  const [methods, setMethods] = useState(START);
+  const [failing, setFailing] = useState(false);
+  const [said, setSaid] = useState(null);
+
+  const settle = async () => {
+    await wait(500);
+    return failing ? { ok: false, error: "The payment provider did not answer. Try again." } : null;
+  };
+
+  return (
+    <div className="grid gap-6">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <ToggleGroup items={VIEWS} value={view} onChange={setView} size="sm" aria-label="Which state to show" />
+        <Switch id="pm-fail" checked={failing} onChange={(e) => setFailing(e.target.checked)} label="Make saves fail" />
+      </div>
+      {said ? (
+        <p role="status" className="text-sm text-muted-foreground">
+          {said}
+        </p>
+      ) : null}
+      <PaymentMethods
+        methods={view === "empty" ? [] : methods}
+        loading={view === "loading"}
+        today="2026-09-23"
+        onAdd={async () => {
+          const failed = await settle();
+          if (failed) return failed;
+          setSaid("onAdd was called. The app would open Paddle's form to add a card now.");
+          return { ok: true };
+        }}
+        onSetDefault={async (m) => {
+          const failed = await settle();
+          if (failed) return failed;
+          setMethods((all) => all.map((x) => ({ ...x, isDefault: x.id === m.id })));
+          return { ok: true };
+        }}
+        onRemove={async (m) => {
+          const failed = await settle();
+          if (failed) return failed;
+          setMethods((all) => all.filter((x) => x.id !== m.id));
+          return { ok: true };
+        }}
+      />
+    </div>
+  );
+}

package/registry/blocks/payment-methods/index.js

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