@10x-media/form-builder 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/calc/normalizeCalc.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalizeCalc.js","names":[],"sources":["../../src/calc/normalizeCalc.ts"],"sourcesContent":["import {\n\tCALC_FNS,\n\tCALC_OPS,\n\ttype CalcExpression,\n\ttype CalcFn,\n\ttype CalcOp,\n\tMAX_DEPTH,\n} from './types'\n\nconst isOp = (v: unknown): v is CalcOp => (CALC_OPS as readonly unknown[]).includes(v)\nconst isFn = (v: unknown): v is CalcFn => (CALC_FNS as readonly unknown[]).includes(v)\n\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n\tv !== null && typeof v === 'object' && !Array.isArray(v)\n\nconst normalizeNode = (value: unknown, depth: number): CalcExpression | undefined => {\n\tif (depth > MAX_DEPTH) return undefined\n\tif (!isRecord(value)) return undefined\n\n\tswitch (value.type) {\n\t\tcase 'lit': {\n\t\t\tconst { value: v } = value\n\t\t\tif (typeof v !== 'number' || !Number.isFinite(v)) return undefined\n\t\t\treturn { type: 'lit', value: v }\n\t\t}\n\t\tcase 'ref': {\n\t\t\tconst { field } = value\n\t\t\tif (typeof field !== 'string') return undefined\n\t\t\treturn { type: 'ref', field }\n\t\t}\n\t\tcase 'op': {\n\t\t\tconst { op, left, right } = value\n\t\t\tif (!isOp(op)) return undefined\n\t\t\tconst l = normalizeNode(left, depth + 1)\n\t\t\tif (!l) return undefined\n\t\t\tconst r = normalizeNode(right, depth + 1)\n\t\t\tif (!r) return undefined\n\t\t\treturn { type: 'op', op, left: l, right: r }\n\t\t}\n\t\tcase 'neg': {\n\t\t\tconst operand = normalizeNode(value.operand, depth + 1)\n\t\t\tif (!operand) return undefined\n\t\t\treturn { type: 'neg', operand }\n\t\t}\n\t\tcase 'fn': {\n\t\t\tconst { fn, args } = value\n\t\t\tif (!isFn(fn)) return undefined\n\t\t\tif (!Array.isArray(args)) return undefined\n\t\t\tconst normalizedArgs: CalcExpression[] = []\n\t\t\tfor (const arg of args) {\n\t\t\t\tconst a = normalizeNode(arg, depth + 1)\n\t\t\t\tif (!a) return undefined\n\t\t\t\tnormalizedArgs.push(a)\n\t\t\t}\n\t\t\treturn { type: 'fn', fn, args: normalizedArgs }\n\t\t}\n\t\tcase 'weight': {\n\t\t\tconst { field, weights } = value\n\t\t\tif (typeof field !== 'string') return undefined\n\t\t\tif (!isRecord(weights)) return undefined\n\t\t\tconst normalizedWeights: Record<string, number> = {}\n\t\t\tfor (const [k, v] of Object.entries(weights)) {\n\t\t\t\tif (typeof v !== 'number' || !Number.isFinite(v)) return undefined\n\t\t\t\tnormalizedWeights[k] = v\n\t\t\t}\n\t\t\treturn { type: 'weight', field, weights: normalizedWeights }\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined\n\t}\n}\n\n/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */\nexport const normalizeCalc = (value: unknown): CalcExpression | undefined => normalizeNode(value, 0)\n"],"mappings":";;AASA,MAAM,QAAQ,MAA6B,SAAgC,SAAS,CAAC;AACrF,MAAM,QAAQ,MAA6B,SAAgC,SAAS,CAAC;AAErF,MAAM,YAAY,MACjB,MAAM,QAAQ,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC;AAExD,MAAM,iBAAiB,OAAgB,UAA8C;CACpF,IAAI,QAAA,IAAmB,OAAO,KAAA;CAC9B,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO,KAAA;CAE7B,QAAQ,MAAM,MAAd;EACC,KAAK,OAAO;GACX,MAAM,EAAE,OAAO,MAAM;GACrB,IAAI,OAAO,MAAM,YAAY,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO,KAAA;GACzD,OAAO;IAAE,MAAM;IAAO,OAAO;GAAE;EAChC;EACA,KAAK,OAAO;GACX,MAAM,EAAE,UAAU;GAClB,IAAI,OAAO,UAAU,UAAU,OAAO,KAAA;GACtC,OAAO;IAAE,MAAM;IAAO;GAAM;EAC7B;EACA,KAAK,MAAM;GACV,MAAM,EAAE,IAAI,MAAM,UAAU;GAC5B,IAAI,CAAC,KAAK,EAAE,GAAG,OAAO,KAAA;GACtB,MAAM,IAAI,cAAc,MAAM,QAAQ,CAAC;GACvC,IAAI,CAAC,GAAG,OAAO,KAAA;GACf,MAAM,IAAI,cAAc,OAAO,QAAQ,CAAC;GACxC,IAAI,CAAC,GAAG,OAAO,KAAA;GACf,OAAO;IAAE,MAAM;IAAM;IAAI,MAAM;IAAG,OAAO;GAAE;EAC5C;EACA,KAAK,OAAO;GACX,MAAM,UAAU,cAAc,MAAM,SAAS,QAAQ,CAAC;GACtD,IAAI,CAAC,SAAS,OAAO,KAAA;GACrB,OAAO;IAAE,MAAM;IAAO;GAAQ;EAC/B;EACA,KAAK,MAAM;GACV,MAAM,EAAE,IAAI,SAAS;GACrB,IAAI,CAAC,KAAK,EAAE,GAAG,OAAO,KAAA;GACtB,IAAI,CAAC,MAAM,QAAQ,IAAI,GAAG,OAAO,KAAA;GACjC,MAAM,iBAAmC,CAAC;GAC1C,KAAK,MAAM,OAAO,MAAM;IACvB,MAAM,IAAI,cAAc,KAAK,QAAQ,CAAC;IACtC,IAAI,CAAC,GAAG,OAAO,KAAA;IACf,eAAe,KAAK,CAAC;GACtB;GACA,OAAO;IAAE,MAAM;IAAM;IAAI,MAAM;GAAe;EAC/C;EACA,KAAK,UAAU;GACd,MAAM,EAAE,OAAO,YAAY;GAC3B,IAAI,OAAO,UAAU,UAAU,OAAO,KAAA;GACtC,IAAI,CAAC,SAAS,OAAO,GAAG,OAAO,KAAA;GAC/B,MAAM,oBAA4C,CAAC;GACnD,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,OAAO,GAAG;IAC7C,IAAI,OAAO,MAAM,YAAY,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO,KAAA;IACzD,kBAAkB,KAAK;GACxB;GACA,OAAO;IAAE,MAAM;IAAU;IAAO,SAAS;GAAkB;EAC5D;EACA,SACC;CACF;AACD;;AAGA,MAAa,iBAAiB,UAA+C,cAAc,OAAO,CAAC"}
+{"version":3,"file":"normalizeCalc.js","names":[],"sources":["../../src/calc/normalizeCalc.ts"],"sourcesContent":["import { CALC_OPS, type CalcExpression, type CalcOp, isCalcFn, MAX_DEPTH } from './types'\n\n/**\n * The extension names a normalized expression may reference: registered calc source keys and custom\n * function names (plugin option `calc`). Absent (the default for every un-threaded caller), only the\n * built-in grammar is valid: `source` nodes, sourced weights, and custom fns all reject.\n */\nexport type CalcAllowed = {\n\tsources?: ReadonlySet<string>\n\tfunctions?: ReadonlySet<string>\n}\n\nconst isOp = (v: unknown): v is CalcOp => (CALC_OPS as readonly unknown[]).includes(v)\n\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n\tv !== null && typeof v === 'object' && !Array.isArray(v)\n\nconst normalizeNode = (\n\tvalue: unknown,\n\tdepth: number,\n\tallowed?: CalcAllowed\n): CalcExpression | undefined => {\n\tif (depth > MAX_DEPTH) return undefined\n\tif (!isRecord(value)) return undefined\n\n\tswitch (value.type) {\n\t\tcase 'lit': {\n\t\t\tconst { value: v } = value\n\t\t\tif (typeof v !== 'number' || !Number.isFinite(v)) return undefined\n\t\t\treturn { type: 'lit', value: v }\n\t\t}\n\t\tcase 'ref': {\n\t\t\tconst { field } = value\n\t\t\tif (typeof field !== 'string') return undefined\n\t\t\treturn { type: 'ref', field }\n\t\t}\n\t\tcase 'op': {\n\t\t\tconst { op, left, right } = value\n\t\t\tif (!isOp(op)) return undefined\n\t\t\tconst l = normalizeNode(left, depth + 1, allowed)\n\t\t\tif (!l) return undefined\n\t\t\tconst r = normalizeNode(right, depth + 1, allowed)\n\t\t\tif (!r) return undefined\n\t\t\treturn { type: 'op', op, left: l, right: r }\n\t\t}\n\t\tcase 'neg': {\n\t\t\tconst operand = normalizeNode(value.operand, depth + 1, allowed)\n\t\t\tif (!operand) return undefined\n\t\t\treturn { type: 'neg', operand }\n\t\t}\n\t\tcase 'fn': {\n\t\t\tconst { fn, args } = value\n\t\t\tif (typeof fn !== 'string') return undefined\n\t\t\tif (!isCalcFn(fn) && !allowed?.functions?.has(fn)) return undefined\n\t\t\tif (!Array.isArray(args)) return undefined\n\t\t\tconst normalizedArgs: CalcExpression[] = []\n\t\t\tfor (const arg of args) {\n\t\t\t\tconst a = normalizeNode(arg, depth + 1, allowed)\n\t\t\t\tif (!a) return undefined\n\t\t\t\tnormalizedArgs.push(a)\n\t\t\t}\n\t\t\treturn { type: 'fn', fn, args: normalizedArgs }\n\t\t}\n\t\tcase 'source': {\n\t\t\tconst { source } = value\n\t\t\tif (typeof source !== 'string') return undefined\n\t\t\tif (!allowed?.sources?.has(source)) return undefined\n\t\t\treturn { type: 'source', source }\n\t\t}\n\t\tcase 'weight': {\n\t\t\tconst { field, weights, source } = value\n\t\t\tif (typeof field !== 'string') return undefined\n\t\t\tif (source !== undefined) {\n\t\t\t\tif (typeof source !== 'string' || !allowed?.sources?.has(source)) return undefined\n\t\t\t}\n\t\t\tlet normalizedWeights: Record<string, number> | undefined\n\t\t\tif (weights !== undefined) {\n\t\t\t\tif (!isRecord(weights)) return undefined\n\t\t\t\tnormalizedWeights = {}\n\t\t\t\tfor (const [k, v] of Object.entries(weights)) {\n\t\t\t\t\tif (typeof v !== 'number' || !Number.isFinite(v)) return undefined\n\t\t\t\t\tnormalizedWeights[k] = v\n\t\t\t\t}\n\t\t\t}\n\t\t\t// A weight must carry a per-option map from somewhere: inline weights or a registered source.\n\t\t\tif (normalizedWeights === undefined && source === undefined) return undefined\n\t\t\treturn {\n\t\t\t\ttype: 'weight',\n\t\t\t\tfield,\n\t\t\t\t...(normalizedWeights !== undefined ? { weights: normalizedWeights } : {}),\n\t\t\t\t...(typeof source === 'string' ? { source } : {}),\n\t\t\t}\n\t\t}\n\t\tdefault:\n\t\t\treturn undefined\n\t}\n}\n\n/**\n * Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded\n * at 64), otherwise undefined. Never throws. `allowed` admits registered extension names (source\n * keys, custom function names); without it only the built-in grammar passes, so an un-threaded\n * caller can never validate an expression the evaluator has no values for.\n */\nexport const normalizeCalc = (value: unknown, allowed?: CalcAllowed): CalcExpression | undefined =>\n\tnormalizeNode(value, 0, allowed)\n"],"mappings":"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"}

package/dist/calc/registry.d.ts

@@ -0,0 +1,43 @@
+import { Payload, PayloadRequest } from "payload";
+
+//#region src/calc/registry.d.ts
+type CalcSourceResolveArgs = {
+  form: {
+    id: number | string;
+  } & Record<string, unknown>;
+  payload: Payload;
+  /**
+   * On public form reads and submits this is an unauthenticated visitor request: never feed data
+   * derived from it into access-escalated queries, and gate any per-user-sensitive number on
+   * `req.user` (resolved values are embedded on every readable form document).
+   */
+  req?: PayloadRequest;
+};
+type CalcWeightResolveArgs = CalcSourceResolveArgs & {
+  /** The field instance whose options are being priced (name, blockType, options, custom config). */field: Record<string, unknown> & {
+    name: string;
+  };
+};
+/**
+ * A named server-side value resolver the calculation field can reference. Values resolve on the
+ * server (render embedding and again at submit), so the client never supplies them. A source may
+ * offer either mode or both; an expression using a mode the source does not implement fails
+ * loudly at resolution.
+ */
+type CalcSource = {
+  label: string | Record<string, string>; /** Scalar mode: one number for the whole form render/submission. */
+  resolve?: (args: CalcSourceResolveArgs) => number | Promise<number>; /** Weight mode: per-option values for a chosen field, keyed by option value. */
+  resolveWeights?: (args: CalcWeightResolveArgs) => Record<string, number> | Promise<Record<string, number>>;
+};
+/** A host-registered calculation function; `apply` must be pure and sync (it runs isomorphically in the live preview). */
+type CalcFunction = {
+  label: string | Record<string, string>;
+  apply: (args: number[]) => number;
+};
+/** Identity helper: define a calc source once with full typing (the `defineFormField` precedent). */
+declare const defineCalcSource: (source: CalcSource) => CalcSource;
+/** Identity helper: define a calc function once with full typing (the `defineFormField` precedent). */
+declare const defineCalcFunction: (fn: CalcFunction) => CalcFunction;
+//#endregion
+export { CalcFunction, CalcSource, CalcSourceResolveArgs, CalcWeightResolveArgs, defineCalcFunction, defineCalcSource };
+//# sourceMappingURL=registry.d.ts.map

package/dist/calc/registry.js

@@ -0,0 +1,27 @@
+import { CALC_FNS } from "./types.js";
+//#region src/calc/registry.ts
+/** Identity helper: define a calc source once with full typing (the `defineFormField` precedent). */
+const defineCalcSource = (source) => source;
+/** Identity helper: define a calc function once with full typing (the `defineFormField` precedent). */
+const defineCalcFunction = (fn) => fn;
+/**
+* Fail fast at boot when a registered calc function key collides with a built-in. The evaluator
+* always resolves built-ins first, so a colliding custom function could never run; rather than let
+* it be shadowed quietly, throw a clear error naming the collision so the author renames it.
+*/
+const assertNoCalcFunctionCollision = (functions) => {
+	for (const key of Object.keys(functions)) if (CALC_FNS.includes(key)) throw new Error(`@10x-media/form-builder: calculation function "${key}" collides with the built-in function "${key}". Rename the custom function.`);
+};
+const CALC_SOURCE_KEY_PATTERN = /^[\w.-]+$/;
+/**
+* Fail fast at boot on a calc source key outside `[\w.-]`. Resolved weight maps are keyed
+* `source + ' ' + field` (`calcWeightKey`), so the separator char must never appear in a source
+* key or two different (source, field) pairs could collide on one map.
+*/
+const assertValidCalcSourceKeys = (sources) => {
+	for (const key of Object.keys(sources)) if (!CALC_SOURCE_KEY_PATTERN.test(key)) throw new Error(`@10x-media/form-builder: calculation source key "${key}" is invalid. Use only letters, digits, "_", "." or "-".`);
+};
+//#endregion
+export { assertNoCalcFunctionCollision, assertValidCalcSourceKeys, defineCalcFunction, defineCalcSource };
+
+//# sourceMappingURL=registry.js.map

package/dist/calc/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","names":[],"sources":["../../src/calc/registry.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport { CALC_FNS } from './types'\n\nexport type CalcSourceResolveArgs = {\n\tform: { id: number | string } & Record<string, unknown>\n\tpayload: Payload\n\t/**\n\t * On public form reads and submits this is an unauthenticated visitor request: never feed data\n\t * derived from it into access-escalated queries, and gate any per-user-sensitive number on\n\t * `req.user` (resolved values are embedded on every readable form document).\n\t */\n\treq?: PayloadRequest\n}\n\nexport type CalcWeightResolveArgs = CalcSourceResolveArgs & {\n\t/** The field instance whose options are being priced (name, blockType, options, custom config). */\n\tfield: Record<string, unknown> & { name: string }\n}\n\n/**\n * A named server-side value resolver the calculation field can reference. Values resolve on the\n * server (render embedding and again at submit), so the client never supplies them. A source may\n * offer either mode or both; an expression using a mode the source does not implement fails\n * loudly at resolution.\n */\nexport type CalcSource = {\n\tlabel: string | Record<string, string>\n\t/** Scalar mode: one number for the whole form render/submission. */\n\tresolve?: (args: CalcSourceResolveArgs) => number | Promise<number>\n\t/** Weight mode: per-option values for a chosen field, keyed by option value. */\n\tresolveWeights?: (\n\t\targs: CalcWeightResolveArgs\n\t) => Record<string, number> | Promise<Record<string, number>>\n}\n\n/** A host-registered calculation function; `apply` must be pure and sync (it runs isomorphically in the live preview). */\nexport type CalcFunction = {\n\tlabel: string | Record<string, string>\n\tapply: (args: number[]) => number\n}\n\n/** Identity helper: define a calc source once with full typing (the `defineFormField` precedent). */\nexport const defineCalcSource = (source: CalcSource): CalcSource => source\n\n/** Identity helper: define a calc function once with full typing (the `defineFormField` precedent). */\nexport const defineCalcFunction = (fn: CalcFunction): CalcFunction => fn\n\n/**\n * Fail fast at boot when a registered calc function key collides with a built-in. The evaluator\n * always resolves built-ins first, so a colliding custom function could never run; rather than let\n * it be shadowed quietly, throw a clear error naming the collision so the author renames it.\n */\nexport const assertNoCalcFunctionCollision = (functions: Record<string, CalcFunction>): void => {\n\tfor (const key of Object.keys(functions)) {\n\t\tif ((CALC_FNS as readonly string[]).includes(key)) {\n\t\t\tthrow new Error(\n\t\t\t\t`@10x-media/form-builder: calculation function \"${key}\" collides with the built-in function \"${key}\". Rename the custom function.`\n\t\t\t)\n\t\t}\n\t}\n}\n\nconst CALC_SOURCE_KEY_PATTERN = /^[\\w.-]+$/\n\n/**\n * Fail fast at boot on a calc source key outside `[\\w.-]`. Resolved weight maps are keyed\n * `source + ' ' + field` (`calcWeightKey`), so the separator char must never appear in a source\n * key or two different (source, field) pairs could collide on one map.\n */\nexport const assertValidCalcSourceKeys = (sources: Record<string, CalcSource>): void => {\n\tfor (const key of Object.keys(sources)) {\n\t\tif (!CALC_SOURCE_KEY_PATTERN.test(key)) {\n\t\t\tthrow new Error(\n\t\t\t\t`@10x-media/form-builder: calculation source key \"${key}\" is invalid. Use only letters, digits, \"_\", \".\" or \"-\".`\n\t\t\t)\n\t\t}\n\t}\n}\n"],"mappings":";;;AA0CA,MAAa,oBAAoB,WAAmC;;AAGpE,MAAa,sBAAsB,OAAmC;;;;;;AAOtE,MAAa,iCAAiC,cAAkD;CAC/F,KAAK,MAAM,OAAO,OAAO,KAAK,SAAS,GACtC,IAAK,SAA+B,SAAS,GAAG,GAC/C,MAAM,IAAI,MACT,kDAAkD,IAAI,yCAAyC,IAAI,+BACpG;AAGH;AAEA,MAAM,0BAA0B;;;;;;AAOhC,MAAa,6BAA6B,YAA8C;CACvF,KAAK,MAAM,OAAO,OAAO,KAAK,OAAO,GACpC,IAAI,CAAC,wBAAwB,KAAK,GAAG,GACpC,MAAM,IAAI,MACT,oDAAoD,IAAI,yDACzD;AAGH"}

package/dist/calc/resolveCalcContext.d.ts

@@ -0,0 +1,36 @@
+import { FormFieldInstance } from "../submissions/types.js";
+import { CalcResolved } from "./evaluate.js";
+import { CalcSource } from "./registry.js";
+import { Payload, PayloadRequest } from "payload";
+
+//#region src/calc/resolveCalcContext.d.ts
+/** Whether any calc field's expression references a registered calc source (scalar or weight mode). */
+declare const calcUsesSources: (fields: FormFieldInstance[]) => boolean;
+type ResolveCalcContextArgs = {
+  fields: FormFieldInstance[]; /** The registered calc sources (plugin option `calc.sources`). */
+  sources: Record<string, CalcSource>;
+  form: {
+    id: number | string;
+  } & Record<string, unknown>;
+  payload: Payload;
+  req?: PayloadRequest;
+};
+/**
+ * Resolve every calc source a form's expressions reference: used scalar keys through `resolve`,
+ * used (source, field) weight pairs through `resolveWeights` with the referenced field instance,
+ * each exactly once. A weight pair whose field instance is missing resolves to an empty map. A
+ * used-but-unregistered key (or a mode the source does not implement) and any resolver failure
+ * THROW: these values are money math, so the caller decides how loud a failure is (submit rejects,
+ * the render hook catches and degrades). Custom functions are not resolved here; they come straight
+ * off the registry per environment.
+ */
+declare const resolveCalcContext: ({
+  fields,
+  sources,
+  form,
+  payload,
+  req
+}: ResolveCalcContextArgs) => Promise<CalcResolved>;
+//#endregion
+export { ResolveCalcContextArgs, calcUsesSources, resolveCalcContext };
+//# sourceMappingURL=resolveCalcContext.d.ts.map

package/dist/calc/resolveCalcContext.js

@@ -0,0 +1,87 @@
+import { calcWeightKey } from "./evaluate.js";
+import { calcExpressionOf } from "./computeCalcFields.js";
+//#region src/calc/resolveCalcContext.ts
+const collectNode = (expr, usage, depth) => {
+	if (depth > 64 || expr == null || typeof expr !== "object") return;
+	switch (expr.type) {
+		case "source":
+			usage.scalars.add(expr.source);
+			return;
+		case "weight":
+			if (typeof expr.source === "string") usage.weightPairs.set(calcWeightKey(expr.source, expr.field), {
+				source: expr.source,
+				field: expr.field
+			});
+			return;
+		case "op":
+			collectNode(expr.left, usage, depth + 1);
+			collectNode(expr.right, usage, depth + 1);
+			return;
+		case "neg":
+			collectNode(expr.operand, usage, depth + 1);
+			return;
+		case "fn":
+			if (Array.isArray(expr.args)) for (const arg of expr.args) collectNode(arg, usage, depth + 1);
+			return;
+		default: return;
+	}
+};
+const usageOf = (fields) => {
+	const usage = {
+		scalars: /* @__PURE__ */ new Set(),
+		weightPairs: /* @__PURE__ */ new Map()
+	};
+	for (const field of fields) {
+		const expr = calcExpressionOf(field);
+		if (expr) collectNode(expr, usage, 0);
+	}
+	return usage;
+};
+/** Whether any calc field's expression references a registered calc source (scalar or weight mode). */
+const calcUsesSources = (fields) => {
+	const usage = usageOf(fields);
+	return usage.scalars.size > 0 || usage.weightPairs.size > 0;
+};
+/**
+* Resolve every calc source a form's expressions reference: used scalar keys through `resolve`,
+* used (source, field) weight pairs through `resolveWeights` with the referenced field instance,
+* each exactly once. A weight pair whose field instance is missing resolves to an empty map. A
+* used-but-unregistered key (or a mode the source does not implement) and any resolver failure
+* THROW: these values are money math, so the caller decides how loud a failure is (submit rejects,
+* the render hook catches and degrades). Custom functions are not resolved here; they come straight
+* off the registry per environment.
+*/
+const resolveCalcContext = async ({ fields, sources, form, payload, req }) => {
+	const usage = usageOf(fields);
+	if (usage.scalars.size === 0 && usage.weightPairs.size === 0) return {};
+	const resolvedSources = {};
+	for (const key of usage.scalars) {
+		const source = sources[key];
+		if (!source?.resolve) throw new Error(`@10x-media/form-builder: calculation expression references source "${key}", which is not registered or has no \`resolve\`.`);
+		resolvedSources[key] = await source.resolve({
+			form,
+			payload,
+			req
+		});
+	}
+	const resolvedWeights = {};
+	for (const [key, pair] of usage.weightPairs) {
+		const source = sources[pair.source];
+		if (!source?.resolveWeights) throw new Error(`@10x-media/form-builder: calculation expression references weights from source "${pair.source}", which is not registered or has no \`resolveWeights\`.`);
+		const instance = fields.find((field) => field.name === pair.field);
+		resolvedWeights[key] = instance ? await source.resolveWeights({
+			form,
+			payload,
+			req,
+			field: instance
+		}) : {};
+	}
+	return {
+		...usage.scalars.size > 0 ? { sources: resolvedSources } : {},
+		...usage.weightPairs.size > 0 ? { weights: resolvedWeights } : {}
+	};
+};
+//#endregion
+export { calcUsesSources, resolveCalcContext };
+
+//# sourceMappingURL=resolveCalcContext.js.map

package/dist/calc/resolveCalcContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveCalcContext.js","names":[],"sources":["../../src/calc/resolveCalcContext.ts"],"sourcesContent":["import type { Payload, PayloadRequest } from 'payload'\nimport type { FormFieldInstance } from '../submissions/types'\nimport { calcExpressionOf } from './computeCalcFields'\nimport { type CalcResolved, calcWeightKey } from './evaluate'\nimport type { CalcSource, CalcWeightResolveArgs } from './registry'\nimport { type CalcExpression, MAX_DEPTH } from './types'\n\ntype CalcSourceUsage = {\n\tscalars: Set<string>\n\t/** Keyed by `calcWeightKey(source, field)`, deduped across expressions. */\n\tweightPairs: Map<string, { source: string; field: string }>\n}\n\nconst collectNode = (expr: CalcExpression, usage: CalcSourceUsage, depth: number): void => {\n\tif (depth > MAX_DEPTH || expr == null || typeof expr !== 'object') return\n\tswitch (expr.type) {\n\t\tcase 'source':\n\t\t\tusage.scalars.add(expr.source)\n\t\t\treturn\n\t\tcase 'weight':\n\t\t\tif (typeof expr.source === 'string') {\n\t\t\t\tusage.weightPairs.set(calcWeightKey(expr.source, expr.field), {\n\t\t\t\t\tsource: expr.source,\n\t\t\t\t\tfield: expr.field,\n\t\t\t\t})\n\t\t\t}\n\t\t\treturn\n\t\tcase 'op':\n\t\t\tcollectNode(expr.left, usage, depth + 1)\n\t\t\tcollectNode(expr.right, usage, depth + 1)\n\t\t\treturn\n\t\tcase 'neg':\n\t\t\tcollectNode(expr.operand, usage, depth + 1)\n\t\t\treturn\n\t\tcase 'fn':\n\t\t\tif (Array.isArray(expr.args)) {\n\t\t\t\tfor (const arg of expr.args) collectNode(arg, usage, depth + 1)\n\t\t\t}\n\t\t\treturn\n\t\tdefault:\n\t\t\treturn\n\t}\n}\n\nconst usageOf = (fields: FormFieldInstance[]): CalcSourceUsage => {\n\tconst usage: CalcSourceUsage = { scalars: new Set(), weightPairs: new Map() }\n\tfor (const field of fields) {\n\t\tconst expr = calcExpressionOf(field)\n\t\tif (expr) collectNode(expr, usage, 0)\n\t}\n\treturn usage\n}\n\n/** Whether any calc field's expression references a registered calc source (scalar or weight mode). */\nexport const calcUsesSources = (fields: FormFieldInstance[]): boolean => {\n\tconst usage = usageOf(fields)\n\treturn usage.scalars.size > 0 || usage.weightPairs.size > 0\n}\n\nexport type ResolveCalcContextArgs = {\n\tfields: FormFieldInstance[]\n\t/** The registered calc sources (plugin option `calc.sources`). */\n\tsources: Record<string, CalcSource>\n\tform: { id: number | string } & Record<string, unknown>\n\tpayload: Payload\n\treq?: PayloadRequest\n}\n\n/**\n * Resolve every calc source a form's expressions reference: used scalar keys through `resolve`,\n * used (source, field) weight pairs through `resolveWeights` with the referenced field instance,\n * each exactly once. A weight pair whose field instance is missing resolves to an empty map. A\n * used-but-unregistered key (or a mode the source does not implement) and any resolver failure\n * THROW: these values are money math, so the caller decides how loud a failure is (submit rejects,\n * the render hook catches and degrades). Custom functions are not resolved here; they come straight\n * off the registry per environment.\n */\nexport const resolveCalcContext = async ({\n\tfields,\n\tsources,\n\tform,\n\tpayload,\n\treq,\n}: ResolveCalcContextArgs): Promise<CalcResolved> => {\n\tconst usage = usageOf(fields)\n\tif (usage.scalars.size === 0 && usage.weightPairs.size === 0) {\n\t\treturn {}\n\t}\n\tconst resolvedSources: Record<string, number> = {}\n\tfor (const key of usage.scalars) {\n\t\tconst source = sources[key]\n\t\tif (!source?.resolve) {\n\t\t\tthrow new Error(\n\t\t\t\t`@10x-media/form-builder: calculation expression references source \"${key}\", which is not registered or has no \\`resolve\\`.`\n\t\t\t)\n\t\t}\n\t\tresolvedSources[key] = await source.resolve({ form, payload, req })\n\t}\n\tconst resolvedWeights: Record<string, Record<string, number>> = {}\n\tfor (const [key, pair] of usage.weightPairs) {\n\t\tconst source = sources[pair.source]\n\t\tif (!source?.resolveWeights) {\n\t\t\tthrow new Error(\n\t\t\t\t`@10x-media/form-builder: calculation expression references weights from source \"${pair.source}\", which is not registered or has no \\`resolveWeights\\`.`\n\t\t\t)\n\t\t}\n\t\tconst instance = fields.find((field) => field.name === pair.field)\n\t\tresolvedWeights[key] = instance\n\t\t\t? await source.resolveWeights({\n\t\t\t\t\tform,\n\t\t\t\t\tpayload,\n\t\t\t\t\treq,\n\t\t\t\t\tfield: instance as CalcWeightResolveArgs['field'],\n\t\t\t\t})\n\t\t\t: {}\n\t}\n\treturn {\n\t\t...(usage.scalars.size > 0 ? { sources: resolvedSources } : {}),\n\t\t...(usage.weightPairs.size > 0 ? { weights: resolvedWeights } : {}),\n\t}\n}\n"],"mappings":";;;AAaA,MAAM,eAAe,MAAsB,OAAwB,UAAwB;CAC1F,IAAI,QAAA,MAAqB,QAAQ,QAAQ,OAAO,SAAS,UAAU;CACnE,QAAQ,KAAK,MAAb;EACC,KAAK;GACJ,MAAM,QAAQ,IAAI,KAAK,MAAM;GAC7B;EACD,KAAK;GACJ,IAAI,OAAO,KAAK,WAAW,UAC1B,MAAM,YAAY,IAAI,cAAc,KAAK,QAAQ,KAAK,KAAK,GAAG;IAC7D,QAAQ,KAAK;IACb,OAAO,KAAK;GACb,CAAC;GAEF;EACD,KAAK;GACJ,YAAY,KAAK,MAAM,OAAO,QAAQ,CAAC;GACvC,YAAY,KAAK,OAAO,OAAO,QAAQ,CAAC;GACxC;EACD,KAAK;GACJ,YAAY,KAAK,SAAS,OAAO,QAAQ,CAAC;GAC1C;EACD,KAAK;GACJ,IAAI,MAAM,QAAQ,KAAK,IAAI,GAC1B,KAAK,MAAM,OAAO,KAAK,MAAM,YAAY,KAAK,OAAO,QAAQ,CAAC;GAE/D;EACD,SACC;CACF;AACD;AAEA,MAAM,WAAW,WAAiD;CACjE,MAAM,QAAyB;EAAE,yBAAS,IAAI,IAAI;EAAG,6BAAa,IAAI,IAAI;CAAE;CAC5E,KAAK,MAAM,SAAS,QAAQ;EAC3B,MAAM,OAAO,iBAAiB,KAAK;EACnC,IAAI,MAAM,YAAY,MAAM,OAAO,CAAC;CACrC;CACA,OAAO;AACR;;AAGA,MAAa,mBAAmB,WAAyC;CACxE,MAAM,QAAQ,QAAQ,MAAM;CAC5B,OAAO,MAAM,QAAQ,OAAO,KAAK,MAAM,YAAY,OAAO;AAC3D;;;;;;;;;;AAoBA,MAAa,qBAAqB,OAAO,EACxC,QACA,SACA,MACA,SACA,UACoD;CACpD,MAAM,QAAQ,QAAQ,MAAM;CAC5B,IAAI,MAAM,QAAQ,SAAS,KAAK,MAAM,YAAY,SAAS,GAC1D,OAAO,CAAC;CAET,MAAM,kBAA0C,CAAC;CACjD,KAAK,MAAM,OAAO,MAAM,SAAS;EAChC,MAAM,SAAS,QAAQ;EACvB,IAAI,CAAC,QAAQ,SACZ,MAAM,IAAI,MACT,sEAAsE,IAAI,kDAC3E;EAED,gBAAgB,OAAO,MAAM,OAAO,QAAQ;GAAE;GAAM;GAAS;EAAI,CAAC;CACnE;CACA,MAAM,kBAA0D,CAAC;CACjE,KAAK,MAAM,CAAC,KAAK,SAAS,MAAM,aAAa;EAC5C,MAAM,SAAS,QAAQ,KAAK;EAC5B,IAAI,CAAC,QAAQ,gBACZ,MAAM,IAAI,MACT,mFAAmF,KAAK,OAAO,yDAChG;EAED,MAAM,WAAW,OAAO,MAAM,UAAU,MAAM,SAAS,KAAK,KAAK;EACjE,gBAAgB,OAAO,WACpB,MAAM,OAAO,eAAe;GAC5B;GACA;GACA;GACA,OAAO;EACR,CAAC,IACA,CAAC;CACL;CACA,OAAO;EACN,GAAI,MAAM,QAAQ,OAAO,IAAI,EAAE,SAAS,gBAAgB,IAAI,CAAC;EAC7D,GAAI,MAAM,YAAY,OAAO,IAAI,EAAE,SAAS,gBAAgB,IAAI,CAAC;CAClE;AACD"}

package/dist/calc/types.d.ts

@@ -5,7 +5,18 @@ type CalcOp = (typeof CALC_OPS)[number];
 /** Canonical function grammar; same single source of truth as `CALC_OPS`. */
 declare const CALC_FNS: readonly ["min", "max", "round", "abs", "ceil", "floor"];
 type CalcFn = (typeof CALC_FNS)[number];
-/** A serializable, safe-by-construction calculation expression. No strings are parsed; the evaluator tree-walks this closed node set (never `eval`). */
+/**
+ * A function slot in the AST: a built-in, or a host-registered function name (plugin option
+ * `calc.functions`). The intersection trick keeps built-in autocomplete while admitting any
+ * registered key; `normalizeCalc` gates which names are actually valid.
+ */
+type CalcFnName = CalcFn | (string & {});
+/**
+ * A serializable, safe-by-construction calculation expression. No strings are parsed; the evaluator
+ * tree-walks this closed node set (never `eval`). `source` reads a server-resolved scalar from a
+ * registered calc source; a `weight` node with `source` reads its per-option map from a registered
+ * weight resolver instead of the inline `weights` (which is then ignored).
+ */
 type CalcExpression = {
   type: 'lit';
   value: number;
@@ -22,12 +33,16 @@ type CalcExpression = {
   operand: CalcExpression;
 } | {
   type: 'fn';
-  fn: CalcFn;
+  fn: CalcFnName;
   args: CalcExpression[];
+} | {
+  type: 'source';
+  source: string;
 } | {
   type: 'weight';
   field: string;
-  weights: Record<string, number>;
+  weights?: Record<string, number>;
+  source?: string;
 };
 //#endregion
 export { CalcExpression };

package/dist/calc/types.js

@@ -16,7 +16,8 @@ const CALC_FNS = [
 	"ceil",
 	"floor"
 ];
+const isCalcFn = (v) => CALC_FNS.includes(v);
 //#endregion
-export { CALC_FNS, CALC_OPS };
+export { CALC_FNS, CALC_OPS, isCalcFn };
 
 //# sourceMappingURL=types.js.map

package/dist/calc/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../src/calc/types.ts"],"sourcesContent":["/** Canonical operator grammar; `CalcExpression`, `normalizeCalc`, and the admin editor's jsonSchema all derive from this list. */\nexport const CALC_OPS = ['+', '-', '*', '/', '%'] as const\nexport type CalcOp = (typeof CALC_OPS)[number]\n\n/** Canonical function grammar; same single source of truth as `CALC_OPS`. */\nexport const CALC_FNS = ['min', 'max', 'round', 'abs', 'ceil', 'floor'] as const\nexport type CalcFn = (typeof CALC_FNS)[number]\n\n/** Recursion guard shared by `normalizeCalc` (parse) and `evaluate` (walk) so both bound depth identically. */\nexport const MAX_DEPTH = 64\n\n/** A serializable, safe-by-construction calculation expression. No strings are parsed; the evaluator tree-walks this closed node set (never `eval`). */\nexport type CalcExpression =\n\t| { type: 'lit'; value: number }\n\t| { type: 'ref'; field: string }\n\t| { type: 'op'; op: CalcOp; left: CalcExpression; right: CalcExpression }\n\t| { type: 'neg'; operand: CalcExpression }\n\t| { type: 'fn'; fn: CalcFn; args: CalcExpression[] }\n\t| { type: 'weight'; field: string; weights: Record<string, number> }\n"],"mappings":";;AACA,MAAa,WAAW;CAAC;CAAK;CAAK;CAAK;CAAK;AAAG;;AAIhD,MAAa,WAAW;CAAC;CAAO;CAAO;CAAS;CAAO;CAAQ;AAAO"}
+{"version":3,"file":"types.js","names":[],"sources":["../../src/calc/types.ts"],"sourcesContent":["/** Canonical operator grammar; `CalcExpression`, `normalizeCalc`, and the admin editor's jsonSchema all derive from this list. */\nexport const CALC_OPS = ['+', '-', '*', '/', '%'] as const\nexport type CalcOp = (typeof CALC_OPS)[number]\n\n/** Canonical function grammar; same single source of truth as `CALC_OPS`. */\nexport const CALC_FNS = ['min', 'max', 'round', 'abs', 'ceil', 'floor'] as const\nexport type CalcFn = (typeof CALC_FNS)[number]\n\nexport const isCalcFn = (v: unknown): v is CalcFn => (CALC_FNS as readonly unknown[]).includes(v)\n\n/**\n * A function slot in the AST: a built-in, or a host-registered function name (plugin option\n * `calc.functions`). The intersection trick keeps built-in autocomplete while admitting any\n * registered key; `normalizeCalc` gates which names are actually valid.\n */\nexport type CalcFnName = CalcFn | (string & {})\n\n/** Recursion guard shared by `normalizeCalc` (parse) and `evaluate` (walk) so both bound depth identically. */\nexport const MAX_DEPTH = 64\n\n/**\n * A serializable, safe-by-construction calculation expression. No strings are parsed; the evaluator\n * tree-walks this closed node set (never `eval`). `source` reads a server-resolved scalar from a\n * registered calc source; a `weight` node with `source` reads its per-option map from a registered\n * weight resolver instead of the inline `weights` (which is then ignored).\n */\nexport type CalcExpression =\n\t| { type: 'lit'; value: number }\n\t| { type: 'ref'; field: string }\n\t| { type: 'op'; op: CalcOp; left: CalcExpression; right: CalcExpression }\n\t| { type: 'neg'; operand: CalcExpression }\n\t| { type: 'fn'; fn: CalcFnName; args: CalcExpression[] }\n\t| { type: 'source'; source: string }\n\t| { type: 'weight'; field: string; weights?: Record<string, number>; source?: string }\n"],"mappings":";;AACA,MAAa,WAAW;CAAC;CAAK;CAAK;CAAK;CAAK;AAAG;;AAIhD,MAAa,WAAW;CAAC;CAAO;CAAO;CAAS;CAAO;CAAQ;AAAO;AAGtE,MAAa,YAAY,MAA6B,SAAgC,SAAS,CAAC"}

package/dist/client/CalcExpressionBuilder.d.ts

@@ -0,0 +1,20 @@
+import { CalcSourceClientMeta } from "../fields/builtin/calculation.js";
+//#region src/client/CalcExpressionBuilder.d.ts
+type CalcExpressionBuilderProps = {
+  path?: string;
+  field?: {
+    label?: unknown;
+  };
+  readOnly?: boolean; /** Registered calc-source metadata (key, label, modes), threaded as clientProps by `buildCalculationField`. */
+  sources?: CalcSourceClientMeta[]; /** Registered custom calc function names, so client-side normalization accepts what the server accepts. */
+  functions?: string[];
+};
+/**
+ * Visual editor for the calculation field's `expression` AST, presented as a left-to-right chain.
+ * Storage shape is unchanged and `validateExpression` stays the server gate; the AST remains
+ * authorable via the API.
+ */
+declare const CalcExpressionBuilder: (props: CalcExpressionBuilderProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+export { CalcExpressionBuilder };
+//# sourceMappingURL=CalcExpressionBuilder.d.ts.map