makersclaw 0.2.0 → 0.3.0

package/registry/blocks/order-detail/README.md

@@ -0,0 +1,109 @@
+# OrderDetail
+
+One placed order on a page. The header says the order's number, its
+status and when it was placed, with an Invoice action. Under it: the items,
+where the order is going and who hears about it, a timeline from placed to
+delivered, and the totals with a Track order action.
+
+It only shows. The actions are the app's: links, or callbacks that may
+return `{ ok: false, error }` and have the reason shown under the button.
+
+```jsx
+import { OrderDetail } from "../components/blocks/order-detail";   // a Makersclaw app ("./blocks/order-detail" from components/)
+import { OrderDetail } from "@/components/makersclaw/blocks/order-detail";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the order in the server surface (README §4).
+
+## The data
+
+One order:
+
+```js
+{
+  number: "#10482",                 // or `id`
+  status: "Shipped",                // the badge's words
+  stage: "shipped",                 // the timeline stage it has reached
+  placedAt: "2026-09-18",           // a date or an ISO timestamp
+  estimatedDelivery: "2026-09-24",
+  items: [{ id, name, image, price, quantity, variant }],
+  address: ["Maya Chen", "18 Harbour Street", "Leith, Edinburgh EH6 6PU", "United Kingdom"],
+  contact: { email: "maya@northwind.co", phone: "+44 7700 900123" },
+  shipping: 0, tax: 21.4, discount: { code: "WELCOME10", amount: 18.4 },
+  currency: "GBP",
+  paidWith: "Visa ending 4242",
+  timeline: [{ key: "placed", label: "Order placed", date: "2026-09-18" }, …],
+}
+```
+
+- `items` use the line-item shape `cart` uses: `price` is one unit, in the
+  currency's major unit.
+- `address` is lines, or one string with line breaks.
+- `shipping` · `tax` — a number (0 shipping reads "Free") or words
+  ("Included"). Leave one out and its row is not drawn.
+- `subtotal` · `total` — worked out from the items and charges when left
+  out; pass them when the stored numbers are the truth.
+- `timeline` — the stages in order, `{ key, label, date?, note?, status? }`.
+  Default: Order placed → Confirmed → Shipped → Delivered (keys `placed`,
+  `confirmed`, `shipped`, `delivered`). Stages before `stage` are
+  complete, `stage` is current (complete when it is the last), later ones
+  pending; a stage's own `status` (`failed`, `skipped`…) wins. A
+  `status` of "Cancelled" marks the reached stage failed and the rest
+  skipped. A stage shows its `date`, or its `note`; the last pending one
+  shows the expected delivery.
+- `statusTone` — the badge's tone when the status word is not one it knows
+  (placed, confirmed, processing, shipped, in transit, delivered,
+  cancelled, refunded, returned).
+
+## Props
+
+- `order` — the order above. `null` (and not loading) shows "Order not
+  found".
+- `loading` — skeletons. `error` — a line under the header (the order
+  loaded but something did not), or above the not-found state.
+- `currency` — used when the order has no `currency`; default `"USD"`.
+  `locale` — for money and dates, default the reader's.
+- `onTrack()` or `trackHref` — Track order, in the summary. `trackLabel`
+  renames it.
+- `onInvoice()` or `invoiceHref` — Invoice, in the header.
+  `invoiceLabel` renames it.
+- `onEditContact()` — an Edit contact button under the contact details
+  (open your `Sheet`).
+- `emptyTitle` · `emptyBody` — the not-found state's words.
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/OrderPage.jsx — client
+"use client";
+import { OrderDetail } from "./blocks/order-detail";
+
+export default function OrderPage({ order, error }) {
+  return (
+    <OrderDetail
+      order={order}
+      error={error}
+      trackHref={order?.trackingUrl}
+      invoiceHref={order ? `/api/invoices/${order.id}` : undefined}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Change the order: cancelling, returning or editing items is your own
+  screen, reached from `onEditContact` or a button beside it.
+- Fetch tracking: pass `stage` and the stage dates in, or link out with
+  `trackHref`.
+- List orders: that is a `data-table`.
+
+An order page 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 order-detail` 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/order-detail/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "order-detail",
+  "title": "OrderDetail",
+  "description": "One placed order on a page: its number, status and date, the items, the delivery address and contact, a timeline from placed to delivered (Steps), and the totals, with Track order and Invoice actions. Loading, error and not-found states built in.",
+  "useWhen": "A buyer or an operator opens one order: \"where is my order\", an order confirmation page, a support view of a purchase. Not for a list of orders (data-table) or for a basket before paying (cart).",
+  "tags": ["order", "order detail", "purchase", "receipt", "tracking", "delivery", "shipping", "timeline", "status", "invoice", "ecommerce", "commerce", "shop", "store"],
+  "exports": ["OrderDetail"],
+  "files": ["index.js", "order-detail.jsx"],
+  "requires": []
+}

