@base44/app-plugin-commerce 0.4.1 → 0.5.1

package/src/commerce/utils/index.js

@@ -28,7 +28,10 @@
  * - `ribbons.js` — `productRibbons`: ribbons normalized to `{id, name}` — they
  *   are objects, and the field is absent on a listing page that carries none.
  * - `specs.js` — `productSpecs`: `meta_data` → descriptive rows (`key`, `label`,
- *   `titleLabel`, `value`). Match rows by `key`, never by `label`.
+ *   `titleLabel`, `value`) each carrying an inferred render `type` (numeric,
+ *   duration, location, list, text), so a weight can read as a figure and a
+ *   composition as bars instead of every modifier as one grey table row. Match
+ *   rows by `key` via `findSpec`, never by `label`.
  * - `types.js` — types only: `StorefrontProduct` and the rest of the catalog
  *   shapes as JSDoc typedefs, so what a field holds is readable from the
  *   frontend instead of from the backend function's source.

package/src/commerce/utils/specs.js

@@ -6,6 +6,32 @@
  * **not** attributes and not ribbons: they describe the product, they don't
  * select a variant. Hidden keys (leading `_`) and empty values are skipped.
  *
+ * Each row carries a `type` — inferred from the value, and for `"location"`
+ * from the key — so the rendering decision is already made for you. **A
+ * `.map()` into one uniform label/value table is the fallback, not the
+ * target:** the types exist because a carat weight and a care instruction are
+ * not the same kind of fact and should not look alike.
+ *
+ * ```jsx
+ * // ❌ every product in every store, identical: one grey table
+ * <dl>{productSpecs(product).map((s) => (
+ *   <div key={s.key}><dt>{s.titleLabel}</dt><dd>{s.value}</dd></div>))}</dl>
+ *
+ * // ✅ branch on type — the figures read as figures, the rest stays a row
+ * {productSpecs(product).map((s) =>
+ *   s.type === "numeric"  ? <Figure  key={s.key} label={s.label} n={s.number} unit={s.unit} />
+ * : s.type === "location" ? <Sourced key={s.key} place={s.value} />          // a located line, a pin
+ * : s.type === "list"     ? <Bars    key={s.key} parts={s.items} />          // composition, materials
+ * : s.type === "duration" ? <Lead    key={s.key} label={s.label} value={s.value} />
+ * :                         <Row     key={s.key} label={s.titleLabel} value={s.value} />)}
+ * ```
+ *
+ * Design the two or three that carry *this* product's meaning (a weight set in
+ * the display face, a provenance beside a map, a composition as bars) and let
+ * the remainder fall through to the plain row. The rows need not sit in one
+ * block either: a spec can go under the gallery, beside the price, or inside
+ * the description.
+ *
  * ```jsx
  * const specs = productSpecs(product);
  * const care = findSpec(specs, "care");   // not specs.find(s => s.label === "Care")
@@ -18,17 +44,15 @@
  * fallback forever (observed in a live store). `titleLabel` is the display-cased
  * form, for when you do want to print the key as a heading.
  *
- * A `.map()` into one uniform label/value table is the fallback, not the
- * target: a carat weight and a care instruction are not the same kind of fact
- * and need not look alike. Which two or three of *this* catalog's modifiers
- * carry meaning — and how each is rendered — is a design decision about this
- * store, made from its own data. The rows need not sit in one block either: a
- * spec can go under the gallery, beside the price, or inside the description.
- *
  * @param {object} product
- * @returns {Array<{key: string, label: string, titleLabel: string, value: string}>}
+ * @returns {Array<{key: string, label: string, titleLabel: string, value: string,
+ *   type: "numeric"|"duration"|"location"|"list"|"text",
+ *   number: number|null, unit: string|null, items: string[]}>}
  *   `[]` when the product has no visible meta_data — render nothing, not an
- *   empty section. `value` is always the store's own text, unchanged.
+ *   empty section. `number`/`unit` are set for `numeric` and `duration`
+ *   (`unit` is `""` for a bare number), `items` for `list`, and are
+ *   `null`/`[]` otherwise. `value` is always the store's own text, unchanged —
+ *   the extra fields are there to render *with*, never a replacement for it.
  */
 export function productSpecs(product) {
   return (product?.meta_data ?? [])
@@ -40,7 +64,7 @@ export function productSpecs(product) {
       // `label` is the key with underscores opened up, in whatever case it was
       // typed; `titleLabel` is the display-cased form, for printing as a <dt>.
       const titleLabel = label.replace(/(^|\s)\p{Ll}/gu, (c) => c.toUpperCase());
-      return { key, label, titleLabel, value };
+      return { key, label, titleLabel, value, ...classify(key, value) };
     });
 }
 
@@ -67,3 +91,64 @@ const normalizeSpecKey = (k) =>
     .toLowerCase()
     .replace(/[\s_-]+/g, "")
     .trim();
+
+const LOCATION_KEY =
+  /(origin|provenance|made[\s_-]?in|country|region|sourced|source|location|city|terroir|appellation|distillery|winery|atelier|workshop)/i;
+
+const DURATION_UNIT =
+  /^(sec|secs|second|seconds|min|mins|minute|minutes|hr|hrs|hour|hours|day|days|week|weeks|month|months|year|years|yr|yrs)$/i;
+
+/** Infer the render-relevant shape of one spec value. Never throws. */
+function classify(key, raw) {
+  const value = raw.trim();
+  const plain = { type: "text", number: null, unit: null, items: [] };
+
+  if (LOCATION_KEY.test(key)) return { ...plain, type: "location" };
+
+  const qty = parseQuantity(value);
+  if (qty) {
+    const type = DURATION_UNIT.test(qty.unit) ? "duration" : "numeric";
+    return { ...plain, type, number: qty.number, unit: qty.unit };
+  }
+
+  const items = parseList(value);
+  if (items) return { ...plain, type: "list", items };
+
+  return plain;
+}
+
+/** "0.75 ct" → {number: 0.75, unit: "ct"}; "18" → {number: 18, unit: ""}. */
+function parseQuantity(value) {
+  const m = /^([-+]?[\d.,]+)\s*(.*)$/.exec(value);
+  if (!m) return null;
+  const number = toNumber(m[1]);
+  if (number === null) return null;
+  const unit = m[2].trim();
+  // A unit is a word or two of symbols/letters. Anything longer is prose that
+  // happens to start with a number ("2 pieces, hand-cut in the studio").
+  if (unit && (!/^[\p{L}%°µ"'/²³.\- ]{1,12}$/u.test(unit) || unit.split(/\s+/).length > 2)) return null;
+  return { number, unit };
+}
+
+/** Grouped thousands are separators; a lone comma between digits is a decimal. */
+function toNumber(raw) {
+  let s = raw.replace(/\s/g, "");
+  if (/^[-+]?\d{1,3}(,\d{3})+(\.\d+)?$/.test(s)) s = s.replace(/,/g, "");
+  else if (/^[-+]?\d+,\d+$/.test(s)) s = s.replace(",", ".");
+  else if (s.includes(",")) return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** "70% wool / 30% cashmere" → ["70% wool", "30% cashmere"]. */
+function parseList(value) {
+  const parts = value
+    .split(/\s*[,;|·•/]\s*/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (parts.length < 2) return null;
+  // Short fragments with words in them — not a sentence that happens to have commas.
+  if (parts.some((p) => p.length > 24 || p.split(/\s+/).length > 3 || /[.!?]/.test(p))) return null;
+  if (!parts.some((p) => /\p{L}/u.test(p))) return null;
+  return parts;
+}

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

@@ -1,99 +0,0 @@
----
-read_when: "You are writing the CSS for the cart, drawer, checkout or receipt — the parts' look."
----
-
-# 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, the
-drawer as a right-hand panel over a full-viewport overlay. 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.
-
-**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`), the notices (`[data-part="error"]`, `blocker`, `hint` —
-`[data-severity="error"]` marks the loud ones), and the drawer surface
-(`[data-part="panel"]` needs a background of its own, `[data-part="overlay"]` a
-scrim).
-
-**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 built-in 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 |
-| `--commerce-drawer-width` | `28rem` | drawer panel width |
-| `--commerce-drawer-z` | `50` | drawer stacking order (raise above a sticky header) |
-
-## `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` · `drawer` | overlay · panel; `close` | `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.
-
-## When CSS isn't enough
-
-A control that needs different markup takes the part's render override
-(`inputRender`, `optionRender`, `lineRender`, `itemRender`, `fieldRender`) —
-your element, the part's wiring. A whole section that needs different structure
-drops to its hook: [`./storefront-custom.md`](./storefront-custom.md).