@merchi/product-form-sdk 1.0.9

package/dist/components/shell.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from 'react';
+import { ProductFormProvider, useProductForm, } from './context';
+import { theme } from './layout';
+import { productHasGroups } from '../helpers/product';
+import { footerActionsFromComponent, resolveFooterActions, } from './footerActions';
+function QuantityControl() {
+    const { product, quantity, setQuantity } = useProductForm();
+    if (productHasGroups(product))
+        return null;
+    const min = Number(product.minOrderQuantity ?? product.minimum) || 1;
+    return (_jsxs("div", { children: [_jsx("label", { style: {
+                    display: 'block',
+                    fontFamily: theme.font,
+                    fontSize: 14,
+                    fontWeight: 700,
+                    color: theme.text,
+                    marginBottom: 8,
+                }, children: "Quantity" }), _jsx("input", { type: "number", min: min, value: quantity, onChange: (e) => setQuantity(Math.max(min, parseInt(e.target.value, 10) || min)), style: {
+                    width: 160,
+                    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 btn(primary) {
+    return {
+        padding: '10px 18px',
+        fontFamily: theme.font,
+        fontSize: 14,
+        fontWeight: 700,
+        borderRadius: 8,
+        cursor: 'pointer',
+        border: `1px solid ${primary ? theme.primary : theme.border}`,
+        background: primary ? theme.primary : theme.card,
+        color: primary ? theme.primaryText : theme.text,
+    };
+}
+function Footer() {
+    const { quote, loading, currency, helpers, available, actionLabels, footerActions, submit, } = useProductForm();
+    const total = quote?.totalCost;
+    const unit = quote?.costPerUnit;
+    const fmt = (n) => typeof n === 'number' ? helpers.formatCurrency(n, currency) : '—';
+    const buttons = resolveFooterActions({
+        available,
+        actionLabels,
+        footerActions,
+    });
+    return (_jsxs("div", { style: {
+            borderTop: `1px solid ${theme.border}`,
+            paddingTop: 20,
+            display: 'flex',
+            flexWrap: 'wrap',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            gap: 16,
+        }, children: [_jsxs("div", { children: [_jsxs("div", { style: {
+                            fontFamily: theme.font,
+                            fontSize: 12,
+                            textTransform: 'uppercase',
+                            letterSpacing: '0.06em',
+                            color: theme.muted,
+                        }, children: ["Total ", loading ? '· updating…' : ''] }), _jsx("div", { style: {
+                            fontFamily: theme.font,
+                            fontSize: 26,
+                            fontWeight: 800,
+                            color: theme.text,
+                        }, children: fmt(total) }), typeof unit === 'number' ? (_jsxs("div", { style: { fontFamily: theme.font, fontSize: 13, color: theme.muted }, children: [fmt(unit), " per unit"] })) : null] }), _jsx("div", { style: { display: 'flex', gap: 10, flexWrap: 'wrap' }, children: buttons.map((item) => (_jsx("button", { type: "button", style: btn(!!item.primary), onClick: () => submit(item.action), children: item.label }, item.action))) })] }));
+}
+/**
+ * Wraps a custom form: provides the form context (state + live pricing) and
+ * renders a quantity control above and a total + submit footer below the form's
+ * own content. Hosts render this around the form's default export.
+ *
+ * If `product` is omitted, render children only. AI-built forms sometimes nest
+ * `<ProductFormShell>` without props; the host already provided the real shell,
+ * so a second Provider with undefined product would crash and fall back to the
+ * default GroupRows form.
+ */
+export function ProductFormShell({ product, pricing, actions, helpers, children, initialJob, actionLabels, footerActions: footerActionsProp, }) {
+    if (product == null || pricing == null || actions == null || helpers == null) {
+        return _jsx(_Fragment, { children: children });
+    }
+    const childFooterActions = React.Children.count(children) === 1 && React.isValidElement(children)
+        ? footerActionsFromComponent(children.type)
+        : null;
+    const footerActions = footerActionsProp ?? childFooterActions;
+    return (_jsx(ProductFormProvider, { product: product, pricing: pricing, actions: actions, helpers: helpers, initialJob: initialJob, actionLabels: actionLabels, footerActions: footerActions, children: _jsxs("div", { style: {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 24,
+                fontFamily: theme.font,
+            }, children: [_jsx(QuantityControl, {}), children, _jsx(Footer, {})] }) }));
+}

package/dist/helpers/area.d.ts

@@ -0,0 +1,90 @@
+/** Shared helpers for Area (height × width) variation fields. Stored value is always millimetres. */
+export type AreaUnit = 'mm' | 'cm' | 'm' | 'in' | 'ft';
+export type AreaInputType = 'input' | 'slider';
+export type DisplayModality = 'metric' | 'imperial';
+export declare function parseAreaValue(value: string | null | undefined): {
+    heightMm: number;
+    widthMm: number;
+} | null;
+export declare function formatAreaValue(heightMm: number, widthMm: number): string;
+export declare function isImperialUnit(unit: AreaUnit | string | null | undefined): boolean;
+export declare function normaliseAreaUnit(unit?: string | null): AreaUnit;
+/** Imperial for en-US / en-LR / en-MM; otherwise metric (incl. en-GB). */
+export declare function localePrefersImperial(locale?: string): boolean;
+/** Millimetres per one unit of the given area unit. */
+export declare function unitFactorMm(unit?: AreaUnit | string): number;
+/** @deprecated use unitFactorMm */
+export declare function metricUnitFactor(unit?: AreaUnit): number;
+export declare function mmToUnit(mm: number, unit?: AreaUnit | string): number;
+export declare function unitToMm(value: number, unit?: AreaUnit | string): number;
+/** @deprecated use mmToUnit */
+export declare function mmToMetricDisplay(mm: number, unit?: AreaUnit): number;
+/** @deprecated use unitToMm */
+export declare function metricDisplayToMm(value: number, unit?: AreaUnit): number;
+export declare function mmToInches(mm: number): number;
+export declare function inchesToMm(inches: number): number;
+/**
+ * Unit shown for the current buyer modality.
+ * Metric → field unit if metric, else mm.
+ * Imperial → field unit if imperial, else inches.
+ */
+export declare function activeDisplayUnit(modality: DisplayModality, areaUnit?: AreaUnit | string): AreaUnit;
+export declare function defaultModalityForAreaUnit(areaUnit?: AreaUnit | string): DisplayModality;
+export declare function mmToDisplay(mm: number, modality: DisplayModality, areaUnit?: AreaUnit | string): number;
+export declare function displayToMm(value: number, modality: DisplayModality, areaUnit?: AreaUnit | string): number;
+export declare function unitLabel(modality: DisplayModality, areaUnit?: AreaUnit | string): string;
+export declare function defaultAreaStep(unit?: AreaUnit | string): number;
+/**
+ * Step for inputs/sliders in the current display unit.
+ * `stepMm` is the admin-configured step stored in millimetres.
+ */
+export declare function stepInDisplayUnit(stepMm: number | null | undefined, modality: DisplayModality, areaUnit?: AreaUnit | string): number;
+/** Format a length in mm for buyer-facing summary. */
+export declare function formatLengthFromMm(mm: number, modality: DisplayModality, areaUnit?: AreaUnit | string): string;
+export declare function formatAreaParts(value: string | null | undefined, modality?: DisplayModality, areaUnit?: AreaUnit | string): {
+    width: string;
+    height: string;
+    areaLabel: string;
+} | null;
+export declare function formatAreaSummary(value: string | null | undefined, modality?: DisplayModality, areaUnit?: AreaUnit | string): string | null;
+export declare function clamp(n: number, min?: number | null, max?: number | null): number;
+interface AreaCostVariationField {
+    areaUnit?: AreaUnit | string | null;
+    area_unit?: AreaUnit | string | null;
+    heightVariationCost?: number | string | null;
+    height_variation_cost?: number | string | null;
+    widthVariationCost?: number | string | null;
+    width_variation_cost?: number | string | null;
+    heightVariationUnitCost?: number | string | null;
+    height_variation_unit_cost?: number | string | null;
+    widthVariationUnitCost?: number | string | null;
+    width_variation_unit_cost?: number | string | null;
+}
+/**
+ * Client-side Area cost estimate (pre-discount), matching API formula:
+ * onceOff = heightCost × widthCost × height_u × width_u
+ * unitCost = heightUnit × widthUnit × height_u × width_u
+ * (dimensions expressed in the field's areaUnit)
+ */
+export declare function estimateAreaCosts(variationField: AreaCostVariationField, value: string | null | undefined): {
+    onceOffCost: number;
+    unitCost: number;
+} | null;
+/**
+ * Keep width/height linked by aspectRatio (width/height).
+ * `changed` indicates which dimension the user edited.
+ */
+export declare function clampWithAspectRatio(args: {
+    heightMm: number;
+    widthMm: number;
+    changed: 'height' | 'width';
+    aspectRatio: number;
+    heightMin?: number | null;
+    heightMax?: number | null;
+    widthMin?: number | null;
+    widthMax?: number | null;
+}): {
+    heightMm: number;
+    widthMm: number;
+};
+export {};

package/dist/helpers/area.js

@@ -0,0 +1,287 @@
+/** Shared helpers for Area (height × width) variation fields. Stored value is always millimetres. */
+const MM_PER_INCH = 25.4;
+const MM_PER_FOOT = 304.8;
+const MM_PER_CM = 10;
+const MM_PER_M = 1000;
+export function parseAreaValue(value) {
+    if (value == null)
+        return null;
+    const text = String(value).trim();
+    if (!text)
+        return null;
+    const parts = text.split(',').map((p) => p.trim());
+    if (parts.length !== 2)
+        return null;
+    const heightMm = Number(parts[0]);
+    const widthMm = Number(parts[1]);
+    if (!Number.isFinite(heightMm) || !Number.isFinite(widthMm))
+        return null;
+    if (heightMm <= 0 || widthMm <= 0)
+        return null;
+    return { heightMm, widthMm };
+}
+export function formatAreaValue(heightMm, widthMm) {
+    const h = Number(heightMm);
+    const w = Number(widthMm);
+    if (!Number.isFinite(h) || !Number.isFinite(w) || h <= 0 || w <= 0)
+        return '';
+    return `${trimNum(h)},${trimNum(w)}`;
+}
+function trimNum(n) {
+    return String(Number(n.toFixed(6)));
+}
+export function isImperialUnit(unit) {
+    const u = String(unit || 'mm').toLowerCase();
+    return u === 'in' || u === 'ft';
+}
+export function normaliseAreaUnit(unit) {
+    const u = String(unit || 'mm').toLowerCase();
+    if (u === 'cm' || u === 'm' || u === 'in' || u === 'ft' || u === 'mm') {
+        return u;
+    }
+    return 'mm';
+}
+/** Imperial for en-US / en-LR / en-MM; otherwise metric (incl. en-GB). */
+export function localePrefersImperial(locale) {
+    const lang = locale ||
+        (typeof navigator !== 'undefined' ? navigator.language : undefined) ||
+        '';
+    const normalized = lang.toLowerCase().replace('_', '-');
+    return (normalized === 'en-us' ||
+        normalized === 'en-lr' ||
+        normalized === 'en-mm' ||
+        normalized.endsWith('-us') ||
+        normalized.endsWith('-lr') ||
+        normalized.endsWith('-mm'));
+}
+/** Millimetres per one unit of the given area unit. */
+export function unitFactorMm(unit = 'mm') {
+    switch (normaliseAreaUnit(unit)) {
+        case 'cm':
+            return MM_PER_CM;
+        case 'm':
+            return MM_PER_M;
+        case 'in':
+            return MM_PER_INCH;
+        case 'ft':
+            return MM_PER_FOOT;
+        default:
+            return 1;
+    }
+}
+/** @deprecated use unitFactorMm */
+export function metricUnitFactor(unit = 'mm') {
+    return unitFactorMm(unit);
+}
+export function mmToUnit(mm, unit = 'mm') {
+    return mm / unitFactorMm(unit);
+}
+export function unitToMm(value, unit = 'mm') {
+    return value * unitFactorMm(unit);
+}
+/** @deprecated use mmToUnit */
+export function mmToMetricDisplay(mm, unit = 'mm') {
+    return mmToUnit(mm, unit);
+}
+/** @deprecated use unitToMm */
+export function metricDisplayToMm(value, unit = 'mm') {
+    return unitToMm(value, unit);
+}
+export function mmToInches(mm) {
+    return mm / MM_PER_INCH;
+}
+export function inchesToMm(inches) {
+    return inches * MM_PER_INCH;
+}
+/**
+ * Unit shown for the current buyer modality.
+ * Metric → field unit if metric, else mm.
+ * Imperial → field unit if imperial, else inches.
+ */
+export function activeDisplayUnit(modality, areaUnit = 'mm') {
+    const unit = normaliseAreaUnit(areaUnit);
+    if (modality === 'imperial') {
+        return isImperialUnit(unit) ? unit : 'in';
+    }
+    return isImperialUnit(unit) ? 'mm' : unit;
+}
+export function defaultModalityForAreaUnit(areaUnit = 'mm') {
+    if (isImperialUnit(areaUnit))
+        return 'imperial';
+    return localePrefersImperial() ? 'imperial' : 'metric';
+}
+export function mmToDisplay(mm, modality, areaUnit = 'mm') {
+    return mmToUnit(mm, activeDisplayUnit(modality, areaUnit));
+}
+export function displayToMm(value, modality, areaUnit = 'mm') {
+    return unitToMm(value, activeDisplayUnit(modality, areaUnit));
+}
+export function unitLabel(modality, areaUnit = 'mm') {
+    return activeDisplayUnit(modality, areaUnit);
+}
+export function defaultAreaStep(unit = 'mm') {
+    switch (normaliseAreaUnit(unit)) {
+        case 'm':
+            return 0.001;
+        case 'cm':
+            return 0.1;
+        case 'in':
+            return 0.125;
+        case 'ft':
+            return 0.01;
+        default:
+            return 1;
+    }
+}
+/**
+ * Step for inputs/sliders in the current display unit.
+ * `stepMm` is the admin-configured step stored in millimetres.
+ */
+export function stepInDisplayUnit(stepMm, modality, areaUnit = 'mm') {
+    const unit = activeDisplayUnit(modality, areaUnit);
+    const raw = Number(stepMm);
+    if (Number.isFinite(raw) && raw > 0) {
+        return raw / unitFactorMm(unit);
+    }
+    return defaultAreaStep(unit);
+}
+function decimalsForUnit(unit) {
+    if (unit === 'm')
+        return 4;
+    if (unit === 'ft')
+        return 3;
+    if (unit === 'in' || unit === 'cm')
+        return 2;
+    return 2;
+}
+/** Format a length in mm for buyer-facing summary. */
+export function formatLengthFromMm(mm, modality, areaUnit = 'mm') {
+    const unit = activeDisplayUnit(modality, areaUnit);
+    if (unit === 'ft') {
+        const feet = mmToUnit(mm, 'ft');
+        return `${trimNum(Number(feet.toFixed(3)))} ft`;
+    }
+    if (unit === 'in') {
+        const inches = mmToInches(mm);
+        if (inches >= 12) {
+            const feet = Math.floor(inches / 12);
+            const rem = inches - feet * 12;
+            if (rem < 0.05)
+                return `${feet} ft`;
+            return `${feet} ft ${trimNum(Number(rem.toFixed(2)))} in`;
+        }
+        return `${trimNum(Number(inches.toFixed(2)))} in`;
+    }
+    const display = mmToUnit(mm, unit);
+    return `${trimNum(Number(display.toFixed(decimalsForUnit(unit))))} ${unit}`;
+}
+export function formatAreaParts(value, modality = 'metric', areaUnit = 'mm') {
+    const parsed = parseAreaValue(value);
+    if (!parsed)
+        return null;
+    const { heightMm, widthMm } = parsed;
+    const height = formatLengthFromMm(heightMm, modality, areaUnit);
+    const width = formatLengthFromMm(widthMm, modality, areaUnit);
+    const areaMm2 = heightMm * widthMm;
+    const unit = activeDisplayUnit(modality, areaUnit);
+    let areaLabel;
+    if (unit === 'ft') {
+        const sqFt = areaMm2 / (MM_PER_FOOT * MM_PER_FOOT);
+        areaLabel = `${trimNum(Number(sqFt.toFixed(3)))} sq ft`;
+    }
+    else if (unit === 'in') {
+        const sqIn = areaMm2 / (MM_PER_INCH * MM_PER_INCH);
+        if (sqIn >= 144) {
+            areaLabel = `${trimNum(Number((sqIn / 144).toFixed(3)))} sq ft`;
+        }
+        else {
+            areaLabel = `${trimNum(Number(sqIn.toFixed(2)))} sq in`;
+        }
+    }
+    else if (unit === 'm') {
+        areaLabel = `${trimNum(Number((areaMm2 / 1000000).toFixed(4)))} m²`;
+    }
+    else if (unit === 'cm') {
+        areaLabel = `${trimNum(Number((areaMm2 / 100).toFixed(2)))} cm²`;
+    }
+    else {
+        areaLabel = `${trimNum(Number(areaMm2.toFixed(2)))} mm²`;
+    }
+    return { width, height, areaLabel };
+}
+export function formatAreaSummary(value, modality = 'metric', areaUnit = 'mm') {
+    const parts = formatAreaParts(value, modality, areaUnit);
+    if (!parts)
+        return null;
+    // Width × height (landscape-first) to match the buyer control order.
+    return `Width ${parts.width} × Height ${parts.height} (${parts.areaLabel})`;
+}
+export function clamp(n, min, max) {
+    let v = n;
+    if (min != null && Number.isFinite(min))
+        v = Math.max(v, min);
+    if (max != null && Number.isFinite(max))
+        v = Math.min(v, max);
+    return v;
+}
+/**
+ * Client-side Area cost estimate (pre-discount), matching API formula:
+ * onceOff = heightCost × widthCost × height_u × width_u
+ * unitCost = heightUnit × widthUnit × height_u × width_u
+ * (dimensions expressed in the field's areaUnit)
+ */
+export function estimateAreaCosts(variationField, value) {
+    const parsed = parseAreaValue(value);
+    if (!parsed)
+        return null;
+    const areaUnit = normaliseAreaUnit(variationField?.areaUnit ?? variationField?.area_unit ?? 'mm');
+    const heightU = mmToUnit(parsed.heightMm, areaUnit);
+    const widthU = mmToUnit(parsed.widthMm, areaUnit);
+    const area = heightU * widthU;
+    const heightCost = Number(variationField?.heightVariationCost ??
+        variationField?.height_variation_cost) || 0;
+    const widthCost = Number(variationField?.widthVariationCost ?? variationField?.width_variation_cost) || 0;
+    const heightUnit = Number(variationField?.heightVariationUnitCost ??
+        variationField?.height_variation_unit_cost) || 0;
+    const widthUnit = Number(variationField?.widthVariationUnitCost ??
+        variationField?.width_variation_unit_cost) || 0;
+    const onceOffCost = heightCost * widthCost * area;
+    const unitCost = heightUnit * widthUnit * area;
+    if (!(onceOffCost > 0) && !(unitCost > 0))
+        return null;
+    return {
+        onceOffCost: Number(onceOffCost.toFixed(3)),
+        unitCost: Number(unitCost.toFixed(3)),
+    };
+}
+/**
+ * Keep width/height linked by aspectRatio (width/height).
+ * `changed` indicates which dimension the user edited.
+ */
+export function clampWithAspectRatio(args) {
+    const ratio = args.aspectRatio;
+    if (!Number.isFinite(ratio) || ratio <= 0) {
+        return {
+            heightMm: clamp(args.heightMm, args.heightMin, args.heightMax),
+            widthMm: clamp(args.widthMm, args.widthMin, args.widthMax),
+        };
+    }
+    let heightMm = args.heightMm;
+    let widthMm = args.widthMm;
+    if (args.changed === 'height') {
+        heightMm = clamp(heightMm, args.heightMin, args.heightMax);
+        widthMm = heightMm * ratio;
+        widthMm = clamp(widthMm, args.widthMin, args.widthMax);
+        heightMm = widthMm / ratio;
+        heightMm = clamp(heightMm, args.heightMin, args.heightMax);
+        widthMm = heightMm * ratio;
+    }
+    else {
+        widthMm = clamp(widthMm, args.widthMin, args.widthMax);
+        heightMm = widthMm / ratio;
+        heightMm = clamp(heightMm, args.heightMin, args.heightMax);
+        widthMm = heightMm * ratio;
+        widthMm = clamp(widthMm, args.widthMin, args.widthMax);
+    }
+    return { heightMm, widthMm };
+}

package/dist/helpers/buildJob.d.ts

@@ -0,0 +1,29 @@
+import { JobJson } from '../types/job';
+import { ProductJson } from '../types/product';
+import { VariationJson } from '../types/variation';
+import { FieldSelection } from '../components/context';
+export interface GroupRow {
+    quantity: number;
+    selections: Record<number, FieldSelection>;
+}
+export interface ProductFormJobState {
+    product: ProductJson;
+    quantity: number;
+    /** Independent (whole-order) field selections. */
+    selections: Record<number, FieldSelection>;
+    /** Multi-batch group rows when the product has 2+ group fields or non-grid group UX. */
+    groups?: GroupRow[];
+    /** Per-option quantities for single group-field grid products. */
+    optionQuantities?: Record<number, number>;
+}
+export declare function selectionsToVariations(selections: Record<number, FieldSelection>): VariationJson[];
+/** Build the job JSON the API expects from provider/form state. */
+export declare function buildProductFormJob(state: ProductFormJobState): JobJson;
+export interface HydratedProductFormState {
+    quantity: number;
+    selections: Record<number, FieldSelection>;
+    groups: GroupRow[];
+    optionQuantities: Record<number, number>;
+}
+/** Reverse of buildProductFormJob — hydrate provider state from a cart item / job. */
+export declare function jobToFormState(product: ProductJson, job?: JobJson | null): HydratedProductFormState;