@base44/app-plugin-commerce 0.5.0 → 0.6.0

package/src/commerce/storefront/AddressFields.jsx

@@ -0,0 +1,150 @@
+import React, { useId, useState } from "react";
+import { addressFieldSpec } from "@/commerce/utils";
+import { useCheckoutContext } from "./useCheckout";
+import { useCountries } from "./StorefrontProvider";
+import { REQUIRED_BILLING_FIELDS } from "./address";
+
+/**
+ * The checkout address form, headless — the one storefront section that ships
+ * as a component rather than as wiring reference, because hand-rolling it is
+ * where checkouts break: the state/province field must appear with the right
+ * options once a country is picked (shipping and taxes match on country *plus*
+ * state, so a form without it silently mis-prices US/CA/AU orders),
+ * `autoComplete` tokens are what make browser autofill work, and the server's
+ * "we don't ship there" belongs on the country field.
+ *
+ * It renders semantic fields and nothing else — no CSS ships with it. Every
+ * element carries `data-part` (`field`, `label`, `control`, `required`,
+ * `error`) plus `data-key`/`data-span`/`data-invalid`, so the store's own
+ * classes attach via `className`/`classes` props or `[data-part]` selectors.
+ * Field labels come from `addressFieldSpec` (plain conventions — rename any of
+ * them via `labels`). Required marks arm on first blur, never on load.
+ *
+ * Works inside `<CheckoutProvider>` (it reads `useCheckoutContext()`).
+ * `which="shipping"` renders null until `shipToDifferent` is on — the
+ * deliver-elsewhere checkbox itself stays yours, wired to
+ * `checkout.shipToDifferent` / `checkout.setShipToDifferent`.
+ *
+ * @param {object} props
+ * @param {"billing"|"shipping"} [props.which] which address this form edits.
+ * @param {boolean} [props.includeCompany] add the company field (default false).
+ * @param {boolean} [props.includePhone] keep the phone field (default true).
+ * @param {string[]} [props.omit] field keys to drop entirely.
+ * @param {Record<string, string>} [props.labels] label text per field key,
+ *   merged over the spec's defaults (e.g. `{ postcode: "ZIP code" }`).
+ * @param {string} [props.selectPlaceholder] the selects' empty-option text.
+ * @param {Function} [props.inputRender] `({ field, options, invalid, ...dom })`
+ *   — swaps the control only; spread `dom` onto your input.
+ * @param {Function} [props.fieldRender] `({ field, label, invalid, options, ...dom })`
+ *   — replaces the whole labeled block.
+ * @param {string} [props.className] class for the wrapping element.
+ * @param {{field?: string, label?: string, control?: string, error?: string}} [props.classes]
+ */
+export function AddressFields({
+  which = "billing",
+  includeCompany = false,
+  includePhone = true,
+  omit,
+  labels,
+  selectPlaceholder = "Select…",
+  inputRender: InputRender,
+  fieldRender,
+  className,
+  classes,
+}) {
+  const checkout = useCheckoutContext();
+  const { countries } = useCountries();
+  const idBase = useId();
+  const [touched, setTouched] = useState({});
+
+  const isBilling = which === "billing";
+  if (!isBilling && !checkout.shipToDifferent) return null;
+
+  const values = isBilling ? checkout.billing : checkout.shipping;
+  const set = isBilling ? checkout.updateBilling : checkout.updateShipping;
+  const omitted = new Set(omit ?? []);
+  const fields = addressFieldSpec({
+    countries,
+    country: values.country,
+    required: isBilling ? REQUIRED_BILLING_FIELDS : ["country", "city"],
+    includeEmail: isBilling, // one email per order, on billing
+    includeCompany,
+    includePhone,
+  }).filter((f) => !omitted.has(f.key));
+
+  return (
+    <div data-part="address-fields" data-which={which} className={className}>
+      {fields.map((f) => {
+        const id = `${idBase}-${which}-${f.key}`;
+        const value = values[f.key] ?? "";
+        const invalid = Boolean(touched[f.key] && f.required && !String(value).trim());
+        const dom = {
+          id,
+          value,
+          autoComplete: f.autoComplete,
+          onChange: (e) => set({ [f.key]: e && e.target ? e.target.value : e }),
+          onBlur: () => setTouched((t) => (t[f.key] ? t : { ...t, [f.key]: true })),
+        };
+        const labelText = labels?.[f.key] ?? f.label;
+        if (fieldRender) {
+          return (
+            <React.Fragment key={f.key}>
+              {fieldRender({ field: f, label: labelText, invalid, options: f.options, ...dom })}
+            </React.Fragment>
+          );
+        }
+        return (
+          <div
+            key={f.key}
+            data-part="field"
+            data-key={f.key}
+            data-span={f.colSpan}
+            data-invalid={invalid || undefined}
+            className={classes?.field}
+          >
+            <label data-part="label" className={classes?.label} htmlFor={id}>
+              {labelText}
+              {f.required && (
+                <span data-part="required" aria-hidden="true">
+                  *
+                </span>
+              )}
+            </label>
+            {InputRender ? (
+              <InputRender field={f} options={f.options} invalid={invalid} {...dom} />
+            ) : f.type === "select" ? (
+              <select
+                data-part="control"
+                className={classes?.control}
+                aria-invalid={invalid || undefined}
+                aria-required={f.required || undefined}
+                {...dom}
+              >
+                <option value="">{selectPlaceholder}</option>
+                {f.options.map((o) => (
+                  <option key={o.value} value={o.value}>
+                    {o.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <input
+                data-part="control"
+                className={classes?.control}
+                type={f.type}
+                aria-invalid={invalid || undefined}
+                aria-required={f.required || undefined}
+                {...dom}
+              />
+            )}
+            {f.key === "country" && checkout.addressError && (
+              <p data-part="error" role="alert" className={classes?.error}>
+                {checkout.addressError.message}
+              </p>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/commerce/storefront/StorefrontProvider.jsx

@@ -12,7 +12,6 @@ import {
   storefrontErrorCode,
   storefrontErrorMessage,
 } from "@/commerce/utils";
-import { LabelsScope } from "./parts/labels";
 
 /**
  * StorefrontProvider — one client, one store-info cache, ONE shared cart.
@@ -27,9 +26,7 @@ import { LabelsScope } from "./parts/labels";
  *   it, so the cart badge and the cart page read different carts.
  *
  * Pass `base44`, or `store={createStorefront(base44)}` when other modules need
- * the same client. `labels` (optional) is the store's copy map for the parts
- * layer — pass it once here and every part resolves its words from it (the
- * key list and example live in the skill's install/02-storefront.md).
+ * the same client.
  *
  * What lives here, and why it must not be duplicated per page: the client (it
  * owns the cart_token lifecycle); store info, cached for the session —
@@ -41,7 +38,7 @@ import { LabelsScope } from "./parts/labels";
 
 const StorefrontContext = createContext(null);
 
-export function StorefrontProvider({ base44, store, labels, children }) {
+export function StorefrontProvider({ base44, store, children }) {
   const client = useMemo(
     () => store ?? createStorefront(base44),
     [store, base44],
@@ -112,11 +109,7 @@ export function StorefrontProvider({ base44, store, labels, children }) {
     () => ({ client, info, infoError, cart, cartError, mutationError, runCart, clearCart }),
     [client, info, infoError, cart, cartError, mutationError, runCart, clearCart],
   );
-  return (
-    <StorefrontContext.Provider value={value}>
-      <LabelsScope labels={labels}>{children}</LabelsScope>
-    </StorefrontContext.Provider>
-  );
+  return <StorefrontContext.Provider value={value}>{children}</StorefrontContext.Provider>;
 }
 
 /** Advanced escape hatch: the raw provider state. Prefer the hooks below. */

package/src/commerce/storefront/cartUI.jsx

@@ -1,45 +1,26 @@
-import React, {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useId,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 
 /**
- * Cart drawer state and behavior, headless — **the drawer's surface is yours**:
- * you render the overlay and the panel, and own their position, size, padding,
- * animation and every class on them. What lives here is the part that is the
- * same in every store and easy to get wrong:
- *
- * - `open` + `openCart`/`closeCart`/`toggleCart`.
- * - Esc closes; the route changing closes (`closeOnNavigate`); an item landing
- *   in the cart opens (`openOnAdd`, wired through `useAddToCart` — pass false
- *   for a navigate-to-bag flow).
- * - **Focus.** Attach `panelRef` to your panel element: focus moves into it
- *   when the drawer opens and returns to whatever had it when the drawer
- *   closes (give the panel `tabIndex={-1}` so it can receive it).
- * - **A closed-but-mounted panel is made `inert`** while `panelRef` is
- *   attached — the classic drawer bug is a panel translated off-screen whose
- *   buttons stay clickable, tab-able and readable to screen readers. Animate
- *   the slide freely; the closed panel stops being interactive by itself.
- * - `panelId` — put it on your panel as `id`; the kit's `<CartDrawer.Trigger>`
- *   already points `aria-controls` at it.
+ * Cart drawer/panel state, headless: `open` plus the handlers to change it,
+ * and the two behaviors every drawer needs but a hand-written one forgets —
+ * it closes when the route changes (`closeOnNavigate`) and it opens when an
+ * item lands in the cart (`openOnAdd`, wired through `useAddToCart`; pass false
+ * for a navigate-to-bag flow). Esc closes it. You own every element, class and
+ * attribute.
  *
  * Mount `<CartUIProvider>` once, inside `<StorefrontProvider>`, around the
- * layout; the layout renders the drawer off `open`.
+ * layout; the layout then renders the panel off `open`.
  *
- * ⚑ Your panel is the dialog: `role="dialog" aria-modal="true"` plus a name
- * (`aria-label`/`aria-labelledby`). ⚑ The overlay is a click-away surface
- * (`aria-hidden`, no tab stop) — it is *not* the close control; a named close
- * button inside the panel is (`<CartDrawer.Close>`).
+ * ⚑ **Render the drawer conditionally — `{ui.open && …}`.** The classic drawer
+ * bug is a panel translated off-screen but still mounted: its buttons stay
+ * clickable, tab-able and visible to screen readers. Unmounting when closed is
+ * the trivial fix; if you keep it mounted to animate the slide, that concern is
+ * yours again — set the `inert` attribute while closed. The overlay is a
+ * click-away surface (`aria-hidden`, no tab stop) — it is not the close control;
+ * a named close button inside the panel is.
  *
- * `useCartUI()` → `{ open, openCart, closeCart, toggleCart, panelRef, panelId }`.
+ * `useCartUI()` → `{ open, openCart, closeCart, toggleCart }`.
  * `useCartUIOptional()` returns null instead of throwing (how `useAddToCart`
  * integrates without requiring the provider).
  *
@@ -48,9 +29,6 @@ import { useLocation } from "react-router-dom";
 
 const CartUIContext = createContext(null);
 
-/** Layout effect where there is a DOM; plain effect on the server (no warning). */
-const useDrawerEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
-
 /** Internal: closes the drawer whenever the route changes (needs a Router above). */
 function CloseOnNavigate({ close }) {
   const { pathname } = useLocation();
@@ -74,9 +52,6 @@ export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, child
   const openCart = useCallback(() => setOpen(true), []);
   const closeCart = useCallback(() => setOpen(false), []);
   const toggleCart = useCallback(() => setOpen((o) => !o), []);
-  const panelId = useId();
-  const panelRef = useRef(null);
-  const restoreRef = useRef(null);
 
   // Esc closes — the keyboard's way out is Esc and the named close button.
   useEffect(() => {
@@ -88,36 +63,15 @@ export function CartUIProvider({ closeOnNavigate = true, openOnAdd = true, child
     return () => window.removeEventListener("keydown", onKey);
   }, [open]);
 
-  // Focus into the store's panel on open, back where it came from on close, and
-  // a closed-but-mounted panel is inert — all on whatever element the store
-  // attached `panelRef` to, so the drawer's markup and animation stay theirs.
-  // Layout effect: before paint, so an animating panel is never briefly live.
-  useDrawerEffect(() => {
-    const node = panelRef.current;
-    if (open) {
-      restoreRef.current = typeof document !== "undefined" ? document.activeElement : null;
-      if (node) {
-        node.inert = false;
-        node.focus?.({ preventScroll: true });
-      }
-    } else {
-      if (node) node.inert = true;
-      restoreRef.current?.focus?.();
-      restoreRef.current = null;
-    }
-  }, [open]);
-
   const value = useMemo(
     () => ({
       open,
       openCart,
       closeCart,
       toggleCart,
-      panelRef,
-      panelId,
       onItemAdded: openOnAdd ? openCart : null,
     }),
-    [open, openCart, closeCart, toggleCart, panelId, openOnAdd],
+    [open, openCart, closeCart, toggleCart, openOnAdd],
   );
 
   return (

package/src/commerce/storefront/index.js

@@ -35,6 +35,10 @@
  * - `useOrderReturn` — the mandatory `/order-received` page in one hook.
  * - `ShippingMethodPicker` / `PaymentMethodPicker` — render-prop components for
  *     the two checkout choices that are store data, never hardcoded.
+ * - `AddressFields` — the ONE rendered component in the layer: the checkout
+ *     address form (state/province appears per country, `autoComplete` kept,
+ *     required marks arm on blur). Unstyled; style it via `data-part`
+ *     selectors or its `className`/`classes` props.
  *
  * Re-exported from `@/commerce/utils` so one import line covers a page:
  * `variantAxes` (axes → options with selected/disabled/stock derived),
@@ -43,8 +47,10 @@
  * gallery follows the variant selection without owning a second copy of it),
  * `productRibbons` (ribbons are `{id, name}` objects, not strings — rendering
  * one straight into JSX is React's "Objects are not valid as a React child"),
- * `productSpecs` + `findSpec` (meta keys are free text, so featuring a
- * particular spec needs a tolerant lookup, not an equality test),
+ * `productSpecs` + `findSpec` (spec rows carry an inferred render `type` so a
+ * weight reads as a figure and a composition as bars rather than every modifier
+ * as one grey table row; meta keys are free text, so featuring a particular
+ * spec needs a tolerant lookup, not an equality test),
  * `attributesLabel`, `cartTotalsLines` / `orderTotalsLines`,
  * `addressFieldSpec` (the checkout's field list, including the state/province
  * field that silently mis-prices US/CA/AU orders when it is left out), and
@@ -60,23 +66,6 @@
  *
  * The catalog and product surfaces are where the design freedom lives: these
  * hooks hand you resolved data, and the rendering is entirely yours.
- *
- * **Parts** — for the four commodity surfaces only (cart, drawer, checkout,
- * order-received), `Checkout.*` / `Cart.*` / `CartDrawer.*` /
- * `OrderReceived.*` render each section's correct semantic markup with zero
- * copy and zero navigation: you place them in YOUR layout, and supply every
- * word through `labels` (chain: part prop → page Root → `<StorefrontProvider
- * labels={…}>`; a missing key renders a visible `⟨copy: …⟩` placeholder).
- * They carry **layout geometry and nothing else** (`parts/parts.css`: field
- * grids, row and thumbnail sizing, totals rows, the drawer panel — no color,
- * type or border, every rule at zero specificity), so an unstyled store looks
- * unfinished but never broken; the look arrives as your CSS on
- * `data-part`/`data-state`, or via `className`/`classes`. Contract tables, the
- * copy example and the `data-part` inventory: the commerce skill's
- * install/02-storefront.md — use the parts from there, not from these files.
- * They compose the hooks above, so dropping one section down to its hook is
- * normal; they are also the app's own source, editable when a requirement
- * outgrows their props.
  */
 export {
   StorefrontProvider,
@@ -87,9 +76,10 @@ export {
   useCountries,
   useCart,
 } from "./StorefrontProvider";
-export { useCheckout, CheckoutProvider, useCheckoutContext, useInCheckout } from "./useCheckout";
+export { useCheckout, CheckoutProvider, useCheckoutContext } from "./useCheckout";
 export { useOrderReturn, orderReceivedUrl } from "./useOrderReturn";
 export { ShippingMethodPicker, PaymentMethodPicker } from "./pickers";
+export { AddressFields } from "./AddressFields";
 export { CartUIProvider, useCartUI } from "./cartUI";
 export {
   REQUIRED_BILLING_FIELDS,
@@ -98,18 +88,6 @@ export {
   isShippingAddressComplete,
 } from "./address";
 
-// ── parts: guided sections for the commodity surfaces ──────────────────────
-// The parts' layout geometry (field grids, row/media sizing, totals rows, the
-// drawer panel) — structure only, no look, every rule at zero specificity so
-// the store's CSS wins. See parts/parts.css for the custom properties.
-import "./parts/parts.css";
-
-export { Checkout } from "./parts/checkout";
-export { Cart } from "./parts/cart";
-export { CartDrawer } from "./parts/drawer";
-export { OrderReceived } from "./parts/orderReceived";
-export { REQUIRED_LABEL_KEYS } from "./parts/labels";
-
 // ── catalog ────────────────────────────────────────────────────────────────
 export { useProductList, useCategories, useRibbons } from "./useProductList";
 export { useProduct, useAddToCart } from "./useProduct";

package/src/commerce/storefront/useCheckout.jsx

@@ -381,30 +381,3 @@ export function useCheckoutContext() {
 export function useCheckoutContextOptional() {
   return useContext(CheckoutContext);
 }
-
-/**
- * Is this component rendering inside a checkout (`Checkout.Root`, or your own
- * `<CheckoutProvider>`)? For the one component a store writes once and shows in
- * three places — the drawer, the cart page and the checkout's order summary —
- * where a merchandising block belongs in the first two and is a distraction (or
- * a way out of the funnel) in the third:
- *
- *   function CartContents() {
- *     const inCheckout = useInCheckout();
- *     return (
- *       <>
- *         <Cart.Lines />
- *         {!inCheckout && <UpsellRail />}   // your own upsell / related rail
- *         <Cart.Totals />
- *       </>
- *     );
- *   }
- *
- * A boolean, not a mode: nothing in the kit changes behavior from it. Prefer an
- * explicit prop (`<CartContents showUpsell={false} />`) where the caller knows
- * best; this is for the case where it doesn't — a shared component several
- * pages deep.
- */
-export function useInCheckout() {
-  return useContext(CheckoutContext) != null;
-}

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;
+}