makersclaw 0.2.0 → 0.3.0

package/registry/blocks/product-detail/product-options.jsx

@@ -0,0 +1,144 @@
+"use client";
+
+import { useId } from "react";
+import { Badge, ButtonGroup, Field, IconButton, RadioGroup, Select, Swatch, ToggleGroup, cx } from "../../ui";
+import { formatPrice, labelOf, valuesOf } from "./price";
+
+// One option's control. How it is drawn follows the values unless the
+// option says (`display`):
+//   swatches  values carry a `color` → colour squares, the name in the heading
+//   buttons   up to 6 short values → a segmented row (sizes)
+//   select    more, or longer, values → the native select
+//   plans     values carry a `price` or a `description` → a card per value
+function displayOf(option, values) {
+  if (option.display) return option.display;
+  if (values.some((v) => v.color)) return "swatches";
+  if (values.some((v) => typeof v.price === "number" || v.description)) return "plans";
+  const long = values.reduce((n, v) => n + labelOf(v).length, 0) > 30;
+  return values.length <= 6 && !long ? "buttons" : "select";
+}
+
+export function OptionPicker({ option, value, onChange, currency, locale }) {
+  const id = useId();
+  const values = valuesOf(option);
+  if (values.length === 0) return null;
+  const display = displayOf(option, values);
+  const current = values.find((v) => v.value === value);
+  const heading = option.label ?? option.key;
+
+  if (display === "select") {
+    return (
+      <Field id={id} label={heading}>
+        <Select id={id} value={value ?? ""} onChange={(e) => onChange(e.target.value)}>
+          {values.map((v) => (
+            <option key={v.value} value={v.value} disabled={v.disabled}>
+              {labelOf(v)}
+              {v.disabled ? " — sold out" : ""}
+            </option>
+          ))}
+        </Select>
+      </Field>
+    );
+  }
+
+  if (display === "plans") {
+    return (
+      <div className="grid gap-2">
+        <p id={`${id}-l`} className="text-sm font-medium text-foreground">
+          {heading}
+        </p>
+        <RadioGroup
+          aria-labelledby={`${id}-l`}
+          variant="card"
+          value={value ?? undefined}
+          onChange={onChange}
+          options={values.map((v) => ({
+            value: v.value,
+            disabled: v.disabled,
+            description: v.description,
+            label: (
+              <span className="flex flex-wrap items-baseline justify-between gap-x-3 gap-y-1">
+                <span className="inline-flex flex-wrap items-center gap-2">
+                  {labelOf(v)}
+                  {v.badge ? (
+                    <Badge tone="primary" variant="soft">
+                      {v.badge}
+                    </Badge>
+                  ) : null}
+                </span>
+                {typeof v.price === "number" ? (
+                  <span data-nums className="font-semibold">
+                    {formatPrice(v.price, currency, locale)}
+                    {v.per ? <span className="text-xs font-normal text-muted-foreground"> {v.per}</span> : null}
+                  </span>
+                ) : null}
+              </span>
+            ),
+          }))}
+        />
+      </div>
+    );
+  }
+
+  const swatches = display === "swatches";
+  return (
+    <div className="grid gap-2">
+      <p id={`${id}-l`} className="text-sm font-medium text-foreground">
+        {heading}
+        {swatches && current ? <span className="font-normal text-muted-foreground">: {labelOf(current)}</span> : null}
+      </p>
+      <ToggleGroup
+        aria-label={heading}
+        value={value ?? undefined}
+        onChange={onChange}
+        className={swatches ? "flex-wrap" : undefined}
+        items={values.map((v) => ({
+          value: v.value,
+          disabled: v.disabled,
+          label: swatches ? (
+            <Swatch color={v.color} label={`${labelOf(v)}${v.disabled ? ", sold out" : ""}`} />
+          ) : (
+            <span className={cx(v.disabled && "line-through")}>{labelOf(v)}</span>
+          ),
+        }))}
+      />
+    </div>
+  );
+}
+
+/** − n + as one attached control. The count is announced as it changes. */
+export function QuantityControl({ value, onChange, min = 1, max = 10, disabled, label = "Quantity" }) {
+  const id = useId();
+  return (
+    <div className="grid gap-2">
+      <p id={id} className="text-sm font-medium text-foreground">
+        {label}
+      </p>
+      <ButtonGroup aria-labelledby={id} className="w-fit">
+        <IconButton
+          icon="minus"
+          label="Decrease quantity"
+          variant="secondary"
+          disabled={disabled || value <= min}
+          onClick={() => onChange(Math.max(min, value - 1))}
+        />
+        <output
+          aria-live="polite"
+          aria-label={`${label} ${value}`}
+          data-nums
+          className="grid min-w-12 place-items-center border border-border bg-background px-2 text-sm font-medium text-foreground"
+        >
+          {value}
+        </output>
+        <IconButton
+          icon="plus"
+          label="Increase quantity"
+          variant="secondary"
+          disabled={disabled || value >= max}
+          onClick={() => onChange(Math.min(max, value + 1))}
+        />
+      </ButtonGroup>
+      {value >= max && max > min ? <p className="text-xs text-muted-foreground">{max} is the most you can add at once.</p> : null}
+    </div>
+  );
+}

