@merchi/product-form-sdk 1.0.9

package/README.md

@@ -0,0 +1,177 @@
+# Merchi Product Form SDK
+
+Contract SDK for AI-built and hand-written **custom Merchi product order forms**.
+
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL%203.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+Custom forms are React components that run inside the Merchi dashboard preview and the product embed. This package defines the **only** imports, components, and helpers those forms may use. Source is validated by a static gate and compiled to a browser bundle that externalises `react` and this SDK to `window` globals.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How forms run](#how-forms-run)
+- [Form component contract](#form-component-contract)
+- [Layout and fields](#layout-and-fields)
+- [Group variations](#group-variations)
+- [Pricing and job building](#pricing-and-job-building)
+- [Allowed exports](#allowed-exports)
+- [Development](#development)
+- [License](#license)
+
+## Installation
+
+```bash
+npm install @merchi/product-form-sdk
+```
+
+Peer dependency: `react` ^18 or ^19.
+
+In the Merchi monorepo, the dashboard installs a packed tarball:
+
+```bash
+cd packages/product-form-sdk
+npm run build && npm pack
+cd ../merchi_dashboard && npm install
+```
+
+## Quick start
+
+A minimal form renders independent variation fields and relies on the host shell for quantity, live pricing, and submit actions:
+
+```tsx
+import React from 'react';
+import {
+  Section,
+  Stack,
+  Heading,
+  Text,
+  Field,
+} from '@merchi/product-form-sdk';
+
+export default function Form({ product }) {
+  const fields = product?.independentVariationFields ?? [];
+
+  return (
+    <Stack gap={24}>
+      <Section>
+        <Heading>{product?.name || 'Order form'}</Heading>
+        {product?.description ? <Text muted>{product.description}</Text> : null}
+      </Section>
+      <Section title="Options">
+        <Stack gap={16}>
+          {fields.map((field) => (
+            <Field key={field.id} field={field} />
+          ))}
+        </Stack>
+      </Section>
+    </Stack>
+  );
+}
+```
+
+See `examples/colour-grid-form.tsx` for a per-colour quantity grid (wristbands, multi-SKU products).
+
+## How forms run
+
+1. **Authoring** — Form source is stored as TSX on a `ProductForm` in Merchi.
+2. **Gate** — Only imports from `react` and `@merchi/product-form-sdk` are allowed (legacy `merchi_sdk_product_form` may still be accepted for older drafts).
+3. **Compile** — esbuild bundles the form to an IIFE; `react` → `window.React`, `@merchi/product-form-sdk` → `window.MerchiProductFormSdk`.
+4. **Host** — The dashboard or embed loads the bundle, provides `createProductFormRuntime`, and wraps the form in `ProductFormShell` (quantity control, live quote footer, submit buttons).
+
+Form authors should **not** reimplement quantity controls or pricing footers. To replace Get quote / Buy now / Add to cart, use `ProductFormActions` (or `Form.footerActions`) — do not hand-roll checkout buttons.
+
+## Form component contract
+
+Default-export a React component matching `ProductFormComponent`:
+
+```tsx
+export default function Form({ product, pricing, actions, helpers }) {
+  // product  — ProductJson for the item being ordered
+  // pricing  — request quotes as the user edits (createPricing wrapper)
+  // actions  — submit handlers (addToCart, buyNow, …); may be undefined
+  // helpers  — serializeJob, nonEmptyGroups, formatCurrency, urlFor
+}
+```
+
+Inside composed UI, prefer `useProductForm()` from a `ProductFormProvider` / `ProductFormShell` subtree for quote state and submit wiring.
+
+## Layout and fields
+
+| Export | Purpose |
+|--------|---------|
+| `Section`, `Stack`, `Card` | Page structure |
+| `Heading`, `Text`, `Divider` | Typography |
+| `Field` | Render a product variation field (options, text, files, etc.) |
+| `theme` | Shared spacing/colour tokens |
+
+Loop `product.independentVariationFields` for options that apply to the **whole order** (`job.variations`).
+
+There is **no** `TextInput`, `Select`, `Button`, or `ColorSwatches` — use `Field` and layout components only.
+
+To change the host footer (for example one **Place order** button that opens the Get quote modal):
+
+```tsx
+import { ProductFormActions } from '@merchi/product-form-sdk';
+
+export default function Form({ product }) {
+  return (
+    <Stack gap={24}>
+      <ProductFormActions
+        actions={[{ action: 'getQuote', label: 'Place order', primary: true }]}
+      />
+      {/* layout */}
+    </Stack>
+  );
+}
+Form.footerActions = [{ action: 'getQuote', label: 'Place order', primary: true }];
+```
+
+## Group variations
+
+Some products need **per-batch** choices (e.g. colour × quantity grids):
+
+| Helper / component | When to use |
+|--------------------|-------------|
+| `productHasGroups(product)` | Product has `groupVariationFields` |
+| `isOptionQuantityGridProduct(product)` | Single option-based group field → use grid |
+| `OptionQuantityGrid` | Table: swatch, quantity, row cost, inventory |
+| `GroupRows` | Multiple group fields or free-text group fields |
+| `Field` with `groupIndex` | Field inside a specific batch row |
+
+When groups exist, each batch has its own `quantity` in `job.variationsGroups`. Do not use top-level `job.quantity` — `ProductFormShell` hides the global quantity control for group products.
+
+## Pricing and job building
+
+| Export | Purpose |
+|--------|---------|
+| `createPricing` / `createProductFormRuntime` | Host/runtime wiring (embed & dashboard) |
+| `buildProductFormJob` | Build a `JobJson` from form state |
+| `selectionsToVariations` | Map field selections to variation payloads |
+| `serializeJob` | Strip empty groups before submit |
+| `nonEmptyGroups` | Filter groups with `quantity > 0` |
+| `formatCurrency`, `urlFor` | Display helpers |
+
+## Allowed exports
+
+The compile gate allowlists these **runtime** named imports (type-only imports are erased and not checked):
+
+`SDK_VERSION`, `serializeJob`, `nonEmptyGroups`, `formatCurrency`, `urlFor`, `createPricing`, `createProductFormRuntime`, `productHasGroups`, `groupFieldsOf`, `independentFieldsOf`, `isOptionQuantityGridProduct`, `buildProductFormJob`, `selectionsToVariations`, `Section`, `Stack`, `Card`, `Heading`, `Text`, `Divider`, `Field`, `GroupRows`, `OptionQuantityGrid`, `ProductFormProvider`, `ProductFormShell`, `ProductFormActions`, `useProductForm`, `OPTION_FIELD_TYPES`, `theme`
+
+Keep this list in sync with `src/index.ts` and `merchi_api/common/js/product_form_gate.cjs`.
+
+## Development
+
+```bash
+npm install
+npm run build    # tsc → dist/
+npm test         # jest
+npm run lint     # eslint src
+npm pack         # merchi-product-form-sdk-<version>.tgz
+```
+
+Repository: [github.com/merchisdk/merchi_ts/tree/main/packages/product-form-sdk](https://github.com/merchisdk/merchi_ts/tree/main/packages/product-form-sdk)
+
+## License
+
+GPL-3.0 — see [LICENSE](https://www.gnu.org/licenses/gpl-3.0) (same as [@merchi/sdk](https://www.npmjs.com/package/@merchi/sdk)).

package/dist/components/Field.d.ts

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { VariationFieldJson } from '../types/variation';
+export declare function Field({ field, groupIndex, }: {
+    field?: VariationFieldJson | null;
+    /** When set, reads/writes that batch's group-field selections (see GroupRows). */
+    groupIndex?: number;
+}): React.JSX.Element | null;

package/dist/components/Field.js

@@ -0,0 +1,353 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { useProductForm } from './context';
+import { theme } from './layout';
+import { clampWithAspectRatio, defaultModalityForAreaUnit, displayToMm, estimateAreaCosts, formatAreaSummary, formatAreaValue, mmToDisplay, parseAreaValue, stepInDisplayUnit, unitLabel, } from '../helpers/area';
+import { formatCurrency } from '../helpers/format';
+const FIELD = {
+    TEXT_INPUT: 1,
+    SELECT: 2,
+    FILE_UPLOAD: 3,
+    TEXT_AREA: 4,
+    NUMBER_INPUT: 5,
+    CHECKBOX: 6,
+    RADIO: 7,
+    FIELD_INSTRUCTIONS: 8,
+    IMAGE_SELECT: 9,
+    COLOUR_PICKER: 10,
+    COLOUR_SELECT: 11,
+    TURNAROUND_TIME: 12,
+    COLOUR_EXTRACT: 13,
+    AREA: 14,
+};
+function Label({ field }) {
+    if (!field.name)
+        return null;
+    return (_jsxs("label", { style: {
+            fontFamily: theme.font,
+            fontSize: 14,
+            fontWeight: 700,
+            color: theme.text,
+            marginBottom: 8,
+            display: 'block',
+        }, children: [field.name, field.required ? _jsx("span", { style: { color: theme.primary }, children: " *" }) : null] }));
+}
+function inputStyle() {
+    return {
+        width: '100%',
+        padding: '10px 12px',
+        fontFamily: theme.font,
+        fontSize: 14,
+        color: theme.text,
+        background: theme.card,
+        border: `1px solid ${theme.border}`,
+        borderRadius: 8,
+        outline: 'none',
+        boxSizing: 'border-box',
+    };
+}
+function visibleOptions(field) {
+    return (field.options || []).filter((o) => o?.isVisible !== false);
+}
+function AreaFieldControl({ field, value, onChange, }) {
+    const areaUnit = (field.areaUnit || 'mm');
+    const aspectLocked = Boolean(field.aspectRatioLock && field.aspectRatio);
+    const aspectRatio = Number(field.aspectRatio) || 0;
+    const [modality, setModality] = useState(() => defaultModalityForAreaUnit(areaUnit));
+    const parsed = parseAreaValue(value);
+    const heightMm = parsed?.heightMm ?? 0;
+    const widthMm = parsed?.widthMm ?? 0;
+    const heightDisplay = heightMm ? mmToDisplay(heightMm, modality, areaUnit) : '';
+    const widthDisplay = widthMm ? mmToDisplay(widthMm, modality, areaUnit) : '';
+    const label = unitLabel(modality, areaUnit);
+    const summary = useMemo(() => formatAreaSummary(value, modality, areaUnit), [value, modality, areaUnit]);
+    const costDetail = useMemo(() => {
+        const estimated = estimateAreaCosts(field, value);
+        if (!estimated)
+            return '';
+        const currency = field.currency || 'AUD';
+        const parts = [];
+        if (estimated.onceOffCost > 0) {
+            parts.push(`${formatCurrency(estimated.onceOffCost, currency)} once off`);
+        }
+        if (estimated.unitCost > 0) {
+            parts.push(`${formatCurrency(estimated.unitCost, currency)} per unit`);
+        }
+        return parts.length ? `+ ${parts.join(', ')}` : '';
+    }, [field, value]);
+    const commitMm = (nextHeightMm, nextWidthMm, changed) => {
+        let h = nextHeightMm;
+        let w = nextWidthMm;
+        if (aspectLocked && aspectRatio > 0) {
+            const clamped = clampWithAspectRatio({
+                heightMm: h,
+                widthMm: w,
+                changed,
+                aspectRatio,
+                heightMin: field.heightFieldMin ?? null,
+                heightMax: field.heightFieldMax ?? null,
+                widthMin: field.widthFieldMin ?? null,
+                widthMax: field.widthFieldMax ?? null,
+            });
+            h = clamped.heightMm;
+            w = clamped.widthMm;
+        }
+        if (!Number.isFinite(h) || !Number.isFinite(w) || h <= 0 || w <= 0) {
+            onChange('');
+            return;
+        }
+        onChange(formatAreaValue(h, w));
+    };
+    const updateHeight = (raw) => {
+        if (raw === '') {
+            onChange('');
+            return;
+        }
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n <= 0)
+            return;
+        const mm = displayToMm(n, modality, areaUnit);
+        commitMm(mm, widthMm > 0 ? widthMm : mm * (aspectRatio || 1), 'height');
+    };
+    const updateWidth = (raw) => {
+        if (raw === '') {
+            onChange('');
+            return;
+        }
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n <= 0)
+            return;
+        const mm = displayToMm(n, modality, areaUnit);
+        commitMm(heightMm > 0 ? heightMm : mm / (aspectRatio || 1), mm, 'width');
+    };
+    const step = stepInDisplayUnit(field.areaStep, modality, areaUnit);
+    return (_jsxs("div", { children: [_jsxs("div", { style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 8,
+                    marginBottom: 8,
+                    flexWrap: 'wrap',
+                }, children: [_jsx("span", { style: {
+                            fontFamily: theme.font,
+                            fontSize: 13,
+                            fontWeight: modality === 'metric' ? 600 : 400,
+                            color: modality === 'metric' ? theme.text : theme.muted,
+                        }, children: "Metric" }), _jsx("button", { type: "button", role: "switch", "aria-checked": modality === 'imperial', "aria-label": "Use imperial units", onClick: () => setModality(modality === 'metric' ? 'imperial' : 'metric'), style: {
+                            position: 'relative',
+                            width: 36,
+                            height: 20,
+                            padding: 0,
+                            border: 'none',
+                            borderRadius: 999,
+                            background: modality === 'imperial' ? theme.primary || '#0d6efd' : '#ced4da',
+                            cursor: 'pointer',
+                            flexShrink: 0,
+                        }, children: _jsx("span", { style: {
+                                position: 'absolute',
+                                top: 2,
+                                left: modality === 'imperial' ? 18 : 2,
+                                width: 16,
+                                height: 16,
+                                borderRadius: '50%',
+                                background: '#fff',
+                                boxShadow: '0 1px 2px rgba(0,0,0,0.2)',
+                                transition: 'left 0.15s ease',
+                            } }) }), _jsx("span", { style: {
+                            fontFamily: theme.font,
+                            fontSize: 13,
+                            fontWeight: modality === 'imperial' ? 600 : 400,
+                            color: modality === 'imperial' ? theme.text : theme.muted,
+                        }, children: "Imperial" }), aspectLocked ? (_jsx("span", { style: {
+                            marginLeft: 'auto',
+                            fontFamily: theme.font,
+                            fontSize: 12,
+                            color: theme.muted,
+                        }, children: "Aspect ratio locked" })) : null] }), _jsxs("div", { style: { display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 12 }, children: [_jsxs("label", { style: { display: 'flex', flexDirection: 'column', gap: 4 }, children: [_jsxs("span", { style: { fontFamily: theme.font, fontSize: 13, color: theme.muted }, children: ["Height (", label, ")"] }), _jsx("input", { type: "number", value: heightDisplay === '' ? '' : heightDisplay, onChange: (e) => updateHeight(e.target.value), step: step, style: inputStyle(), "aria-label": `${field.name || 'Area'} height` })] }), _jsxs("label", { style: { display: 'flex', flexDirection: 'column', gap: 4 }, children: [_jsxs("span", { style: { fontFamily: theme.font, fontSize: 13, color: theme.muted }, children: ["Width (", label, ")"] }), _jsx("input", { type: "number", value: widthDisplay === '' ? '' : widthDisplay, onChange: (e) => updateWidth(e.target.value), step: step, style: inputStyle(), "aria-label": `${field.name || 'Area'} width` })] })] }), summary ? (_jsxs("div", { style: { marginTop: 8 }, children: [_jsx("p", { style: {
+                            fontFamily: theme.font,
+                            fontSize: 13,
+                            color: theme.muted,
+                            margin: 0,
+                        }, children: summary }), costDetail ? (_jsx("p", { style: {
+                            fontFamily: theme.font,
+                            fontSize: 12,
+                            color: theme.muted,
+                            margin: '4px 0 0',
+                        }, children: costDetail })) : null] })) : null] }));
+}
+export function Field({ field, groupIndex, }) {
+    const { selections, setFieldSelection, groups, setGroupFieldSelection, } = useProductForm();
+    if (!field || field.id === undefined)
+        return null;
+    const fieldId = field.id;
+    const isGroupField = groupIndex !== undefined;
+    const current = isGroupField
+        ? groups[groupIndex]?.selections[fieldId]
+        : selections[fieldId];
+    const fieldType = Number(field.fieldType);
+    const selectedIds = current?.selectedOptionIds ?? [];
+    const applySelection = (sel) => {
+        if (isGroupField) {
+            setGroupFieldSelection(groupIndex, fieldId, sel);
+        }
+        else {
+            setFieldSelection(fieldId, sel);
+        }
+    };
+    const selectSingle = (optionId) => applySelection({
+        value: String(optionId),
+        selectedOptionIds: [optionId],
+    });
+    const toggleMulti = (optionId) => {
+        const next = selectedIds.includes(optionId)
+            ? selectedIds.filter((id) => id !== optionId)
+            : [...selectedIds, optionId];
+        applySelection({
+            value: next.join(','),
+            selectedOptionIds: next,
+        });
+    };
+    const setText = (value) => applySelection({ value, selectedOptionIds: [] });
+    // ── Image select ────────────────────────────────────────────────
+    if (fieldType === FIELD.IMAGE_SELECT) {
+        const opts = visibleOptions(field);
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("div", { style: {
+                        display: 'grid',
+                        gridTemplateColumns: 'repeat(auto-fill, minmax(150px, 1fr))',
+                        gap: 12,
+                    }, children: opts.map((o) => {
+                        const checked = o.id !== undefined && selectedIds.includes(o.id);
+                        const available = o.available !== false;
+                        return (_jsxs("button", { type: "button", disabled: !available, onClick: () => o.id !== undefined && selectSingle(o.id), style: {
+                                position: 'relative',
+                                textAlign: 'center',
+                                padding: 12,
+                                background: theme.card,
+                                border: `2px solid ${checked ? theme.primary : theme.border}`,
+                                borderRadius: theme.radius,
+                                cursor: available ? 'pointer' : 'not-allowed',
+                                opacity: available ? 1 : 0.45,
+                                transition: 'border-color 0.15s ease, box-shadow 0.15s ease',
+                            }, children: [o.linkedFile?.viewUrl ? (_jsx("img", { src: o.linkedFile.viewUrl, alt: o.value || '', style: {
+                                        display: 'block',
+                                        width: '100%',
+                                        height: 130,
+                                        objectFit: 'contain',
+                                        margin: '0 auto 8px',
+                                    } })) : null, _jsx("span", { style: {
+                                        display: 'block',
+                                        fontFamily: theme.font,
+                                        fontSize: 13,
+                                        fontWeight: 500,
+                                        color: theme.text,
+                                    }, children: o.value }), checked ? (_jsx("span", { style: {
+                                        position: 'absolute',
+                                        top: 8,
+                                        right: 8,
+                                        width: 20,
+                                        height: 20,
+                                        borderRadius: '50%',
+                                        background: theme.primary,
+                                        color: theme.primaryText,
+                                        fontSize: 13,
+                                        lineHeight: '20px',
+                                    }, children: "\u2713" })) : null] }, o.id));
+                    }) })] }));
+    }
+    // ── Colour select ───────────────────────────────────────────────
+    if (fieldType === FIELD.COLOUR_SELECT) {
+        const opts = visibleOptions(field);
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 12 }, children: opts.map((o) => {
+                        const checked = o.id !== undefined && selectedIds.includes(o.id);
+                        return (_jsxs("button", { type: "button", title: o.value, onClick: () => o.id !== undefined && selectSingle(o.id), style: {
+                                display: 'flex',
+                                flexDirection: 'column',
+                                alignItems: 'center',
+                                gap: 4,
+                                background: 'transparent',
+                                border: 'none',
+                                cursor: 'pointer',
+                            }, children: [_jsx("span", { style: {
+                                        width: 36,
+                                        height: 36,
+                                        borderRadius: '50%',
+                                        background: o.colour || '#ccc',
+                                        boxShadow: checked
+                                            ? `0 0 0 2px ${theme.card}, 0 0 0 4px ${theme.primary}`
+                                            : `0 0 0 1px ${theme.border}`,
+                                    } }), _jsx("span", { style: { fontFamily: theme.font, fontSize: 11, color: theme.muted }, children: o.value })] }, o.id));
+                    }) })] }));
+    }
+    // ── Select dropdown ─────────────────────────────────────────────
+    if (fieldType === FIELD.SELECT) {
+        const opts = visibleOptions(field);
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsxs("select", { value: selectedIds[0] !== undefined ? String(selectedIds[0]) : '', onChange: (e) => selectSingle(Number(e.target.value)), style: inputStyle(), children: [_jsx("option", { value: "", disabled: true, children: "Select\u2026" }), opts.map((o) => (_jsx("option", { value: o.id, children: o.value }, o.id)))] })] }));
+    }
+    // ── Radio ───────────────────────────────────────────────────────
+    if (fieldType === FIELD.RADIO) {
+        const opts = visibleOptions(field);
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: 8 }, children: opts.map((o) => (_jsxs("label", { style: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 8,
+                            fontFamily: theme.font,
+                            fontSize: 14,
+                            color: theme.text,
+                            cursor: 'pointer',
+                        }, children: [_jsx("input", { type: "radio", name: `field-${fieldId}`, checked: o.id !== undefined && selectedIds.includes(o.id), onChange: () => o.id !== undefined && selectSingle(o.id) }), o.value] }, o.id))) })] }));
+    }
+    // ── Checkbox (multi) ────────────────────────────────────────────
+    if (fieldType === FIELD.CHECKBOX) {
+        const opts = visibleOptions(field);
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: 8 }, children: opts.map((o) => (_jsxs("label", { style: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 8,
+                            fontFamily: theme.font,
+                            fontSize: 14,
+                            color: theme.text,
+                            cursor: 'pointer',
+                        }, children: [_jsx("input", { type: "checkbox", checked: o.id !== undefined && selectedIds.includes(o.id), onChange: () => o.id !== undefined && toggleMulti(o.id) }), o.value] }, o.id))) })] }));
+    }
+    // ── Text / number / textarea / colour picker ────────────────────
+    if (fieldType === FIELD.TEXT_AREA) {
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("textarea", { value: current?.value ?? '', onChange: (e) => setText(e.target.value), rows: 3, style: { ...inputStyle(), resize: 'vertical' } })] }));
+    }
+    if (fieldType === FIELD.NUMBER_INPUT) {
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("input", { type: "number", value: current?.value ?? '', onChange: (e) => setText(e.target.value), style: inputStyle() })] }));
+    }
+    if (fieldType === FIELD.AREA) {
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx(AreaFieldControl, { field: field, value: current?.value ?? '', onChange: setText })] }));
+    }
+    if (fieldType === FIELD.COLOUR_PICKER) {
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("input", { type: "color", value: current?.value || '#000000', onChange: (e) => setText(e.target.value), style: { width: 48, height: 36, border: 'none', background: 'none' } })] }));
+    }
+    if (fieldType === FIELD.FIELD_INSTRUCTIONS) {
+        return (_jsx("div", { children: _jsx(Label, { field: field }) }));
+    }
+    // TEXT_INPUT (default) + unsupported-in-preview types fall back to a text box.
+    if (fieldType === FIELD.FILE_UPLOAD ||
+        fieldType === FIELD.TURNAROUND_TIME ||
+        fieldType === FIELD.COLOUR_EXTRACT) {
+        const message = fieldType === FIELD.FILE_UPLOAD
+            ? 'File upload is available on the live store.'
+            : fieldType === FIELD.COLOUR_EXTRACT
+                ? 'Colour extract (upload artwork and edit extracted colours) is available on the live store.'
+                : 'Turnaround options are available on the live store.';
+        const selectedColours = (current?.selectedOptions || []).filter((option) => option.colour || option.value);
+        return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("p", { style: { fontFamily: theme.font, fontSize: 13, color: theme.muted, margin: 0 }, children: message }), fieldType === FIELD.COLOUR_EXTRACT && selectedColours.length > 0 ? (_jsx("div", { style: { display: 'flex', flexWrap: 'wrap', gap: 8, marginTop: 10 }, children: selectedColours.map((option, index) => (_jsxs("span", { style: {
+                            display: 'inline-flex',
+                            alignItems: 'center',
+                            gap: 6,
+                            fontFamily: theme.font,
+                            fontSize: 12,
+                            color: theme.text,
+                        }, children: [_jsx("span", { style: {
+                                    width: 18,
+                                    height: 18,
+                                    borderRadius: 4,
+                                    background: option.colour || option.value || '#ccc',
+                                    border: `1px solid ${theme.border}`,
+                                } }), (option.colour || option.value || '').toUpperCase()] }, option.id ?? index))) })) : null] }));
+    }
+    return (_jsxs("div", { children: [_jsx(Label, { field: field }), _jsx("input", { type: "text", value: current?.value ?? '', onChange: (e) => setText(e.target.value), style: inputStyle() })] }));
+}

