@10x-media/form-builder 0.1.0-beta.2 → 0.1.0-beta.21

package/dist/calc/normalizeCalc.js

@@ -1,23 +1,9 @@
+import { CALC_OPS, isCalcFn } from "./types.js";
 //#region src/calc/normalizeCalc.ts
-const MAX_DEPTH = 64;
-const OP_SET = new Set([
-	"+",
-	"-",
-	"*",
-	"/",
-	"%"
-]);
-const FN_SET = new Set([
-	"min",
-	"max",
-	"round",
-	"abs",
-	"ceil",
-	"floor"
-]);
+const isOp = (v) => CALC_OPS.includes(v);
 const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-const normalizeNode = (value, depth) => {
-	if (depth > MAX_DEPTH) return void 0;
+const normalizeNode = (value, depth, allowed) => {
+	if (depth > 64) return void 0;
 	if (!isRecord(value)) return void 0;
 	switch (value.type) {
 		case "lit": {
@@ -38,10 +24,10 @@ const normalizeNode = (value, depth) => {
 		}
 		case "op": {
 			const { op, left, right } = value;
-			if (typeof op !== "string" || !OP_SET.has(op)) return void 0;
-			const l = normalizeNode(left, depth + 1);
+			if (!isOp(op)) return void 0;
+			const l = normalizeNode(left, depth + 1, allowed);
 			if (!l) return void 0;
-			const r = normalizeNode(right, depth + 1);
+			const r = normalizeNode(right, depth + 1, allowed);
 			if (!r) return void 0;
 			return {
 				type: "op",
@@ -51,7 +37,7 @@ const normalizeNode = (value, depth) => {
 			};
 		}
 		case "neg": {
-			const operand = normalizeNode(value.operand, depth + 1);
+			const operand = normalizeNode(value.operand, depth + 1, allowed);
 			if (!operand) return void 0;
 			return {
 				type: "neg",
@@ -60,11 +46,12 @@ const normalizeNode = (value, depth) => {
 		}
 		case "fn": {
 			const { fn, args } = value;
-			if (typeof fn !== "string" || !FN_SET.has(fn)) return void 0;
+			if (typeof fn !== "string") return void 0;
+			if (!isCalcFn(fn) && !allowed?.functions?.has(fn)) return void 0;
 			if (!Array.isArray(args)) return void 0;
 			const normalizedArgs = [];
 			for (const arg of args) {
-				const a = normalizeNode(arg, depth + 1);
+				const a = normalizeNode(arg, depth + 1, allowed);
 				if (!a) return void 0;
 				normalizedArgs.push(a);
 			}
@@ -74,26 +61,48 @@ const normalizeNode = (value, depth) => {
 				args: normalizedArgs
 			};
 		}
+		case "source": {
+			const { source } = value;
+			if (typeof source !== "string") return void 0;
+			if (!allowed?.sources?.has(source)) return void 0;
+			return {
+				type: "source",
+				source
+			};
+		}
 		case "weight": {
-			const { field, weights } = value;
+			const { field, weights, source } = value;
 			if (typeof field !== "string") return void 0;
-			if (!isRecord(weights)) return void 0;
-			const normalizedWeights = {};
-			for (const [k, v] of Object.entries(weights)) {
-				if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
-				normalizedWeights[k] = v;
+			if (source !== void 0) {
+				if (typeof source !== "string" || !allowed?.sources?.has(source)) return void 0;
+			}
+			let normalizedWeights;
+			if (weights !== void 0) {
+				if (!isRecord(weights)) return void 0;
+				normalizedWeights = {};
+				for (const [k, v] of Object.entries(weights)) {
+					if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+					normalizedWeights[k] = v;
+				}
 			}
+			if (normalizedWeights === void 0 && source === void 0) return void 0;
 			return {
 				type: "weight",
 				field,
-				weights: normalizedWeights
+				...normalizedWeights !== void 0 ? { weights: normalizedWeights } : {},
+				...typeof source === "string" ? { source } : {}
 			};
 		}
 		default: return;
 	}
 };
-/** Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded at 64), otherwise undefined. Never throws. */
-const normalizeCalc = (value) => normalizeNode(value, 0);
+/**
+* Structural guard: returns a valid CalcExpression if `value` is structurally sound (depth-guarded
+* at 64), otherwise undefined. Never throws. `allowed` admits registered extension names (source
+* keys, custom function names); without it only the built-in grammar passes, so an un-threaded
+* caller can never validate an expression the evaluator has no values for.
+*/
+const normalizeCalc = (value, allowed) => normalizeNode(value, 0, allowed);
 //#endregion
 export { normalizeCalc };
 

package/dist/calc/normalizeCalc.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalizeCalc.js","names":[],"sources":["../../src/calc/normalizeCalc.ts"],"sourcesContent":["import type { CalcExpression } from './types'\n\nconst MAX_DEPTH = 64\n\nconst OP_SET = new Set(['+', '-', '*', '/', '%'])\nconst FN_SET = new Set(['min', 'max', 'round', 'abs', 'ceil', 'floor'])\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 (typeof op !== 'string' || !OP_SET.has(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: op as '+' | '-' | '*' | '/' | '%', 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 (typeof fn !== 'string' || !FN_SET.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)\n\t\t\t\tif (!a) return undefined\n\t\t\t\tnormalizedArgs.push(a)\n\t\t\t}\n\t\t\treturn {\n\t\t\t\ttype: 'fn',\n\t\t\t\tfn: fn as 'min' | 'max' | 'round' | 'abs' | 'ceil' | 'floor',\n\t\t\t\targs: normalizedArgs,\n\t\t\t}\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":";AAEA,MAAM,YAAY;AAElB,MAAM,SAAS,IAAI,IAAI;CAAC;CAAK;CAAK;CAAK;CAAK;AAAG,CAAC;AAChD,MAAM,SAAS,IAAI,IAAI;CAAC;CAAO;CAAO;CAAS;CAAO;CAAQ;AAAO,CAAC;AAEtE,MAAM,YAAY,MACjB,MAAM,QAAQ,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC;AAExD,MAAM,iBAAiB,OAAgB,UAA8C;CACpF,IAAI,QAAQ,WAAW,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,OAAO,OAAO,YAAY,CAAC,OAAO,IAAI,EAAE,GAAG,OAAO,KAAA;GACtD,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;IAAU;IAAmC,MAAM;IAAG,OAAO;GAAE;EAC/E;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,OAAO,OAAO,YAAY,CAAC,OAAO,IAAI,EAAE,GAAG,OAAO,KAAA;GACtD,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;IACN,MAAM;IACF;IACJ,MAAM;GACP;EACD;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

@@ -1,5 +1,22 @@
 //#region src/calc/types.d.ts
-/** A serializable, safe-by-construction calculation expression. No strings are parsed; the evaluator tree-walks this closed node set (never `eval`). */
+/** Canonical operator grammar; `CalcExpression`, `normalizeCalc`, and the admin editor's jsonSchema all derive from this list. */
+declare const CALC_OPS: readonly ["+", "-", "*", "/", "%"];
+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 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;
@@ -8,7 +25,7 @@ type CalcExpression = {
   field: string;
 } | {
   type: 'op';
-  op: '+' | '-' | '*' | '/' | '%';
+  op: CalcOp;
   left: CalcExpression;
   right: CalcExpression;
 } | {
@@ -16,12 +33,16 @@ type CalcExpression = {
   operand: CalcExpression;
 } | {
   type: 'fn';
-  fn: 'min' | 'max' | 'round' | 'abs' | 'ceil' | 'floor';
+  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

@@ -0,0 +1,23 @@
+//#region src/calc/types.ts
+/** Canonical operator grammar; `CalcExpression`, `normalizeCalc`, and the admin editor's jsonSchema all derive from this list. */
+const CALC_OPS = [
+	"+",
+	"-",
+	"*",
+	"/",
+	"%"
+];
+/** Canonical function grammar; same single source of truth as `CALC_OPS`. */
+const CALC_FNS = [
+	"min",
+	"max",
+	"round",
+	"abs",
+	"ceil",
+	"floor"
+];
+const isCalcFn = (v) => CALC_FNS.includes(v);
+//#endregion
+export { CALC_FNS, CALC_OPS, isCalcFn };
+
+//# sourceMappingURL=types.js.map

package/dist/calc/types.js.map

@@ -0,0 +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\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/ByteSizeField.d.ts

@@ -0,0 +1,29 @@
+import { TranslationKey } from "../translations/keys.js";
+
+//#region src/client/ByteSizeField.d.ts
+/** Props: standard number field client props; label and description arrive resolved on `field`. */
+type ByteSizeFieldProps = {
+  path?: string;
+  field?: {
+    label?: unknown;
+    admin?: {
+      description?: unknown;
+    };
+  };
+  label?: unknown;
+  /**
+   * Field description as a translation key, resolved client-side. Payload drops `admin.description`
+   * functions from client fields, so a translated description must travel as a key; a static
+   * `admin.description` string still renders when this is unset.
+   */
+  descriptionKey?: TranslationKey;
+};
+/**
+ * The `Field` mounted on a byte-count number config field (the file field's `maxSize`): a plain
+ * number input that live-previews the value as a human-readable size ('= 2.5 MB') so authors are
+ * not left decoding raw bytes. Stores the raw byte number unchanged.
+ */
+declare const ByteSizeField: (props: ByteSizeFieldProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+export { ByteSizeField };
+//# sourceMappingURL=ByteSizeField.d.ts.map

package/dist/client/ByteSizeField.js

@@ -0,0 +1,58 @@
+"use client";
+import { formatBytes } from "../uploads/formatBytes.js";
+import { useTranslation as useTranslation$1 } from "../translations/useTranslation.js";
+import { toStaticLabel } from "./toStaticLabel.js";
+import { FieldDescription, FieldLabel, useField } from "@payloadcms/ui";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/client/ByteSizeField.tsx
+/**
+* The `Field` mounted on a byte-count number config field (the file field's `maxSize`): a plain
+* number input that live-previews the value as a human-readable size ('= 2.5 MB') so authors are
+* not left decoding raw bytes. Stores the raw byte number unchanged.
+*/
+const ByteSizeField = (props) => {
+	const { path, setValue, value } = useField({ path: props.path });
+	const label = toStaticLabel(props.field?.label ?? props.label);
+	const { t } = useTranslation$1();
+	const description = props.descriptionKey ? t(props.descriptionKey) : toStaticLabel(props.field?.admin?.description);
+	const handleChange = (event) => {
+		if (event.target.value === "") {
+			setValue(null);
+			return;
+		}
+		const parsed = Number(event.target.value);
+		if (Number.isFinite(parsed)) setValue(parsed);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: "field-type number",
+		style: { marginBlockEnd: "1rem" },
+		children: [/* @__PURE__ */ jsx(FieldLabel, {
+			label,
+			path
+		}), /* @__PURE__ */ jsxs("div", {
+			className: "field-type__wrap",
+			children: [
+				/* @__PURE__ */ jsx("input", {
+					id: `field-${path.replace(/\./g, "__")}`,
+					min: 0,
+					name: path,
+					onChange: handleChange,
+					type: "number",
+					value: typeof value === "number" ? value : ""
+				}),
+				typeof value === "number" && value > 0 ? /* @__PURE__ */ jsx("div", {
+					className: "field-description",
+					children: `= ${formatBytes(value)}`
+				}) : null,
+				/* @__PURE__ */ jsx(FieldDescription, {
+					description,
+					path
+				})
+			]
+		})]
+	});
+};
+//#endregion
+export { ByteSizeField };
+
+//# sourceMappingURL=ByteSizeField.js.map

package/dist/client/ByteSizeField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByteSizeField.js","names":["useTranslation"],"sources":["../../src/client/ByteSizeField.tsx"],"sourcesContent":["'use client'\n\nimport { FieldDescription, FieldLabel, useField } from '@payloadcms/ui'\nimport type { ChangeEvent } from 'react'\nimport type { TranslationKey } from '../translations/keys'\nimport { useTranslation } from '../translations/useTranslation'\nimport { formatBytes } from '../uploads/formatBytes'\nimport { toStaticLabel } from './toStaticLabel'\n\n/** Props: standard number field client props; label and description arrive resolved on `field`. */\nexport type ByteSizeFieldProps = {\n\tpath?: string\n\tfield?: { label?: unknown; admin?: { description?: unknown } }\n\tlabel?: unknown\n\t/**\n\t * Field description as a translation key, resolved client-side. Payload drops `admin.description`\n\t * functions from client fields, so a translated description must travel as a key; a static\n\t * `admin.description` string still renders when this is unset.\n\t */\n\tdescriptionKey?: TranslationKey\n}\n\n/**\n * The `Field` mounted on a byte-count number config field (the file field's `maxSize`): a plain\n * number input that live-previews the value as a human-readable size ('= 2.5 MB') so authors are\n * not left decoding raw bytes. Stores the raw byte number unchanged.\n */\nexport const ByteSizeField = (props: ByteSizeFieldProps) => {\n\tconst { path, setValue, value } = useField<number>({ path: props.path })\n\tconst label = toStaticLabel(props.field?.label ?? props.label)\n\tconst { t } = useTranslation()\n\tconst description = props.descriptionKey\n\t\t? t(props.descriptionKey)\n\t\t: toStaticLabel(props.field?.admin?.description)\n\n\tconst handleChange = (event: ChangeEvent<HTMLInputElement>) => {\n\t\tif (event.target.value === '') {\n\t\t\tsetValue(null)\n\t\t\treturn\n\t\t}\n\t\tconst parsed = Number(event.target.value)\n\t\tif (Number.isFinite(parsed)) {\n\t\t\tsetValue(parsed)\n\t\t}\n\t}\n\n\treturn (\n\t\t<div className=\"field-type number\" style={{ marginBlockEnd: '1rem' }}>\n\t\t\t<FieldLabel label={label} path={path} />\n\t\t\t<div className=\"field-type__wrap\">\n\t\t\t\t<input\n\t\t\t\t\tid={`field-${path.replace(/\\./g, '__')}`}\n\t\t\t\t\tmin={0}\n\t\t\t\t\tname={path}\n\t\t\t\t\tonChange={handleChange}\n\t\t\t\t\ttype=\"number\"\n\t\t\t\t\tvalue={typeof value === 'number' ? value : ''}\n\t\t\t\t/>\n\t\t\t\t{typeof value === 'number' && value > 0 ? (\n\t\t\t\t\t<div className=\"field-description\">{`= ${formatBytes(value)}`}</div>\n\t\t\t\t) : null}\n\t\t\t\t<FieldDescription description={description} path={path} />\n\t\t\t</div>\n\t\t</div>\n\t)\n}\n"],"mappings":";;;;;;;;;;;;AA2BA,MAAa,iBAAiB,UAA8B;CAC3D,MAAM,EAAE,MAAM,UAAU,UAAU,SAAiB,EAAE,MAAM,MAAM,KAAK,CAAC;CACvE,MAAM,QAAQ,cAAc,MAAM,OAAO,SAAS,MAAM,KAAK;CAC7D,MAAM,EAAE,MAAMA,iBAAe;CAC7B,MAAM,cAAc,MAAM,iBACvB,EAAE,MAAM,cAAc,IACtB,cAAc,MAAM,OAAO,OAAO,WAAW;CAEhD,MAAM,gBAAgB,UAAyC;EAC9D,IAAI,MAAM,OAAO,UAAU,IAAI;GAC9B,SAAS,IAAI;GACb;EACD;EACA,MAAM,SAAS,OAAO,MAAM,OAAO,KAAK;EACxC,IAAI,OAAO,SAAS,MAAM,GACzB,SAAS,MAAM;CAEjB;CAEA,OACC,qBAAC,OAAD;EAAK,WAAU;EAAoB,OAAO,EAAE,gBAAgB,OAAO;YAAnE,CACC,oBAAC,YAAD;GAAmB;GAAa;EAAO,CAAA,GACvC,qBAAC,OAAD;GAAK,WAAU;aAAf;IACC,oBAAC,SAAD;KACC,IAAI,SAAS,KAAK,QAAQ,OAAO,IAAI;KACrC,KAAK;KACL,MAAM;KACN,UAAU;KACV,MAAK;KACL,OAAO,OAAO,UAAU,WAAW,QAAQ;IAC3C,CAAA;IACA,OAAO,UAAU,YAAY,QAAQ,IACrC,oBAAC,OAAD;KAAK,WAAU;eAAqB,KAAK,YAAY,KAAK;IAAS,CAAA,IAChE;IACJ,oBAAC,kBAAD;KAA+B;KAAmB;IAAO,CAAA;GACrD;IACD;;AAEP"}

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