package/registry/blocks/product-grid/README.md

@@ -0,0 +1,162 @@
+# Product grid
+
+Products as cards in a grid — picture, badge, heart, brand, name, stars,
+price — with a quick **Add to cart** on each. Over the grid: facet filters,
+a sort and a live count. A lead tile (a picture or a muted looping video)
+can take a double cell, and `card="promo"` turns the cards into collection
+tiles ("New", "Sale"). The add goes out through `onAddToCart(line)`; while
+it runs the card's button spins, when it fails the card says why.
+
+```jsx
+import { ProductGrid } from "../components/blocks/product-grid";   // a Makersclaw app ("./blocks/product-grid" from components/)
+import { ProductGrid } from "@/components/makersclaw/blocks/product-grid";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the rows in the server surface (README §4). It requires
+`product-detail` (added with it): the cards share its price and cart line.
+
+## The data
+
+`products` are the same objects `ProductDetail` takes (see its README):
+`{ id, name, price }` required; `compareAt`, `currency`, `image` (or
+`images`), `brand`, `badge`, `rating`, `reviews`, `href`, `available:
+false` (sold out), `options` all draw on the card when present. A product
+with an option that has more than one value cannot be added blind: its
+button says **Choose options** and opens it (`onOpen`, else its `href`).
+
+Filters look for a value in three places on each product: its own field
+(`product.category`, a string or a list), `product.facets[key]`, and the
+values of its option with that key (so a **size** filter keeps what is
+sold in that size, skipping sold-out sizes).
+
+With `card="promo"` each item is a tile: `{ id, title, kicker?, body?,
+image, href?, actionLabel?, action?: { label, href?, onClick? } }`.
+
+### The cart line
+
+`onAddToCart` gets one line, the shape the `cart` block takes as an item:
+`{ id, key, name, price, compareAt?, currency, image, href?, quantity: 1,
+selected: {}, variant: "" }`. `key` is the product id (plus its choices on
+a product page), so adding the same thing twice is one row — merge
+quantities by `key`.
+
+## Props
+
+- `products` — the rows. Pass `useFixture(rows, SAMPLE).rows` to show
+  example cards before there is data.
+- `onAddToCart(line)` — return `{ ok: true }` or `{ ok: false, error }` (a
+  throw counts as failed). Without it the cards have no button.
+- `onOpen(product)` — the card becomes a button that opens the product (a
+  `Sheet`, a route). A product's own `href` makes it a link instead.
+- `onFavorite(product, next)` — a heart on each picture; flips at once,
+  flips back with the error when the save fails. `favorites` — the ids
+  saved now.
+- `filters` — `[{ key, label, options, all?, value? }]`: one select per
+  facet, first choice "All …" (`all` renames it, `value` starts it set).
+  `options` are strings or `{ value, label }`.
+- `sort` — `true` for Featured, price up, price down, top rated; or a
+  list of those keys (`"featured"`, `"price-asc"`, `"price-desc"`,
+  `"rating"`, `"newest"` by `createdAt`) and your own `{ value, label,
+  compare(a, b) }`. `defaultSort` — the key it starts on.
+- `manual` — the loader filters and sorts (a big catalogue): the block
+  shows `products` as they come, reports each change through
+  `onQueryChange({ filters, sort })`, and counts `total`.
+- `feature` — the lead tile, `{ kicker, title, body?, image | video +
+  poster, href | onOpen, actionLabel }`, or any node. Two cells wide (and
+  two tall from lg up). A video is muted and looping, has a pause, and
+  never plays for a reader who asks for reduced motion.
+- `card` — `"product"` (default) or `"promo"`.
+- `columns` — how many from lg up: `2` · `3` · `4` (default 4 for
+  products, 3 for tiles). A phone shows two product cards a row, one tile.
+- `currency` (`"USD"`) · `locale` — for prices and counts.
+- `countLabel(n)` — `"12 products"` by default. `addLabel` — the button's
+  words.
+- `loading` — skeleton cards. `error` (a string) with `onRetry` — "Try
+  again". `emptyTitle` · `emptyBody` — when there are no products; when
+  filters hide them all it offers **Clear filters**.
+- `label` — what the grid is called to a screen reader.
+- `className` — layout around it (width, margin). Never colour.
+
+`ProductCard({ product, onAddToCart, onOpen, onFavorite, favorite })` and
+`PromoTile({ item, large })` are exported for a row of your own.
+
+## Example
+
+```jsx
+// surfaces/shop.jsx — server: load, hand over
+import { loadRows } from "../lib/data";
+import Shop from "../components/Shop";
+
+export default async function ShopSurface() {
+  const { rows, error } = await loadRows({ source: "public.products", orderBy: "created_at desc" });
+  return <Shop products={rows} error={error} />;
+}
+```
+
+```jsx
+// components/Shop.jsx — client: the grid and the cart write
+"use client";
+import { useRouter } from "next/navigation";
+import { insertRow } from "../lib/actions";
+import { ProductGrid } from "./blocks/product-grid";
+
+export default function Shop({ products, error }) {
+  const router = useRouter();
+  return (
+    <ProductGrid
+      products={products}
+      error={error}
+      onRetry={() => router.refresh()}
+      filters={[
+        { key: "category", label: "Category", options: ["Shirts", "Sweaters", "Jackets"] },
+        { key: "size", label: "Size", options: ["S", "M", "L", "XL"] },
+      ]}
+      sort
+      onAddToCart={(line) =>
+        insertRow({ source: "public.cart_items", values: { product_id: line.id, line_key: line.key, quantity: 1 }, detail: line.name })
+      }
+      label="Shop"
+    />
+  );
+}
+```
+
+Collection tiles, and a lead picture beside four products:
+
+```jsx
+<ProductGrid
+  card="promo"
+  products={[
+    { id: "new", kicker: "New", title: "The autumn edit", image: "/tiles/autumn.jpg", href: "/shop/new" },
+    { id: "sale", kicker: "Sale", title: "Summer linen", image: "/tiles/linen.jpg", href: "/shop/sale" },
+  ]}
+  label="Collections"
+/>
+
+<ProductGrid
+  products={skincare}
+  feature={{ kicker: "Skincare", title: "The morning routine", image: "/hero.jpg", href: "/routine", actionLabel: "Shop the routine" }}
+  onAddToCart={addToCart}
+/>
+```
+
+## What it will not do
+
+- Choose options on a card: that is the product page's job
+  (`product-detail`); the card sends the customer there.
+- Page through a catalogue: pass a page of rows with `manual` and put the
+  kit's `Pagination` under it.
+- Load a third-party player: a lead video is a plain `<video>` file, never
+  a YouTube embed or script.
+- Colour itself: the tiles' words sit on the theme's background, so any
+  picture reads in any theme.
+
+A catalogue it cannot be is your own component in `components/`, built
+from the kit (and `ProductCard`) — not an edit to this block. Its files
+are fixed: `npm run check` refuses a change, and `makersclaw add
+product-grid` restores them.
+
+## Credits
+
+Ported from Creative Tim UI (https://github.com/creativetimofficial/ui), MIT — a rewrite on the Makersclaw kit, none of its code, copy or pictures.

package/registry/blocks/product-grid/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "product-grid",
+  "title": "Product grid",
+  "description": "Products as cards in a grid: picture, badge, favourite heart, brand, name, star rating, price with the old one struck through, and a quick add to cart through an async callback that may fail (\"Choose options\" when the product has sizes or colours). Facet filters as selects that also match a product's option values, a sort, a live count, a lead tile that takes a double cell (a picture or a muted looping video), and a promo card for collection tiles. Loading, error, empty and no-matches states; two columns on a phone.",
+  "useWhen": "A shop's catalogue, a collection page, related products under a product page, a row of promotions ('New', 'Sale'). Not for records to scan and act on in columns (data-table), one product's page (product-detail), or the cart (cart).",
+  "tags": ["products", "shop", "store", "ecommerce", "commerce", "catalogue", "catalog", "grid", "cards", "filter", "facets", "sort", "add to cart", "favourite", "collection", "promo", "listing", "plp"],
+  "exports": ["ProductGrid", "ProductCard", "PromoTile", "productMatches"],
+  "files": ["index.js", "product-grid.jsx", "product-card.jsx"],
+  "requires": ["product-detail"]
+}

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

@@ -0,0 +1,255 @@
+"use client";
+
+// The product grid with its data in memory — the gallery's and the smoke
+// test's surface. Not installed into apps: `makersclaw add product-grid`
+// lays the block's files only. Each layout it was ported from is one
+// choice in the switcher.
+import { useState } from "react";
+import { Field, Select, ToggleGroup } from "../components/ui";
+import { ProductGrid } from "../components/blocks/product-grid";
+
+const pic = (seed, w = 800, h = 800) => `https://picsum.photos/seed/${seed}/${w}/${h}`;
+
+const PRODUCTS = [
+  {
+    id: "cardigan",
+    brand: "Northfold",
+    name: "Cable-knit merino cardigan",
+    category: "sweaters",
+    material: "wool",
+    price: 240,
+    rating: 4.6,
+    reviews: 58,
+    badge: "Exclusive",
+    image: pic("mc-grid-cardigan"),
+    options: [{ key: "size", values: ["S", "M", "L"] }],
+    createdAt: "2026-08-02",
+  },
+  {
+    id: "oxford",
+    brand: "Harbor & Pine",
+    name: "Brushed cotton oxford shirt",
+    category: "shirts",
+    material: "cotton",
+    price: 72,
+    rating: 4.2,
+    reviews: 131,
+    image: pic("mc-grid-oxford"),
+    createdAt: "2026-06-11",
+  },
+  {
+    id: "trousers",
+    brand: "Northfold",
+    name: "Wool straight trousers",
+    category: "trousers",
+    material: "wool",
+    price: 165,
+    compareAt: 210,
+    rating: 4.8,
+    reviews: 44,
+    badge: "Sale",
+    image: pic("mc-grid-trousers"),
+    createdAt: "2026-05-20",
+  },
+  {
+    id: "crewneck",
+    brand: "Atelier Rue",
+    name: "Cashmere crewneck",
+    category: "sweaters",
+    material: "cashmere",
+    price: 310,
+    rating: 5,
+    reviews: 12,
+    badge: "New",
+    image: pic("mc-grid-crewneck"),
+    options: [{ key: "size", values: ["XS", "S", { value: "M", disabled: true }] }],
+    createdAt: "2026-09-10",
+  },
+  {
+    id: "overshirt",
+    brand: "Harbor & Pine",
+    name: "Linen overshirt",
+    category: "shirts",
+    material: "linen",
+    price: 98,
+    rating: 3.9,
+    reviews: 27,
+    image: pic("mc-grid-overshirt"),
+    createdAt: "2026-07-01",
+  },
+  {
+    id: "chore",
+    brand: "Kiln Street",
+    name: "Canvas chore jacket",
+    category: "jackets",
+    material: "cotton",
+    price: 185,
+    rating: 4.4,
+    reviews: 90,
+    available: false,
+    image: pic("mc-grid-chore"),
+    createdAt: "2026-04-18",
+  },
+  {
+    id: "silk-scarf",
+    brand: "Atelier Rue",
+    name: "Printed silk scarf",
+    category: "accessories",
+    material: "silk",
+    price: 60,
+    rating: 4.7,
+    reviews: 203,
+    image: pic("mc-grid-scarf"),
+    createdAt: "2026-08-28",
+  },
+  {
+    id: "field-jacket",
+    brand: "Northfold",
+    name: "Waxed field jacket",
+    category: "jackets",
+    material: "cotton",
+    price: 280,
+    rating: 4.5,
+    reviews: 66,
+    image: pic("mc-grid-field"),
+    options: [{ key: "size", values: ["M", "L", "XL"] }],
+    createdAt: "2026-03-30",
+  },
+];
+
+const FILTERS = [
+  { key: "category", label: "Category", all: "All categories", options: [{ value: "shirts", label: "Shirts" }, { value: "sweaters", label: "Sweaters" }, { value: "trousers", label: "Trousers" }, { value: "jackets", label: "Jackets" }, { value: "accessories", label: "Accessories" }] },
+  { key: "size", label: "Size", all: "All sizes", options: ["XS", "S", "M", "L", "XL"] },
+  { key: "material", label: "Material", all: "All materials", options: [{ value: "cotton", label: "Cotton" }, { value: "wool", label: "Wool" }, { value: "cashmere", label: "Cashmere" }, { value: "linen", label: "Linen" }, { value: "silk", label: "Silk" }] },
+];
+
+const COLLECTIONS = [
+  { id: "new", kicker: "New", title: "The autumn edit", image: pic("mc-tile-autumn", 800, 1000), href: "#new", actionLabel: "See what's new" },
+  { id: "sale", kicker: "Sale", title: "Last of the summer linen", image: pic("mc-tile-linen", 800, 1000), href: "#sale", actionLabel: "Shop the sale" },
+  { id: "half", kicker: "Half price", title: "Knitwear, one week only", image: pic("mc-tile-knit", 800, 1000), href: "#knit", actionLabel: "Shop knitwear" },
+];
+
+const SKINCARE = [
+  { id: "toner", name: "Balancing toner", price: 32, rating: 4.4, reviews: 212, image: pic("mc-skin-toner") },
+  { id: "serum", name: "Hydrating serum", price: 45, rating: 4.8, reviews: 540, badge: "Best seller", image: pic("mc-skin-serum") },
+  { id: "cream", name: "Daily moisturiser", price: 38, rating: 4.5, reviews: 318, image: pic("mc-skin-cream") },
+  { id: "balm", name: "Overnight lip balm", price: 16, compareAt: 20, rating: 4.1, reviews: 97, image: pic("mc-skin-balm") },
+];
+
+const HEADPHONES = [
+  { id: "hp-1", brand: "Loop Audio", name: "Over-ear headphones, noise cancelling", price: 299, rating: 4, reviews: 128, badge: "New", image: pic("mc-audio-1") },
+  { id: "hp-2", brand: "Loop Audio", name: "Wireless earbuds", price: 149, rating: 4.3, reviews: 402, image: pic("mc-audio-2") },
+  { id: "hp-3", brand: "Loop Audio", name: "Bookshelf speaker pair", price: 420, compareAt: 499, rating: 4.7, reviews: 61, image: pic("mc-audio-3") },
+];
+
+const VARIANTS = [
+  { value: "filters", label: "Filters, sort and count" },
+  { value: "tiles", label: "Collection tiles" },
+  { value: "promo", label: "Promotion beside products" },
+  { value: "spotlight", label: "Video spotlight" },
+  { value: "cards", label: "Product cards" },
+];
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export default function ProductGridDemo() {
+  const [variant, setVariant] = useState("filters");
+  const [state, setState] = useState("ready");
+  const [favorites, setFavorites] = useState(["oxford"]);
+  const [cart, setCart] = useState([]);
+  const failing = state === "fails";
+
+  async function addToCart(line) {
+    await wait(600);
+    if (failing) return { ok: false, error: "The cart did not answer." };
+    setCart((all) => {
+      const hit = all.find((l) => l.key === line.key);
+      return hit ? all.map((l) => (l.key === line.key ? { ...l, quantity: l.quantity + 1 } : l)) : [...all, line];
+    });
+    return { ok: true };
+  }
+  async function favorite(product, next) {
+    await wait(300);
+    if (failing) return { ok: false, error: "Favourites are not saving." };
+    setFavorites((all) => (next ? [...all, product.id] : all.filter((id) => id !== product.id)));
+    return { ok: true };
+  }
+  const open = () => {};
+
+  const common = {
+    loading: state === "loading",
+    error: state === "error" ? "The catalogue did not answer." : undefined,
+    onRetry: () => setState("ready"),
+    onAddToCart: addToCart,
+    onFavorite: favorite,
+    favorites,
+    onOpen: open,
+  };
+  const pick = (list) => (state === "empty" ? [] : list);
+  const count = cart.reduce((n, l) => n + l.quantity, 0);
+
+  let grid;
+  if (variant === "tiles") {
+    grid = <ProductGrid key="tiles" card="promo" products={pick(COLLECTIONS)} {...common} label="Collections" emptyTitle="No collections yet" />;
+  } else if (variant === "promo") {
+    grid = (
+      <ProductGrid
+        key="promo"
+        products={pick(SKINCARE)}
+        columns={4}
+        feature={{ kicker: "Skincare", title: "Glow, from plants up", body: "Four steps, morning and night.", image: pic("mc-skin-hero", 1200, 1200), href: "#skincare", actionLabel: "Shop the routine" }}
+        {...common}
+        label="Skincare"
+      />
+    );
+  } else if (variant === "spotlight") {
+    grid = (
+      <ProductGrid
+        key="spotlight"
+        products={pick(HEADPHONES)}
+        columns={3}
+        feature={{
+          kicker: "In the studio",
+          title: "Sound you can work in",
+          video: "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
+          poster: pic("mc-audio-hero", 1200, 900),
+          href: "#audio",
+          actionLabel: "See all audio",
+        }}
+        {...common}
+        label="Audio"
+      />
+    );
+  } else if (variant === "cards") {
+    grid = <ProductGrid key="cards" products={pick(HEADPHONES)} columns={3} {...common} label="Headphones" />;
+  } else {
+    grid = <ProductGrid key="filters" products={pick(PRODUCTS)} filters={FILTERS} sort={["featured", "price-asc", "price-desc", "rating", "newest"]} {...common} label="Menswear" />;
+  }
+
+  return (
+    <div className="grid gap-6">
+      <div className="flex flex-wrap items-end gap-3">
+        <Field id="pg-variant" label="Layout" className="w-full sm:w-64">
+          <Select id="pg-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: "ready", label: "Ready" },
+            { value: "fails", label: "Fails" },
+            { value: "loading", label: "Loading" },
+            { value: "error", label: "Error" },
+            { value: "empty", label: "Empty" },
+          ]}
+        />
+        <p data-nums className="text-sm text-muted-foreground sm:ml-auto">
+          Cart: {count} {count === 1 ? "item" : "items"}
+        </p>
+      </div>
+      {grid}
+    </div>
+  );
+}

package/registry/blocks/product-grid/index.js

@@ -0,0 +1,5 @@
+// The Product grid block — `makersclaw add product-grid`. Fixed: compose
+// it through its props (README.md beside this file); a catalogue it cannot
+// be is your own component in components/.
+export { ProductGrid, productMatches } from "./product-grid";
+export { ProductCard, PromoTile } from "./product-card";