@base44/app-plugin-commerce 0.5.1 → 0.6.0

package/skills/commerce/references/storefront-parts.md

@@ -1,184 +0,0 @@
----
-read_when: "You are writing the store's copy file for the parts, the CSS for the cart/drawer/checkout/receipt, or swapping one of their controls for your own element."
----
-
-# The parts' words and look
-
-The two inputs that make the commodity surfaces *this* store's: the copy file
-(every word the parts render) and the CSS (everything they look like). The parts
-themselves are contracted in install/02-storefront.md.
-
-## The copy file — every word, written once
-
-The parts ship **no customer-facing string and no fallback**: a label that isn't
-provided renders a visible `⟨copy: path⟩` placeholder and warns once in the
-console. Copy the map below into `src/copy.js`, pass it once
-(`<StorefrontProvider labels={STORE_COPY}>`), and ⚑ **rewrite every value in
-this store's voice** — the English here is *reference*; shipped verbatim it is
-how storefronts end up sounding alike (`aria.*` name controls for screen
-readers; templates take the item's name):
-
-```js
-export const STORE_COPY = {
-  placeOrder: { label: "Place order", placing: "Placing your order…" },
-  blockers: {
-    empty_cart: "Your bag is empty.", billing_incomplete: "Fill in your details above.",
-    shipping_address_incomplete: "Finish the delivery address.",
-    shipping_address_required: "Enter your address to see delivery options.",
-    shipping_method_required: "Choose a delivery option.",
-    shipping_not_available: "We can't deliver to that address.",
-    payment_method_required: "Choose how you'd like to pay.",
-    cart_loading: "One moment — loading your bag.", shipping_recalculating: "Updating delivery costs…",
-  },
-  shipping: {
-    missing_address: "Delivery options appear once your address is entered.",
-    none_available: "We don't deliver to that address yet.",
-    syncing: "Updating delivery options…",
-  },
-  payment: { none_available: "Checkout is unavailable right now — please try again later." },
-  coupon: { placeholder: "Gift or promo code", apply: "Apply", remove: "Remove" },
-  fields: {
-    first_name: "First name", last_name: "Last name", email: "Email", company: "Company",
-    address_1: "Address", address_2: "Apartment, suite (optional)", country: "Country",
-    city: "City", state: "State / Province", postcode: "Postal code",
-    phone: "Phone (optional)", select_placeholder: "Select…",
-  },
-  totals: { subtotal: "Subtotal", discount: "Discount", shipping: "Shipping", tax: "Tax", total: "Total" },
-  bank: { account_name: "Account name", account_number: "Account number", bank_name: "Bank",
-          sort_code: "Sort code", iban: "IBAN", bic: "BIC" },
-  aria: {
-    trigger: "Open your bag", drawer: "Your bag", close: "Close",
-    increase: (name) => `Add one more ${name}`, decrease: (name) => `Remove one ${name}`,
-    remove: (name) => `Remove ${name} from your bag`,
-    shipping_group: "Delivery options", payment_group: "Payment methods",
-  },
-};
-```
-
-Blocker lines are what a disabled place-order button says — one per code, naming
-the thing the customer can fix (`cart_loading`/`shipping_recalculating` are quiet
-transients, not errors); `shipping.*`/`payment.*` are the pickers' dead-ends,
-with the server's own message rendered instead where one exists. The key tree is
-frozen in code as `REQUIRED_LABEL_KEYS`, and a part or a page `Root` takes a
-`labels` slice of the same shape when one surface needs different wording.
-
-Headings, empty/loading/submitted screens, links and anything else in *your*
-markup are ordinary JSX — the copy file covers only what the parts render.
-
-## Styling the parts
-
-The parts ship **layout geometry and nothing else** (`src/commerce/storefront/parts/parts.css`,
-loaded automatically by `@/commerce/storefront`): field grids, labels above
-full-width controls, media as a fixed square, rows as media + content +
-controls with the money pushed right, totals as label-left/value-right. Nothing
-in it carries color, background, border, radius, shadow, font or text
-decoration — a release check enforces that — so an unstyled store reads as
-*unfinished*, never as broken, and the look is entirely yours.
-
-It also stops at the edge of a part: **arranging sections is yours** — the
-checkout's columns, the space between sections, and the cart drawer, whose
-overlay and panel you render and position yourself (`useCartUI()` keeps its
-state, focus handling and inert-while-closed; see install/02-storefront.md).
-
-**Every rule is wrapped in `:where()`, so its specificity is 0.** A plain
-`[data-part="row"] { display: grid }` in your stylesheet wins — no `!important`,
-no cascade fights, no need to know what the sheet did.
-
-## Two ways in, one vocabulary
-
-```css
-/* index.css — selectors, next to the store's design classes */
-[data-part="control"] { … }
-[data-part="option"][data-state="selected"] { … }
-[data-part="row"][data-pending] { opacity: .55; }
-```
-
-```jsx
-{/* or classes, keyed by the same data-part names */}
-<Cart.Lines className="bag" classes={{ row: "bag-row", media: "bag-thumb", "line-total": "price" }} />
-```
-
-Tailwind reaches inner parts with arbitrary variants
-(`className="[&_[data-part=option]]:choice-row"`) or `@apply` inside a design
-class. Either way the names are the ones below.
-
-## The minimum that makes a store look designed
-
-⚑ **Style the controls.** Browser-default inputs are a white box in a system
-font — on a dark or branded storefront that alone reads as unfinished:
-
-```css
-[data-part="control"], [data-part="input"] {
-  border: …; background: …; color: inherit; font: inherit; padding: …;
-}
-[data-part="control"]:focus-visible { outline: …; }      /* keep a visible focus ring */
-[data-part="field"][data-invalid] [data-part="control"] { border-color: …; }
-```
-
-Then, in the store's own values: the labels (`[data-part="label"]` — size,
-tracking, case), the option rows (`[data-part="option"]` — padding, border,
-and the `[data-state="selected"]` treatment, which is the one control customers
-look for), the totals (`[data-part="value"]`, `[data-emphasis]` for the total
-line), the buttons (`[data-part="place-order"]`, `apply`, `remove`,
-`increase`/`decrease`), and the notices (`[data-part="error"]`, `blocker`, `hint` —
-`[data-severity="error"]` marks the loud ones). The drawer's own surface and
-scrim are your elements, so they carry your classes, not `data-part` selectors.
-
-**The parts add no outer margins** — space *between* sections comes from the
-containers you wrap them in (`gap` on your checkout grid, your aside, your
-drawer panel's column).
-
-## Tuning the geometry
-
-Set these anywhere — `:root`, a page, one part — instead of rewriting the rules:
-
-| Custom property | Default | Controls |
-|---|---|---|
-| `--commerce-gap` | `1rem` | fields, rows, options, panel sections |
-| `--commerce-gap-tight` | `0.4rem` | label→control, name→attributes, stepper |
-| `--commerce-field-columns` | `2` | address-form columns (set `1` in a narrow aside or a media query) |
-| `--commerce-media-size` | `4rem` | cart/summary thumbnail edge |
-
-## `data-part` inventory
-
-| Part root | Inner `data-part`s | State attributes |
-|---|---|---|
-| `address-fields`; `ship-to-different` | field · label · required · control · error | `data-which`, `data-key`, `data-span`, `data-invalid` |
-| `shipping-methods` `payment-methods` | hint · option · option-input · option-label · option-cost / option-description · chosen | `data-state="selected"`, `data-syncing`, `data-severity` |
-| `lines` `items`; `notices` | row · media · content · name · attributes · controls · stepper · increase · decrease · quantity · remove · line-total · error; notice | `data-pending`, `data-empty`, `data-code` |
-| `totals`; `payment-instructions` | row · label · value; description · account | `data-key`, `data-emphasis` |
-| `coupon-field` | input · apply · error · applied · code · remove | `data-busy` |
-| `place-order` · `order-error` · `blockers` | blocker | `data-state="placing"`, `data-code` |
-| `trigger` · `close` | — (the drawer's layer, scrim and panel are your elements) | `data-state="open\|closed"` |
-
-`media` is an `<img>` when the line has an image and an empty `<div
-data-part="media" data-empty>` when it doesn't — same box either way, so style
-the placeholder (`[data-empty]`) rather than letting it render as a hole. ⚑ **A
-cart, summary or receipt that shows no thumbnails is a `media={false}` prop, not
-a CSS `display: none`** — the prop renders nothing at all, while hiding leaves an
-empty box in the layout and the accessibility tree.
-
-## Overrides — your element, the part's wiring
-
-CSS covers how a control *looks*; these cover the cases where the **element
-itself** is the design decision. Each one keeps the part's state, gating and
-accessibility wiring and hands you what to render from:
-
-| Prop | On | Receives | Replaces |
-|---|---|---|---|
-| `inputRender` | `AddressFields` | `{ field, id, value, onChange, onBlur, invalid, autoComplete, options }` | the input/select only (label, required mark and error stay) |
-| `fieldRender` | `AddressFields` | the same, plus `label` | the whole labeled block |
-| `controlRender` | `ShipToDifferent` | `{ checked, onChange, toggle }` | the checkbox — a switch, a segmented control, two buttons |
-| `optionRender` | `ShippingMethods`, `PaymentMethods` | the decorated option (`title`, `costLabel`/`description`, `selected`, `select()`) | **the whole option element**, radio included |
-| `stepperRender` | `Cart.Lines` | `(controls, item)` — the `useCartLine` set | the quantity control alone (a `<select>`, a number input, your buttons) |
-| `inputRender` | `CouponField` | `{ value, onChange, onKeyDown, placeholder, disabled }` | the code field; apply button and messages stay |
-| `lineRender` / `itemRender` | `Cart.Lines`, `Checkout.Items`, `OrderReceived.Items` | `(item, controls)` / `(item)` | a whole row |
-
-⚑ **A replaced control still owes its semantics.** The kit's defaults are real
-form controls; if yours are not, carry the equivalent — keyboard operability, a
-readable state (`role="radio"` + `aria-checked`, `role="switch"`), and an
-accessible name. `show` (above) is for *removing* an element; these are for
-*replacing* it.
-
-A whole section that needs different structure drops to its hook instead:
-[`./storefront-custom.md`](./storefront-custom.md).

package/src/commerce/storefront/parts/cart.jsx

@@ -1,191 +0,0 @@
-import React from "react";
-import { attributesLabel } from "@/commerce/utils";
-import { useCart, useFormatMoney } from "../StorefrontProvider";
-import { CartLine } from "../useCartLine";
-import { label, nameLabel, useResolvedLabels } from "./labels";
-import { visible } from "./visibility";
-import { CouponField, Totals } from "./shared";
-
-/**
- * Cart parts — the bag's sections, unstyled and unworded, for a cart page or
- * a drawer's contents alike. Contract, styling (`data-part`), labels and
- * placement: the commerce skill's install/02-storefront.md. These read the
- * ONE shared cart on `<StorefrontProvider>`; there is no `Cart.Root`.
- *
- * `Loading` / `Empty` / `Ready` are gates: children render only in the
- * matching cart status, so branching on emptiness-while-loading cannot be
- * written. Children may be a node or a function of `{ cart, itemCount }`.
- * The checkout link belongs in the store's own markup inside `<Cart.Ready>` —
- * no part renders navigation.
- */
-function gate(name, match) {
-  function Gate({ children }) {
-    const { status, cart, itemCount } = useCart();
-    if (status !== match) return null;
-    return typeof children === "function" ? (children({ cart, itemCount }) ?? null) : (children ?? null);
-  }
-  Gate.displayName = `Cart.${name}`;
-  return Gate;
-}
-
-const Loading = gate("Loading", "loading");
-const Empty = gate("Empty", "empty");
-const Ready = gate("Ready", "ready");
-
-/**
- * The line rows, with the interaction premade per row (optimistic quantity,
- * coalesced clicks, rollback, per-row `pending` — never a cart-wide busy
- * state).
- *
- * - `show` decides which of the row's elements render — `media`, `attributes`,
- *   `stepper`, `remove`, `lineTotal` (`show={{ media: false }}` is a text-only
- *   bag; `show={["media", "lineTotal"]}` is exactly those two). Nothing lands in
- *   the DOM for a hidden element, so it costs no layout and no screen-reader
- *   announcement. `stepper: false` still shows the quantity, as text.
- * - `stepperRender(controls, item)` replaces the quantity control alone — a
- *   `<select>`, a number input, the store's own buttons — while the row keeps its
- *   layout (`controls` is the `useCartLine` set: `quantity`, `increase`,
- *   `decrease`, `setQuantity`, `canIncrease`, `canDecrease`, `pending`).
- * - `lineRender(item, controls)` replaces a row wholesale; `item.slug` is there
- *   when the store's row links to the product page.
- */
-function Lines({ show, stepperRender, lineRender, className, classes, labels: partLabels }) {
-  const vis = visible(show);
-  const { status, cart } = useCart();
-  const formatMoney = useFormatMoney();
-  const L = useResolvedLabels(partLabels);
-  if (status !== "ready") return null;
-  return (
-    <ul data-part="lines" className={className}>
-      {cart.items.map((item) => (
-        <CartLine key={item.item_key} line={item}>
-          {(l) =>
-            lineRender ? (
-              lineRender(item, l)
-            ) : (
-              <li
-                data-part="row"
-                data-pending={l.pending || undefined}
-                aria-busy={l.pending}
-                className={classes?.row}
-              >
-                {vis("media") &&
-                  (item.image ? (
-                    <img data-part="media" className={classes?.media} src={item.image} alt="" loading="lazy" />
-                  ) : (
-                    <div data-part="media" data-empty="" className={classes?.media} />
-                  ))}
-                <span data-part="content" className={classes?.content}>
-                  <span data-part="name" className={classes?.name}>{item.name}</span>
-                  {vis("attributes") && attributesLabel(item.attributes) ? (
-                    <span data-part="attributes" className={classes?.attributes}>
-                      {attributesLabel(item.attributes)}
-                    </span>
-                  ) : null}
-                </span>
-                <span data-part="controls" className={classes?.controls}>
-                  {vis("stepper") && stepperRender && stepperRender(l, item)}
-                  {vis("stepper") && !stepperRender && (
-                    <span data-part="stepper" className={classes?.stepper}>
-                      <button
-                        type="button"
-                        data-part="decrease"
-                        className={classes?.decrease}
-                        onClick={l.decrease}
-                        disabled={!l.canDecrease || l.pending}
-                        aria-label={nameLabel(L, "aria.decrease", item.name)}
-                      >
-                        −
-                      </button>
-                      <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
-                      <button
-                        type="button"
-                        data-part="increase"
-                        className={classes?.increase}
-                        onClick={l.increase}
-                        disabled={!l.canIncrease || l.pending}
-                        aria-label={nameLabel(L, "aria.increase", item.name)}
-                      >
-                        +
-                      </button>
-                    </span>
-                  )}
-                  {!vis("stepper") && (
-                    <span data-part="quantity" className={classes?.quantity}>{l.quantity}</span>
-                  )}
-                  {vis("remove") && (
-                    <button
-                      type="button"
-                      data-part="remove"
-                      className={classes?.remove}
-                      onClick={l.remove}
-                      disabled={l.pending}
-                      aria-label={nameLabel(L, "aria.remove", item.name)}
-                    >
-                      ×
-                    </button>
-                  )}
-                </span>
-                {vis("lineTotal") && (
-                  <span data-part="line-total" className={classes?.["line-total"]}>
-                    {formatMoney(item.total)}
-                  </span>
-                )}
-                {l.error && (
-                  <p data-part="error" role="alert" className={classes?.error}>{l.error.message}</p>
-                )}
-                {item.purchasable && !item.purchasable.ok && (
-                  <p data-part="error" data-code={item.purchasable.code} role="alert" className={classes?.error}>
-                    {item.purchasable.error}
-                  </p>
-                )}
-              </li>
-            )
-          }
-        </CartLine>
-      ))}
-    </ul>
-  );
-}
-
-/**
- * What auto-dropped and why, in the server's own words — expired coupons
- * (`coupon_notices`) and vanished products (`removed_items`). Renders null
- * when there is nothing to say; place it above the lines so a disappearing
- * row never goes unexplained.
- */
-function Notices({ className, classes }) {
-  const { cart } = useCart();
-  const notices = [
-    ...(cart?.coupon_notices ?? []).map((n, i) => ({
-      key: `coupon-${n.code ?? i}`,
-      code: n.error_code,
-      text: n.error,
-    })),
-    ...(cart?.removed_items ?? []).map((r, i) => ({
-      key: `removed-${r.item_key ?? i}`,
-      code: r.code,
-      text: r.reason,
-    })),
-  ];
-  if (!notices.length) return null;
-  return (
-    <ul data-part="notices" role="status" className={className}>
-      {notices.map((n) => (
-        <li key={n.key} data-part="notice" data-code={n.code} className={classes?.notice}>
-          {n.text}
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-export const Cart = {
-  Loading,
-  Empty,
-  Ready,
-  Lines,
-  Notices,
-  CouponField,
-  Totals,
-};