package/dist/components/ProductFormActions.d.ts

@@ -0,0 +1,11 @@
+import { FooterAction } from './footerActions';
+/**
+ * Configure the host ProductFormShell footer from form source.
+ * Render as the first child of the default-exported form.
+ *
+ * Example — one "Place order" button that opens the Get quote modal:
+ *   <ProductFormActions actions={[{ action: 'getQuote', label: 'Place order', primary: true }]} />
+ */
+export declare function ProductFormActions({ actions }: {
+    actions: FooterAction[];
+}): null;

package/dist/components/ProductFormActions.js

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import { useProductForm } from './context';
+import { normalizeFooterActions } from './footerActions';
+/**
+ * Configure the host ProductFormShell footer from form source.
+ * Render as the first child of the default-exported form.
+ *
+ * Example — one "Place order" button that opens the Get quote modal:
+ *   <ProductFormActions actions={[{ action: 'getQuote', label: 'Place order', primary: true }]} />
+ */
+export function ProductFormActions({ actions }) {
+    const { setFooterActions } = useProductForm();
+    const key = JSON.stringify(actions);
+    const normalized = React.useMemo(() => normalizeFooterActions(actions), [key]);
+    React.useLayoutEffect(() => {
+        setFooterActions(normalized);
+        return () => setFooterActions(null);
+    }, [normalized, setFooterActions]);
+    return null;
+}

