makersclaw 0.1.0 → 0.3.0

package/registry/blocks/cart/README.md

@@ -0,0 +1,146 @@
+# Cart
+
+The basket and the checkout page. The cart lists line items (picture,
+name, option, quantity, remove) beside a summary: subtotal, a discount
+code, shipping, tax, the total and Checkout. `step="checkout"` is the next
+page: the buyer's email and delivery address beside the same summary,
+read-only. It ends at `onPay`. **There are no card fields**: the app hands
+off to Paddle there, which takes the payment.
+
+Every change goes out through a callback that returns `{ ok }`; a failed
+one is shown on the row (or the summary) that asked for it.
+
+```jsx
+import { Cart } from "../components/blocks/cart";   // a Makersclaw app ("./blocks/cart" from components/)
+import { Cart } from "@/components/makersclaw/blocks/cart";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the cart in the server surface (README §4).
+
+## The data
+
+One line item per row of the cart:
+
+```js
+{ id: "li_1", name: "Merino crew", image: "https://…", price: 89, quantity: 2, variant: "Charcoal · M" }
+```
+
+- `price` is one unit's price, a number in the currency's major unit
+  (89.5 is $89.50). The row shows `price × quantity`.
+- `variant` is the chosen option in words, or empty.
+- `maxQuantity` (optional) caps the quantity picker; default 10.
+- Optional: `key` (a line's own key when the same product sits on two
+  lines, one per size; default `id`), `href` (the name links to the
+  product), `compareAt` (the old unit price, struck through beside the
+  line total), `currency` (over the `currency` prop).
+
+The same shape is what `product-detail` and `product-grid` hand to their
+add-to-cart callbacks, so a cart is those rows.
+
+## Props
+
+- `items` — the line items. An empty list shows the empty state.
+- `step` — `"cart"` (default) or `"checkout"`.
+- `currency` — an ISO code, default `"USD"`. `locale` — for the money
+  format, default the reader's.
+- `shipping` · `tax` — a number is a row that adds to the total (0 reads
+  "Free" for shipping); a string is shown as written and adds nothing
+  (`tax="Calculated at payment"` — Paddle works tax out). Leave one out
+  and its row is not drawn.
+- `discount` — the code in force: `{ code, amount, label? }`; `amount` is
+  taken off the total.
+- `note` — a line at the foot of the summary, beside a truck ("Free
+  delivery on orders over $100").
+- `loading` — skeleton rows. `error` — a line above everything (the cart
+  did not load).
+- `title` — the heading; default "Cart" or "Checkout".
+
+The cart step:
+
+- `onQuantityChange(item, quantity)` — save the new quantity; return
+  `{ ok: true }` or `{ ok: false, error }`. Without it the quantity is
+  shown, not picked.
+- `onRemove(item)` — remove the row, same return. Without it no ×.
+- `onApplyCode(code)` — a discount code field appears; return
+  `{ ok: false, error: "That code has expired." }` to say why not. On
+  success pass the new `discount` back in.
+- `onRemoveCode()` — an × beside the discount.
+- `onCheckout()` — the Checkout button; move to the checkout step (route
+  or state). May return `{ ok: false, error }`.
+- `checkoutLabel` — default "Checkout".
+- `onContinueShopping()` or `continueHref` — "Continue shopping", in the
+  summary and in the empty state. `continueLabel` renames it.
+- `emptyTitle` · `emptyBody` — the empty state's words.
+
+The checkout step:
+
+- `onPay(details)` — required for checkout. `details` is `{ email }`, plus
+  `{ name, address, city, postal, country }` when the address is asked
+  for. Save the order, open Paddle's checkout with it, and return
+  `{ ok: true }`; `{ ok: false, error }` shows the reason above the button.
+- `requireAddress` — default `true`; `false` for things that are not
+  shipped (downloads, tickets): only the email is asked for.
+- `terms` — a checkbox label that must be ticked before paying ("I agree
+  to the terms of sale"); a string or a node with links. Omit for none.
+- `defaultDetails` — prefill: `{ email, name, address, city, postal, country }`.
+- `payLabel` — the button; default "Continue to payment · $123.00".
+- `payNote` — the line under it; default says the card is entered on the
+  next screen. `null` for none.
+- `onBack()` — "Back to cart". `backLabel` renames it.
+
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/Basket.jsx — client
+"use client";
+import { useState } from "react";
+import { deleteRow, updateRow } from "../lib/actions";
+import { Cart } from "./blocks/cart";
+
+export default function Basket({ items, error }) {
+  const [step, setStep] = useState("cart");
+  return (
+    <Cart
+      items={items}
+      error={error}
+      step={step}
+      shipping={0}
+      tax="Calculated at payment"
+      note="Free delivery on every order this month."
+      onQuantityChange={(item, quantity) => updateRow({ source: "public.cart_items", id: item.id, patch: { quantity } })}
+      onRemove={(item) => deleteRow({ source: "public.cart_items", id: item.id })}
+      onCheckout={() => setStep("checkout")}
+      onBack={() => setStep("cart")}
+      continueHref="/shop"
+      terms="I agree to the terms of sale"
+      onPay={async (details) => {
+        const res = await fetch("/api/checkout", { method: "POST", body: JSON.stringify(details) });
+        if (!res.ok) return { ok: false, error: "We could not start the payment. Try again." };
+        const { transactionId } = await res.json();
+        window.Paddle?.Checkout.open({ transactionId });
+        return { ok: true };
+      }}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- Take a card number, expiry or CVC. Payment is Paddle's overlay or page,
+  opened from `onPay`; the block never sees a card.
+- Work out tax or shipping: pass the numbers (or the words) in.
+- Keep the cart: `items` is the app's; every change is a callback.
+- Validate an address against a country's format: it checks that each
+  field is filled.
+
+A cart 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 cart` 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/cart/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "cart",
+  "title": "Cart",
+  "description": "A shopping cart: line items with picture, option, quantity and remove, a summary (subtotal, discount code, shipping, tax, total) and Checkout. step=\"checkout\" is the checkout page: contact and delivery details beside the order summary, ending at onPay, which hands off to Paddle. No card fields. Empty and loading states built in.",
+  "useWhen": "An app that sells things: the basket before paying, and the page that collects the buyer's email and address before the payment provider takes over. Not for a subscription plan picker (a pricing table) or for an order already placed (order-detail).",
+  "tags": ["cart", "basket", "checkout", "shop", "store", "ecommerce", "commerce", "order", "summary", "quantity", "discount", "coupon", "promo", "shipping", "paddle", "pay"],
+  "exports": ["Cart"],
+  "files": ["index.js", "cart.jsx", "money.js"],
+  "requires": []
+}