package/registry/blocks/order-detail/demo.jsx

@@ -0,0 +1,88 @@
+"use client";
+
+// OrderDetail with an order 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 { OrderDetail } from "../components/blocks/order-detail";
+
+const photo = (id) => `https://images.unsplash.com/${id}?w=320&h=320&fit=crop&auto=format&q=70`;
+
+const ORDER = {
+  number: "#10482",
+  status: "Shipped",
+  stage: "shipped",
+  placedAt: "2026-09-18",
+  estimatedDelivery: "2026-09-24",
+  currency: "GBP",
+  items: [
+    { id: "li_1", name: "Field jacket", image: photo("photo-1591047139829-d91aecb6caea"), price: 164, quantity: 1, variant: "Olive · M" },
+    { id: "li_2", name: "Merino crew socks", image: photo("photo-1586350977771-b3b0abd50c82"), price: 16, quantity: 2, variant: "Charcoal · 3 pack" },
+  ],
+  address: ["Maya Chen", "18 Harbour Street", "Leith, Edinburgh EH6 6PU", "United Kingdom"],
+  contact: { email: "maya@northwind.co", phone: "+44 7700 900123" },
+  shipping: 0,
+  tax: "Included",
+  discount: { code: "WELCOME10", amount: 19.6 },
+  paidWith: "Visa ending 4242",
+  timeline: [
+    { key: "placed", label: "Order placed", date: "2026-09-18" },
+    { key: "confirmed", label: "Confirmed", date: "2026-09-18" },
+    { key: "shipped", label: "Shipped", date: "2026-09-20" },
+    { key: "delivered", label: "Delivered" },
+  ],
+};
+
+const DELIVERED = {
+  ...ORDER,
+  status: "Delivered",
+  stage: "delivered",
+  timeline: ORDER.timeline.map((s) => (s.key === "delivered" ? { ...s, date: "2026-09-23" } : s)),
+};
+
+const CANCELLED = { ...ORDER, number: "#10477", status: "Cancelled", stage: "confirmed", estimatedDelivery: null };
+
+const VIEWS = [
+  { value: "shipped", label: "Shipped" },
+  { value: "delivered", label: "Delivered" },
+  { value: "cancelled", label: "Cancelled" },
+  { value: "missing", label: "Missing" },
+  { value: "loading", label: "Loading" },
+];
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export default function OrderDetailDemo() {
+  const [view, setView] = useState("shipped");
+  const [failing, setFailing] = useState(false);
+  const [said, setSaid] = useState(null);
+  const order = { shipped: ORDER, delivered: DELIVERED, cancelled: CANCELLED }[view] ?? null;
+
+  const act = (what) => async () => {
+    await wait(400);
+    if (failing) return { ok: false, error: "The carrier did not answer. Try again." };
+    setSaid(what);
+    return { ok: true };
+  };
+
+  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 order to show" className="overflow-x-auto" />
+        <Switch id="order-fail" checked={failing} onChange={(e) => setFailing(e.target.checked)} label="Make actions fail" />
+      </div>
+      {said ? (
+        <p role="status" className="text-sm text-muted-foreground">
+          {said} was called.
+        </p>
+      ) : null}
+      <OrderDetail
+        order={order}
+        loading={view === "loading"}
+        onTrack={act("onTrack")}
+        onInvoice={act("onInvoice")}
+        onEditContact={act("onEditContact")}
+      />
+    </div>
+  );
+}

package/registry/blocks/order-detail/index.js

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

package/registry/blocks/order-detail/order-detail.jsx

