makersclaw 0.2.0 → 0.3.1

package/registry/blocks/product-grid/product-card.jsx

@@ -0,0 +1,232 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Badge, Button, Image, Kicker, Rating, Toggle, cx } from "../../ui";
+import { Price, cartLine } from "../product-detail";
+
+// One product as a card in the grid, and one promotion as a picture tile.
+// The whole card opens the product (its name is the real link or button,
+// stretched over the card); the heart and the add button sit above that
+// target and click on their own.
+
+async function attempt(fn, ...args) {
+  try {
+    const r = await fn(...args);
+    return r && typeof r === "object" ? r : { ok: Boolean(r) };
+  } catch (e) {
+    return { ok: false, error: e?.message };
+  }
+}
+
+const STRETCH = "after:absolute after:inset-0";
+
+function Title({ href, onOpen, children, className }) {
+  if (href) {
+    return (
+      <Button variant="link" size="inherit" tone="muted" href={href} data-stretch className={cx(STRETCH, className)}>
+        {children}
+      </Button>
+    );
+  }
+  if (onOpen) {
+    return (
+      <Button variant="link" size="inherit" tone="muted" onClick={onOpen} data-stretch className={cx("text-left", STRETCH, className)}>
+        {children}
+      </Button>
+    );
+  }
+  return <span className={className}>{children}</span>;
+}
+
+/**
+ * A product card: picture, badge, heart, brand, name, rating, price and a
+ * quick add. A product with options cannot be added blind: its button
+ * says "Choose options" and opens it.
+ */
+export function ProductCard({ product, onOpen, onAddToCart, onFavorite, favorite = false, currency = "USD", locale, addLabel = "Add to cart", className }) {
+  const [fav, setFav] = useState(favorite);
+  const [status, setStatus] = useState({ state: "idle" });
+  useEffect(() => setFav(favorite), [favorite]);
+  useEffect(() => {
+    if (status.state !== "added") return;
+    const t = setTimeout(() => setStatus({ state: "idle" }), 2500);
+    return () => clearTimeout(t);
+  }, [status.state]);
+
+  const open = onOpen ? () => onOpen(product) : undefined;
+  const cur = product.currency ?? currency;
+  const needsChoice = (product.options ?? []).some((o) => (o.values ?? []).length > 1);
+  const soldOut = product.available === false;
+  const picture = product.image ?? (typeof product.images?.[0] === "object" ? product.images[0]?.src : product.images?.[0]);
+
+  async function add() {
+    setStatus({ state: "busy" });
+    const r = await attempt(onAddToCart, cartLine(product, {}, 1, cur));
+    setStatus(r.ok ? { state: "added" } : { state: "failed", error: r.error || "Not added. Try again." });
+  }
+
+  async function toggle(next) {
+    setFav(next);
+    const r = await attempt(onFavorite, product, next);
+    if (!r.ok) {
+      setFav(!next);
+      setStatus({ state: "failed", error: r.error || (next ? "Not saved." : "Not removed.") });
+    }
+  }
+
+  return (
+    <article
+      className={cx(
+        "relative flex h-full min-w-0 flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground",
+        "has-[a[data-stretch]:focus-visible,button[data-stretch]:focus-visible]:ring-2 has-[a[data-stretch]:focus-visible,button[data-stretch]:focus-visible]:ring-ring",
+        (product.href || onOpen) && "transition-shadow hover:shadow-md",
+        className,
+      )}
+    >
+      <div className="relative">
+        <Image src={picture} alt="" ratio="square" rounded="none" />
+        {product.badge ? (
+          <Badge variant="soft" className="absolute start-2 top-2">
+            {product.badge}
+          </Badge>
+        ) : null}
+        {onFavorite ? (
+          <Toggle
+            icon="heart"
+            label={fav ? `Remove ${product.name} from favourites` : `Save ${product.name} to favourites`}
+            pressed={fav}
+            onPressedChange={toggle}
+            className="absolute end-2 top-2 z-10"
+          />
+        ) : null}
+      </div>
+      <div className="flex flex-1 flex-col gap-1.5 border-t border-border p-3 sm:p-4">
+        {product.brand ? <Kicker className="truncate">{product.brand}</Kicker> : null}
+        <h3 className="line-clamp-2 text-sm font-medium leading-snug">
+          <Title href={product.href} onOpen={open}>
+            {product.name}
+          </Title>
+        </h3>
+        {typeof product.rating === "number" ? (
+          <p className="flex items-center gap-1.5 text-xs text-muted-foreground">
+            <Rating value={product.rating} size="sm" />
+            {typeof product.reviews === "number" ? <span data-nums>({product.reviews.toLocaleString(locale)})</span> : null}
+          </p>
+        ) : null}
+        <Price price={product.price} compareAt={product.compareAt} currency={cur} locale={locale} size="md" className="mt-auto pt-1" />
+        {onAddToCart ? (
+          <div className="relative z-10 mt-2 grid gap-1.5">
+            {soldOut ? (
+              <Button disabled className="w-full">
+                Sold out
+              </Button>
+            ) : needsChoice ? (
+              <Button className="w-full" onClick={open} disabled={!open} href={open ? undefined : product.href}>
+                Choose options
+              </Button>
+            ) : (
+              <Button variant="primary" icon="shopping-cart" className="w-full" loading={status.state === "busy"} onClick={add}>
+                {status.state === "added" ? "Added" : addLabel}
+              </Button>
+            )}
+            <p aria-live="polite" className="text-xs empty:hidden">
+              {status.state === "failed" ? <span className="text-destructive">{status.error}</span> : null}
+              {status.state === "added" ? <span className="sr-only">{product.name} added to your cart.</span> : null}
+            </p>
+          </div>
+        ) : null}
+      </div>
+    </article>
+  );
+}
+
+/**
+ * A promotion: a tall picture with a kicker, a title and an action on a
+ * panel over its foot. The panel is the theme's background, so the words
+ * read on any picture in any theme.
+ */
+export function PromoTile({ item, large = false, onOpen, className }) {
+  const action = item.action ?? (item.href || onOpen ? { label: item.actionLabel ?? "Shop now", href: item.href } : null);
+  const open = action?.onClick ?? (onOpen ? () => onOpen(item) : undefined);
+  return (
+    <article
+      className={cx(
+        "relative flex min-w-0 overflow-hidden rounded-lg border border-border bg-muted",
+        "has-[a[data-stretch]:focus-visible,button[data-stretch]:focus-visible]:ring-2 has-[a[data-stretch]:focus-visible,button[data-stretch]:focus-visible]:ring-ring",
+        large ? "min-h-80 lg:min-h-full" : "min-h-80",
+        className,
+      )}
+    >
+      <FeatureMedia item={item} />
+      <div className={cx("relative mt-auto w-full p-3", large && "sm:p-5")}>
+        <div className="grid gap-1 rounded-md bg-background/90 p-4 text-foreground shadow-sm backdrop-blur-sm">
+          {item.kicker ? <Kicker>{item.kicker}</Kicker> : null}
+          <h3 className={cx("font-semibold leading-tight", large ? "text-xl sm:text-2xl" : "text-lg")}>{item.title ?? item.name}</h3>
+          {item.body ? <p className="text-sm text-muted-foreground">{item.body}</p> : null}
+          {action ? (
+            <p className="mt-1 text-sm">
+              {action.href ? (
+                <Button variant="link" href={action.href} data-stretch className={STRETCH}>
+                  {action.label}
+                </Button>
+              ) : open ? (
+                <Button variant="link" onClick={open} data-stretch className={STRETCH}>
+                  {action.label}
+                </Button>
+              ) : null}
+            </p>
+          ) : null}
+        </div>
+      </div>
+    </article>
+  );
+}
+
+// The tile's picture, or a muted looping video for a feature. The video
+// never plays for a reader who asks for reduced motion, and has a pause.
+function FeatureMedia({ item }) {
+  const [paused, setPaused] = useState(false);
+  const [calm, setCalm] = useState(true);
+  useEffect(() => {
+    if (!item.video || typeof matchMedia !== "function") return;
+    const mq = matchMedia("(prefers-reduced-motion: reduce)");
+    setCalm(mq.matches);
+    const on = () => setCalm(mq.matches);
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, [item.video]);
+
+  if (item.video) {
+    const still = calm || paused;
+    return (
+      <>
+        {/* A picture of motion, not content: muted, no controls of its own. */}
+        <video
+          key={still ? "still" : "moving"}
+          src={item.video}
+          poster={item.poster ?? item.image}
+          muted
+          loop
+          playsInline
+          autoPlay={!still}
+          aria-hidden="true"
+          className="absolute inset-0 size-full object-cover"
+        />
+        {!calm ? (
+          <Toggle
+            icon={paused ? "play" : "pause"}
+            label={paused ? "Play the video" : "Pause the video"}
+            pressed={paused}
+            onPressedChange={setPaused}
+            className="absolute start-3 top-3 z-10"
+          />
+        ) : null}
+      </>
+    );
+  }
+  return (
+    <div className="absolute inset-0">
+      <Image src={item.image} alt={item.alt ?? ""} ratio="square" rounded="none" className="size-full" />
+    </div>
+  );
+}

package/registry/blocks/product-grid/product-grid.jsx

@@ -0,0 +1,235 @@
+"use client";
+
+import { isValidElement, useId, useMemo, useState } from "react";
+import { Button, Empty, Notice, Select, Skeleton, cx } from "../../ui";
+import { ProductCard, PromoTile } from "./product-card";
+
+// Products (or promotions) as cards in a grid, with facet filters, a sort
+// and a count over it, and an optional lead tile that takes a double
+// cell. Filtering and sorting happen here over `products`, or — with
+// `manual` — in your loader, the block only reporting what was picked.
+
+const SORTS = {
+  featured: { label: "Featured", compare: null },
+  "price-asc": { label: "Price: low to high", compare: (a, b) => (a.price ?? 0) - (b.price ?? 0) },
+  "price-desc": { label: "Price: high to low", compare: (a, b) => (b.price ?? 0) - (a.price ?? 0) },
+  rating: { label: "Top rated", compare: (a, b) => (b.rating ?? 0) - (a.rating ?? 0) },
+  newest: {
+    label: "Newest",
+    compare: (a, b) => String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")),
+  },
+};
+const DEFAULT_SORTS = ["featured", "price-asc", "price-desc", "rating"];
+
+function sortsOf(sort) {
+  if (!sort) return [];
+  const list = Array.isArray(sort) ? sort : DEFAULT_SORTS;
+  return list
+    .map((s) => (typeof s === "string" ? { value: s, ...SORTS[s] } : { ...SORTS[s.value], ...s }))
+    .filter((s) => s.value && s.label);
+}
+
+const optionsOf = (filter) =>
+  (filter.options ?? []).filter((o) => o != null).map((o) => (typeof o === "object" ? o : { value: String(o), label: String(o) }));
+
+/** Does `product` carry `value` under `key`? Looked for in the product's
+ *  own field (a string or a list), in `facets[key]`, and in the values of
+ *  its option with that key — so a size filter matches the sizes a
+ *  product is sold in. */
+export function productMatches(product, key, value) {
+  const found = [];
+  const push = (v) => (Array.isArray(v) ? found.push(...v) : v != null && found.push(v));
+  push(product?.[key]);
+  push(product?.facets?.[key]);
+  const option = product?.options?.find((o) => o.key === key);
+  for (const v of option?.values ?? []) if (!(typeof v === "object" && v?.disabled)) push(typeof v === "object" ? v.value : v);
+  return found.some((v) => String(typeof v === "object" ? v.value : v) === String(value));
+}
+
+const COLS = {
+  product: {
+    2: "grid-cols-2",
+    3: "grid-cols-2 lg:grid-cols-3",
+    4: "grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+  },
+  promo: {
+    2: "grid-cols-1 sm:grid-cols-2",
+    3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+    4: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-4",
+  },
+};
+
+function LoadingCards({ count, promo, cols }) {
+  return (
+    <div aria-busy="true" aria-label="Loading products" className={cx("grid gap-3 sm:gap-4", cols)}>
+      {Array.from({ length: count }, (_, i) =>
+        promo ? (
+          <Skeleton key={i} shape="rect" className="h-80 w-full" />
+        ) : (
+          <div key={i} className="grid gap-2 overflow-hidden rounded-lg border border-border bg-card pb-4">
+            <Skeleton shape="rect" className="aspect-square w-full" />
+            <Skeleton className="mx-4 w-1/3" />
+            <Skeleton className="mx-4 w-3/4" />
+            <Skeleton className="mx-4 w-1/4" />
+          </div>
+        ),
+      )}
+    </div>
+  );
+}
+
+export function ProductGrid({
+  products,
+  card = "product",
+  columns,
+  filters,
+  sort,
+  defaultSort,
+  manual = false,
+  total,
+  onQueryChange,
+  feature,
+  onOpen,
+  onAddToCart,
+  onFavorite,
+  favorites,
+  currency = "USD",
+  locale,
+  addLabel,
+  countLabel = (n) => `${n.toLocaleString(locale)} ${n === 1 ? "product" : "products"}`,
+  loading = false,
+  error,
+  onRetry,
+  emptyTitle = "No products yet",
+  emptyBody,
+  label = "Products",
+  className,
+}) {
+  const id = useId();
+  const promo = card === "promo";
+  const sorts = sortsOf(sort);
+  const facetList = (filters ?? []).filter(Boolean);
+  const [picked, setPicked] = useState(() => Object.fromEntries(facetList.map((f) => [f.key, f.value ?? ""])));
+  const [order, setOrder] = useState(defaultSort ?? sorts[0]?.value ?? "featured");
+  const favSet = new Set(favorites ?? []);
+  const active = Object.values(picked).some(Boolean);
+
+  const shown = useMemo(() => {
+    let list = (products ?? []).filter(Boolean);
+    if (manual) return list;
+    for (const [key, value] of Object.entries(picked)) if (value) list = list.filter((p) => productMatches(p, key, value));
+    const cmp = sorts.find((s) => s.value === order)?.compare;
+    return cmp ? [...list].sort(cmp) : list;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [products, picked, order, manual, sort]);
+
+  function change(nextPicked, nextOrder) {
+    setPicked(nextPicked);
+    setOrder(nextOrder);
+    onQueryChange?.({ filters: Object.fromEntries(Object.entries(nextPicked).filter(([, v]) => v)), sort: nextOrder });
+  }
+  const clear = () => change(Object.fromEntries(facetList.map((f) => [f.key, ""])), order);
+
+  const n = columns ?? (promo ? 3 : 4);
+  const cols = (COLS[promo ? "promo" : "product"][n] ?? COLS.product[4]);
+  const count = manual && typeof total === "number" ? total : shown.length;
+
+  const toolbar =
+    facetList.length || sorts.length ? (
+      <div className="flex flex-wrap items-end justify-between gap-3">
+        {facetList.length ? (
+          <div role="group" aria-label="Filters" className="grid w-full grid-cols-2 gap-2 sm:flex sm:w-auto sm:flex-wrap">
+            {facetList.map((f) => (
+              <div key={f.key} className="min-w-0 sm:w-40">
+                <Select aria-label={f.label} value={picked[f.key] ?? ""} onChange={(e) => change({ ...picked, [f.key]: e.target.value }, order)}>
+                  <option value="">{f.all ?? `All ${String(f.label).toLowerCase()}`}</option>
+                  {optionsOf(f).map((o) => (
+                    <option key={o.value} value={o.value}>
+                      {o.label}
+                    </option>
+                  ))}
+                </Select>
+              </div>
+            ))}
+            {active ? (
+              <Button variant="quiet" icon="x" onClick={clear}>
+                Clear
+              </Button>
+            ) : null}
+          </div>
+        ) : null}
+        <div className="flex w-full items-center justify-between gap-3 sm:ml-auto sm:w-auto">
+          <p id={`${id}-count`} data-nums aria-live="polite" className="text-sm text-muted-foreground whitespace-nowrap">
+            {loading ? " " : countLabel(count)}
+          </p>
+          {sorts.length ? (
+            <div className="w-44 shrink-0">
+              <Select
+                aria-label="Sort by"
+                value={order}
+                onChange={(e) => change(picked, e.target.value)}
+                options={sorts.map((s) => ({ value: s.value, label: s.label }))}
+              />
+            </div>
+          ) : null}
+        </div>
+      </div>
+    ) : null;
+
+  let body;
+  if (loading) body = <LoadingCards count={promo ? n : n * 2} promo={promo} cols={cols} />;
+  else if (error) {
+    body = (
+      <Notice tone="danger" title="The products did not load" action={onRetry ? <Button size="sm" onClick={onRetry}>Try again</Button> : null}>
+        {typeof error === "string" ? error : null}
+      </Notice>
+    );
+  } else if (shown.length === 0 && !feature) {
+    body = active ? (
+      <Empty
+        icon="filter"
+        title="Nothing matches these filters"
+        body="Take one off, or clear them all."
+        action={<Button onClick={clear}>Clear filters</Button>}
+      />
+    ) : (
+      <Empty icon="package" title={emptyTitle} body={emptyBody} />
+    );
+  } else {
+    const lead = feature ? (
+      <li key="feature" className={cx("min-w-0", promo ? "sm:col-span-2 sm:row-span-2" : "col-span-2 lg:row-span-2")}>
+        {isValidElement(feature) ? feature : <PromoTile item={feature} large onOpen={feature.onOpen} className="h-full" />}
+      </li>
+    ) : null;
+    body = (
+      <ul aria-describedby={toolbar ? `${id}-count` : undefined} className={cx("grid gap-3 sm:gap-4", cols)}>
+        {lead}
+        {shown.map((p, i) => (
+          <li key={p.id ?? i} className="min-w-0">
+            {promo ? (
+              <PromoTile item={p} onOpen={onOpen} className="h-full" />
+            ) : (
+              <ProductCard
+                product={p}
+                onOpen={onOpen}
+                onAddToCart={onAddToCart}
+                onFavorite={onFavorite}
+                favorite={favSet.has(p.id)}
+                currency={currency}
+                locale={locale}
+                addLabel={addLabel}
+              />
+            )}
+          </li>
+        ))}
+      </ul>
+    );
+  }
+
+  return (
+    <section aria-label={label} className={cx("grid min-w-0 gap-4", className)}>
+      {toolbar}
+      {body}
+    </section>
+  );
+}

package/registry/blocks/record-form/README.md

@@ -0,0 +1,196 @@
+# RecordForm
+
+One record's fields, described as data and drawn with the kit: a label, a
+control, help under it, an error in its place. The fields are grouped into
+titled sections. The form holds the draft, checks each field when you
+leave it (and again as you fix it), and saves the whole record through
+`onSave`. A save that fails keeps every edit on screen and says why — over
+the form, and under each field the server refused.
+
+```jsx
+import { RecordForm } from "../components/blocks/record-form";   // a Makersclaw app ("./blocks/record-form" from components/)
+import { RecordForm } from "@/components/makersclaw/blocks/record-form";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the record in the server surface (README §4).
+
+## The data
+
+`values` is the record: `{ name: "…", price: 189, tags: ["gift"] }`. Each
+field reads and writes `values[field.name]`.
+
+A field:
+
+- `name` — the key in `values` (required, unique in the form).
+- `label` — what it is called.
+- `type` — how it is entered (default `"text"`):
+  - `text` · `email` · `url` · `tel` · `number` — an Input. `icon`,
+    `prefix` ("$") or `suffix` ("kg") make it an InputGroup. A number is
+    sent as a number (empty → `null`).
+  - `password` — a PasswordInput with show/hide.
+  - `textarea` — `rows` (4).
+  - `select` — a native Select over `options`; `placeholder` is the empty
+    first choice.
+  - `combobox` — a searchable Combobox over `options` (with `description`
+    per option); `multiple: true` holds an array.
+  - `tags` — a Combobox that holds an array and takes new words.
+  - `radio` — a RadioGroup; `orientation: "horizontal"` for a short row.
+  - `choice-cards` — the RadioGroup's card look: each option
+    `{ value, label, description?, price?, per?, badge? }` — a plan, a
+    package, a mode.
+  - `checkbox` — one box that must be ticked when `required` ("I agree…");
+    `description` under its label. Holds `true`/`false`.
+  - `checkboxes` — several boxes over `options`; holds an array of values.
+  - `switch` — an on/off with `description`; holds `true`/`false`.
+  - `date` — a DatePicker; the value is `"YYYY-MM-DD"`. `min`, `max`,
+    `captionLayout: "dropdown"` for a birth date.
+  - `time` — a TimeInput; `"HH:MM"`.
+  - `rating` — Rating stars as an input; `max` (5). Holds a whole number.
+  - `photo` — an Avatar with Upload and Remove. `nameFrom(values)` gives
+    the initials shown with no picture. Holds a URL string, or
+    `{ src, file, name }` after a pick: upload `file` in `onSave`.
+  - `images` — a row of thumbnails, each removable, and Add while under
+    `maxItems`. Holds an array of URL strings or `{ src, file, name }`.
+  - `static` — the value as text, not editable ("Verified"); `format(value,
+    values)` to word it.
+- `required` — it must hold something (a ticked box, a chosen option).
+- `options` — for the choosing types: `[{ value, label, description?,
+  disabled? }]` or plain strings.
+- `help` — the muted line under it (hidden while an error shows).
+- `placeholder`, `autoComplete`, `min`, `max`, `step`, `disabled`,
+  `readOnly` — as the control's own.
+- `width` — `"full"` spans both columns; `"half"` keeps a wide type in one.
+  Text areas, choices, boxes, switches, a photo and images are full by
+  default.
+- `when(values)` — shown only while it returns true; a hidden field is not
+  checked and not sent.
+- `defaultValue` — used when `values` has none.
+
+Validation, first broken rule wins, one message per field:
+
+- `required` (`requiredMessage` to word it);
+- the type's own shape: an email, a full `https://` address, a number
+  within `min`/`max`;
+- `minLength`, `maxLength`;
+- `pattern` — a regular expression the whole text must match, with
+  `patternMessage`;
+- `matches` — the name of another field this one must equal (a confirm),
+  with `matchMessage`;
+- `maxItems` — for arrays (tags, images, checkboxes);
+- `validate(value, values)` — return a message, or nothing when fine.
+
+## Props
+
+- `fields` — the fields, one untitled section. Or:
+- `sections` — `[{ title?, description?, columns?, fields }]`: titled
+  groups in order.
+- `values` — the record as it stands. Pass a different record and the form
+  starts over from it (and forgets unsaved edits).
+- `onSave(values, { changed })` — save the record. `values` is every
+  shown field, text trimmed, numbers as numbers; `changed` names the keys
+  that differ from `values`. Return `{ ok: true }`, or `{ ok: false,
+  error?, errors? }` where `errors` is `{ fieldName: "message" }` — each
+  shows under its field and the first one is focused. A throw counts as
+  failed. In a Makersclaw app it is one line over `updateRow`:
+  `onSave={(v) => updateRow({ source: "public.products", id: p.id, patch: v })}`.
+- `container` — `"card"` (default: a Card with `title` and `description`)
+  · `"page"` (no box: a page heading, then the sections) · `"dialog"` (a
+  centred Sheet; on a phone a bottom sheet). A dialog needs `open` and
+  `onClose`; it closes on a good save, and opens on the record as it
+  stands, never on last time's edits.
+- `layout` — `"stacked"` (default: each section's title over its fields)
+  or `"split"` (the title and description on the left, the fields on the
+  right, a rule between sections, from 768px up). A dialog is always
+  stacked.
+- `columns` — `2` (default: two columns from 640px) or `1`. A dialog is
+  one column.
+- `title`, `description` — the card's, the page's, or the dialog's.
+- `onCancel()` — shows Cancel; it drops the edits first. Without it, a
+  Discard button shows while there are edits.
+- `onDelete()` — shows a danger button at the start of the footer (not in
+  a dialog) that asks first. Return `{ ok }` like `onSave`.
+- `confirmDelete` — the ask: `{ title?, body?, confirmLabel?,
+  consequences?, requireText?, acknowledge? }` (the kit Confirm's).
+- `deleteLabel` — `"Delete"`.
+- `onChange(values)` — every edit, for a live preview beside the form.
+- `submitLabel` (`"Save changes"`) · `cancelLabel` (`"Cancel"`) ·
+  `savedLabel` (`"Saved"`, shown for three seconds after a good save).
+- `requireChanges` — `true` (default): Save waits for an edit. Pass
+  `false` for a form that creates a record.
+- `loading` — skeleton fields while the record loads.
+- `error` — the record could not be loaded: a Notice in place of the
+  fields; `onRetry` adds "Try again".
+- `emptyLabel` — shown when there are no fields.
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/ProductEditor.jsx — client
+"use client";
+import { updateRow, deleteRow } from "../lib/actions";
+import { RecordForm } from "./blocks/record-form";
+
+const FIELDS = [
+  { name: "name", label: "Product name", required: true },
+  { name: "price", label: "Price", type: "number", prefix: "$", min: 0, required: true },
+  { name: "category", label: "Category", type: "select", options: ["Outerwear", "Tops", "Footwear"] },
+  { name: "launch", label: "Launch date", type: "date" },
+  { name: "details", label: "Details", type: "textarea" },
+];
+
+export default function ProductEditor({ product }) {
+  return (
+    <RecordForm
+      title="Edit product"
+      fields={FIELDS}
+      values={product}
+      onSave={(values) => updateRow({ source: "public.products", id: product.id, patch: values })}
+      onDelete={() => deleteRow({ source: "public.products", id: product.id })}
+      deleteLabel="Remove product"
+    />
+  );
+}
+```
+
+In a dialog, from a list:
+
+```jsx
+const [editing, setEditing] = useState(null);
+
+<RecordForm
+  container="dialog"
+  open={Boolean(editing)}
+  onClose={() => setEditing(null)}
+  title="Edit member"
+  values={editing ?? {}}
+  sections={[
+    { title: "Profile", fields: [{ name: "photo", label: "Photo", type: "photo" }, { name: "name", label: "Name", required: true }] },
+    { title: "Access", fields: [{ name: "role", label: "Role", type: "radio", options: ["Admin", "Member", "Viewer"] }] },
+  ]}
+  onSave={async (values) => {
+    const res = await updateRow({ source: "public.members", id: editing.id, patch: values });
+    return res.ok ? res : { ok: false, errors: res.error?.includes("email") ? { email: "Already in use." } : undefined, error: res.error };
+  }}
+/>
+```
+
+## What it will not do
+
+- Upload files: a picked photo or image arrives in `onSave` as
+  `{ src, file }` — upload `file`, store the URL.
+- Save field by field: it saves the record with one button. Settings that
+  each save when flipped are `settings-list`.
+- Sign in, sign up or change a password with rules beside it: that is
+  `auth-form`.
+- Lay out a field by hand: a field it cannot draw is your own form in
+  `components/`, built from the kit's `Field` and controls.
+
+A form 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 record-form` restores them.
+
+## Credits
+
+Shapes from Creative Tim UI (https://github.com/creativetimofficial/ui, MIT) and blocks.so (https://github.com/ephraimduncan/blocks, MIT); this is a rewrite on the Makersclaw kit.

package/registry/blocks/record-form/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "record-form",
+  "title": "RecordForm",
+  "description": "Edit or create one record from a list of fields given as data (type, label, required, options, help, validation), grouped into titled sections — text, email, number, password, select, combobox, tags, radio, choice cards with prices, checkboxes, switch, date, time, rating, a photo and a row of images. It checks as you type, saves through an async onSave that answers { ok } or per-field errors shown under each field, and sits in a card, on a page (sections split title-left) or in a dialog.",
+  "useWhen": "A screen edits one record's fields: a profile, a product, a team member, account details, a sign-up or application form, a settings page of fields with one Save. Not for a list of records (data-table), for toggles that each save on their own (settings-list), or for sign-in (auth-form).",
+  "tags": ["form", "record", "edit", "create", "fields", "sections", "validation", "save", "profile", "product", "dialog", "settings", "crud", "choice", "plan"],
+  "exports": ["RecordForm"],
+  "files": ["index.js", "record-form.jsx", "record-fields.jsx", "rules.js"],
+  "requires": []
+}