package/dist/components/context.d.ts

@@ -0,0 +1,85 @@
+import * as React from 'react';
+import { ProductJson } from '../types/product';
+import { JobJson } from '../types/job';
+import { VariationFieldJson } from '../types/variation';
+import { Pricing } from '../runtime/pricing';
+import { Actions, Helpers } from '../runtime/runtime';
+import { GroupRow } from '../helpers/buildJob';
+import { OPTION_FIELD_TYPES } from '../helpers/constants';
+import { FooterAction, type SubmitAction } from './footerActions';
+export { OPTION_FIELD_TYPES };
+export type { FooterAction, SubmitAction } from './footerActions';
+export interface FieldSelection {
+    /** Comma-separated option ids (selectable fields) or the raw text/number. */
+    value: string;
+    selectedOptionIds: number[];
+    /** Uploaded files for file / colour-extract fields. */
+    variationFiles?: Array<{
+        id?: string;
+        name?: string;
+        viewUrl?: string;
+    }>;
+    /** Selected option rows (used by colour-extract for colour/value edits). */
+    selectedOptions?: Array<{
+        id?: number;
+        value?: string;
+        colour?: string;
+        isExtracted?: boolean;
+    }>;
+}
+export interface ProductFormContextValue {
+    product: ProductJson;
+    hasGroups: boolean;
+    /** True when one group field has options — prefer OptionQuantityGrid. */
+    optionQuantityGrid: boolean;
+    groupFields: VariationFieldJson[];
+    independentFields: VariationFieldJson[];
+    quantity: number;
+    setQuantity: (n: number) => void;
+    /** Selections for independent (whole-order) variation fields. */
+    selections: Record<number, FieldSelection>;
+    setFieldSelection: (fieldId: number, sel: FieldSelection) => void;
+    /** Per-batch group rows (multi group-field products). */
+    groups: GroupRow[];
+    setGroupQuantity: (index: number, quantity: number) => void;
+    setGroupFieldSelection: (groupIndex: number, fieldId: number, sel: FieldSelection) => void;
+    addGroup: () => void;
+    removeGroup: (index: number) => void;
+    /** Per-option quantities for single group-field grid products. */
+    optionQuantities: Record<number, number>;
+    setOptionQuantity: (optionId: number, quantity: number) => void;
+    quote: JobJson | null;
+    loading: boolean;
+    currency?: string;
+    helpers: Helpers;
+    /** Which submit actions the host enabled. */
+    available: {
+        addToCart: boolean;
+        buyNow: boolean;
+        getQuote: boolean;
+    };
+    /** Optional overrides for footer button labels. */
+    actionLabels: Partial<Record<SubmitAction, string>>;
+    /** Form-configured footer buttons; null uses the default Get quote / Buy now / Add to cart set. */
+    footerActions: FooterAction[] | null;
+    /** Replace or clear the host footer buttons from form source. */
+    setFooterActions: (actions: FooterAction[] | null) => void;
+    /** Build the current job and invoke the given host action. */
+    submit: (action: SubmitAction) => void;
+}
+export declare function useProductForm(): ProductFormContextValue;
+export interface ProductFormProviderProps {
+    product: ProductJson;
+    pricing: Pricing;
+    actions: Actions;
+    helpers: Helpers;
+    children: React.ReactNode;
+    /** Optional cart-item / quote job used to hydrate quantity and selections. */
+    initialJob?: JobJson | null;
+    /** Override footer button labels (e.g. cart edit: addToCart → "Save"). */
+    actionLabels?: Partial<Record<SubmitAction, string>>;
+    /** Restrict / relabel host footer buttons. Host labels still win when set. */
+    footerActions?: FooterAction[] | null;
+}
+export declare function ProductFormProvider({ product, pricing, actions, helpers, children, initialJob, actionLabels, footerActions: footerActionsProp, }: ProductFormProviderProps): React.JSX.Element;
+export type { GroupRow };