@@ -0,0 +1,354 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Badge, Button, Card, Empty, Icon, Image, Notice, Skeleton, Steps, cx, formatDate } from "../../ui";
+
+// One placed order: its number and status, the items, where it goes and
+// who hears about it, a timeline from placed to delivered, and the
+// totals. Read-only; the actions (track, invoice, edit contact) are the
+// app's through callbacks or links.
+
+// Server and browser may differ in locale, time zone and even the day:
+// the first render uses fixed ones (en-US, UTC) so it matches the server's
+// HTML, then the reader's own take over.
+function useHydrated() {
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => setHydrated(true), []);
+  return hydrated;
+}
+
+const DEFAULT_STAGES = [
+  { key: "placed", label: "Order placed" },
+  { key: "confirmed", label: "Confirmed" },
+  { key: "shipped", label: "Shipped" },
+  { key: "delivered", label: "Delivered" },
+];
+
+const STATUS_TONE = {
+  placed: "info",
+  confirmed: "info",
+  processing: "info",
+  shipped: "primary",
+  "in transit": "primary",
+  delivered: "success",
+  cancelled: "danger",
+  refunded: "warning",
+  returned: "warning",
+};
+
+const formats = new Map();
+function money(amount, currency = "USD", locale) {
+  const key = `${locale ?? ""}|${currency}`;
+  let f = formats.get(key);
+  if (!f) {
+    try {
+      f = new Intl.NumberFormat(locale, { style: "currency", currency });
+    } catch {
+      f = new Intl.NumberFormat(locale, { style: "currency", currency: "USD" });
+    }
+    formats.set(key, f);
+  }
+  return f.format(Number(amount) || 0);
+}
+
+// "2026-09-21" or a full ISO timestamp → "Sep 21, 2026".
+function day(value, locale, timeZone) {
+  if (!value) return "";
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) return formatDate(value, { dateStyle: "medium" }, locale);
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? String(value) : new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeZone }).format(d);
+}
+
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+
+// The stages as Steps: before the reached one complete, the reached one
+// current (complete when it is the last), after it pending. A stage may
+// carry its own status (a failed delivery). A cancelled order stops where
+// it was and says so.
+function timeline(order, locale, timeZone) {
+  const stages = order.timeline?.length ? order.timeline : DEFAULT_STAGES;
+  const reached = Math.max(0, stages.findIndex((s) => s.key === order.stage));
+  const cancelled = String(order.status ?? "").toLowerCase() === "cancelled";
+  const steps = stages.map((s, i) => {
+    let status = s.status;
+    if (!status) {
+      if (i < reached) status = "complete";
+      else if (i === reached) status = cancelled ? "failed" : i === stages.length - 1 ? "complete" : "current";
+      else status = cancelled ? "skipped" : "pending";
+    }
+    const when = s.date ? day(s.date, locale, timeZone) : null;
+    const description = s.note ?? (when ? when : status === "pending" && i === stages.length - 1 && order.estimatedDelivery ? `Expected ${day(order.estimatedDelivery, locale, timeZone)}` : undefined);
+    return { key: s.key ?? String(i), label: s.label, description, status };
+  });
+  return steps;
+}
+
+function Loading() {
+  return (
+    <div aria-busy="true" aria-label="Loading the order" className="grid gap-4">
+      <Skeleton className="h-7 w-48" />
+      <Skeleton className="w-64" />
+      <Card>
+        <div className="flex gap-4">
+          <Skeleton shape="rect" className="size-20" />
+          <div className="grid flex-1 content-start gap-2">
+            <Skeleton className="w-1/2" />
+            <Skeleton className="w-1/4" />
+          </div>
+        </div>
+      </Card>
+      <Card>
+        <div className="grid gap-3">
+          <Skeleton className="w-full" />
+          <Skeleton className="w-full" />
+          <Skeleton className="w-2/3" />
+        </div>
+      </Card>
+    </div>
+  );
+}
+
+function Detail({ icon, title, action, children }) {
+  return (
+    <div className="grid content-start gap-2">
+      <div className="flex items-center gap-2">
+        <span className="grid size-8 shrink-0 place-items-center rounded-full bg-primary/10 text-primary">
+          <Icon name={icon} size={16} />
+        </span>
+        <h3 className="text-sm font-semibold">{title}</h3>
+      </div>
+      <div className="text-sm text-muted-foreground">{children}</div>
+      {action}
+    </div>
+  );
+}
+
+function ActionButton({ label, icon, href, onAction, variant = "secondary", size = "md" }) {
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  async function run() {
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await onAction();
+      if (res && res.ok === false) setError(res.error || "That did not work.");
+    } catch (e) {
+      setError(e?.message || "That did not work.");
+    }
+    setBusy(false);
+  }
+  return (
+    <span className="grid justify-items-start gap-1">
+      <Button variant={variant} size={size} icon={icon} href={href} onClick={href ? undefined : run} loading={busy}>
+        {label}
+      </Button>
+      {error ? (
+        <span role="alert" className="text-xs text-destructive">
+          {error}
+        </span>
+      ) : null}
+    </span>
+  );
+}
+
+export function OrderDetail({
+  order,
+  currency: currencyProp,
+  locale: localeProp,
+  loading = false,
+  error,
+  onTrack,
+  trackHref,
+  trackLabel = "Track order",
+  onInvoice,
+  invoiceHref,
+  invoiceLabel = "Invoice",
+  onEditContact,
+  emptyTitle = "Order not found",
+  emptyBody = "It may have been removed, or the link is out of date.",
+  className,
+}) {
+  const hydrated = useHydrated();
+  const locale = localeProp ?? (hydrated ? undefined : "en-US");
+  const timeZone = hydrated ? undefined : "UTC";
+  if (loading) return <Loading />;
+  if (!order) {
+    return (
+      <div className={cx("grid gap-4", className)}>
+        {error ? <Notice tone="danger">{error}</Notice> : null}
+        <Empty icon="package" title={emptyTitle} body={emptyBody} />
+      </div>
+    );
+  }
+
+  const currency = order.currency ?? currencyProp ?? "USD";
+  const items = (order.items ?? []).filter(Boolean);
+  const count = items.reduce((n, i) => n + (Number(i.quantity) || 0), 0);
+  const subtotal = order.subtotal ?? items.reduce((s, i) => s + (Number(i.price) || 0) * (Number(i.quantity) || 0), 0);
+  const discount = order.discount ? Math.abs(num(order.discount.amount ?? order.discount)) : 0;
+  const total = order.total ?? Math.max(0, subtotal - discount + num(order.shipping) + num(order.tax));
+  const status = order.status ? String(order.status) : null;
+  const tone = order.statusTone ?? STATUS_TONE[status?.toLowerCase()] ?? "neutral";
+  const address = Array.isArray(order.address) ? order.address : order.address ? String(order.address).split("\n") : [];
+  const contact = order.contact ?? {};
+  const canTrack = Boolean(onTrack || trackHref);
+
+  const chargeRow = (label, v, freeLabel) =>
+    v === undefined || v === null ? null : (
+      <div className="flex justify-between gap-3">
+        <dt className="text-muted-foreground">{label}</dt>
+        <dd className={cx("font-medium tabular-nums", v === 0 && freeLabel && "text-success")}>
+          {typeof v === "string" ? v : v === 0 && freeLabel ? freeLabel : money(v, currency, locale)}
+        </dd>
+      </div>
+    );
+
+  return (
+    <div className={cx("grid gap-5", className)}>
+      <header className="flex flex-wrap items-start justify-between gap-4">
+        <div className="grid min-w-0 gap-1.5">
+          <div className="flex flex-wrap items-center gap-2">
+            <h2 className="text-xl font-semibold">Order {order.number ?? order.id}</h2>
+            {status ? (
+              <Badge tone={tone} variant="soft">
+                {status}
+              </Badge>
+            ) : null}
+          </div>
+          <p className="flex flex-wrap items-center gap-x-4 gap-y-1 text-sm text-muted-foreground">
+            {order.placedAt ? (
+              <span className="inline-flex items-center gap-1.5">
+                <Icon name="clock" size={14} />
+                Placed {day(order.placedAt, locale, timeZone)}
+              </span>
+            ) : null}
+            <span className="inline-flex items-center gap-1.5">
+              <Icon name="package" size={14} />
+              {count} {count === 1 ? "item" : "items"}
+            </span>
+          </p>
+        </div>
+        {onInvoice || invoiceHref ? (
+          <ActionButton label={invoiceLabel} icon="receipt" href={invoiceHref} onAction={onInvoice} />
+        ) : null}
+      </header>
+
+      {error ? <Notice tone="danger">{error}</Notice> : null}
+
+      <Card padding="none">
+        <div className="grid gap-6 p-4 sm:p-6 md:grid-cols-2">
+          <ul aria-label="Items in this order" className="grid content-start gap-4">
+            {items.map((item) => (
+              <li key={item.id} className="flex gap-3 sm:gap-4">
+                <Image src={item.image} alt="" ratio="square" fit="cover" className="size-20 shrink-0 sm:size-24" />
+                <div className="grid min-w-0 flex-1 content-start gap-1">
+                  <p className="font-medium leading-snug">{item.name}</p>
+                  {item.variant ? <p className="text-sm text-muted-foreground">{item.variant}</p> : null}
+                  <div className="mt-1 flex flex-wrap items-baseline justify-between gap-2">
+                    <span className="text-sm text-muted-foreground">Qty {item.quantity}</span>
+                    <span className="font-semibold tabular-nums">
+                      {money((Number(item.price) || 0) * (Number(item.quantity) || 0), currency, locale)}
+                    </span>
+                  </div>
+                </div>
+              </li>
+            ))}
+            {!items.length ? <li className="text-sm text-muted-foreground">No items on this order.</li> : null}
+          </ul>
+
+          <div className="grid content-start gap-6 sm:grid-cols-2">
+            {address.length ? (
+              <Detail icon="map" title="Delivery address">
+                <address className="not-italic leading-relaxed">
+                  {address.map((line, i) => (
+                    <span key={i} className="block">
+                      {line}
+                    </span>
+                  ))}
+                </address>
+              </Detail>
+            ) : null}
+            {contact.email || contact.phone ? (
+              <Detail
+                icon="mail"
+                title="Updates go to"
+                action={
+                  onEditContact ? (
+                    <ActionButton label="Edit contact" size="sm" onAction={onEditContact} />
+                  ) : null
+                }
+              >
+                <div className="grid gap-1">
+                  {contact.email ? (
+                    <span className="inline-flex min-w-0 items-center gap-1.5">
+                      <Icon name="mail" size={14} className="shrink-0" />
+                      <span className="truncate">{contact.email}</span>
+                    </span>
+                  ) : null}
+                  {contact.phone ? (
+                    <span className="inline-flex items-center gap-1.5">
+                      <Icon name="phone" size={14} className="shrink-0" />
+                      {contact.phone}
+                    </span>
+                  ) : null}
+                </div>
+              </Detail>
+            ) : null}
+          </div>
+        </div>
+
+        <div className="grid gap-6 border-t border-border p-4 sm:p-6 lg:grid-cols-[1fr_20rem] lg:gap-10">
+          <div className="grid content-start gap-4">
+            <h3 className="font-semibold">Timeline</h3>
+            <Steps steps={timeline(order, locale, timeZone)} orientation="vertical" label="Order progress" hideLabel />
+          </div>
+
+          <div className="grid content-start gap-4 rounded-lg border border-border bg-muted/40 p-4">
+            <h3 className="font-semibold">Summary</h3>
+            <dl className="grid gap-2.5 text-sm">
+              {chargeRow("Subtotal", subtotal)}
+              {discount ? (
+                <div className="flex justify-between gap-3">
+                  <dt className="text-muted-foreground">
+                    Discount{order.discount?.code ? ` (${order.discount.code})` : ""}
+                  </dt>
+                  <dd className="font-medium tabular-nums text-success">−{money(discount, currency, locale)}</dd>
+                </div>
+              ) : null}
+              {chargeRow("Shipping", order.shipping, "Free")}
+              {chargeRow("Tax", order.tax)}
+              <div className="mt-1.5 flex items-baseline justify-between gap-3 border-t border-border pt-3">
+                <dt className="text-base font-semibold">Total</dt>
+                <dd className="text-xl font-semibold tabular-nums">{money(total, currency, locale)}</dd>
+              </div>
+            </dl>
+            {order.paidWith ? (
+              <p className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                <Icon name="credit-card" size={14} />
+                Paid with {order.paidWith}
+              </p>
+            ) : null}
+            {canTrack || order.estimatedDelivery ? (
+              <div className="grid gap-3 rounded-md bg-primary/10 p-3">
+                <div className="flex items-start gap-2">
+                  <Icon name="truck" size={16} className="mt-0.5 shrink-0 text-primary" />
+                  <div className="text-sm">
+                    <p className="font-medium">
+                      {order.stage === "delivered" ? "Delivered" : order.estimatedDelivery ? "On its way" : "Tracking"}
+                    </p>
+                    {order.estimatedDelivery && order.stage !== "delivered" ? (
+                      <p className="text-xs text-muted-foreground">Expected {day(order.estimatedDelivery, locale, timeZone)}</p>
+                    ) : null}
+                  </div>
+                </div>
+                {canTrack ? (
+                  <ActionButton label={trackLabel} icon="external" href={trackHref} onAction={onTrack} size="sm" />
+                ) : null}
+              </div>
+            ) : null}
+          </div>
+        </div>
+      </Card>
+    </div>
+  );
+}