@chelone/core 0.5.0 → 0.7.0

package/dist/form/json-text.js

@@ -1,47 +1,61 @@
+// src/form/json-text.ts
 function detectJsonShape(value) {
-  if (value === void 0) return null;
-  return typeof value === "string" ? "string" : "object";
+	if (value === void 0) return null;
+	return typeof value === "string" ? "string" : "object";
 }
 function toJsonText(value, shape, indent = 2) {
-  if (shape === "string") return typeof value === "string" ? value : "";
-  if (value === void 0) return "";
-  try {
-    return JSON.stringify(value, null, indent) ?? "";
-  } catch {
-    return "";
-  }
+	if (shape === "string") return typeof value === "string" ? value : "";
+	if (value === void 0) return "";
+	try {
+		return JSON.stringify(value, null, indent) ?? "";
+	} catch {
+		return "";
+	}
 }
 function fromJsonText(text, shape) {
-  if (shape === "string") return { value: text, parseError: null };
-  if (text.trim() === "") return { value: null, parseError: null };
-  try {
-    return { value: JSON.parse(text), parseError: null };
-  } catch (error) {
-    return {
-      value: void 0,
-      parseError: error instanceof Error ? error : new Error(String(error))
-    };
-  }
+	if (shape === "string") return {
+		value: text,
+		parseError: null
+	};
+	if (text.trim() === "") return {
+		value: null,
+		parseError: null
+	};
+	try {
+		return {
+			value: JSON.parse(text),
+			parseError: null
+		};
+	} catch (error) {
+		return {
+			value: void 0,
+			parseError: error instanceof Error ? error : new Error(String(error))
+		};
+	}
 }
 function formatJsonValue(value, indent = 2) {
-  try {
-    const parsed = typeof value === "string" ? parseOrKeep(value) : { value, ok: true };
-    if (!parsed.ok) return value;
-    return JSON.stringify(parsed.value, null, indent) ?? String(value);
-  } catch {
-    return String(value);
-  }
+	try {
+		if (typeof value === "string") {
+			const parsed = parseOrKeep(value);
+			if (!parsed.ok) return value;
+			return JSON.stringify(parsed.value, null, indent) ?? value;
+		}
+		return JSON.stringify(value, null, indent) ?? String(value);
+	} catch {
+		return String(value);
+	}
 }
 function parseOrKeep(text) {
-  try {
-    return { value: JSON.parse(text), ok: true };
-  } catch {
-    return { value: text, ok: false };
-  }
+	try {
+		return {
+			value: JSON.parse(text),
+			ok: true
+		};
+	} catch {
+		return {
+			value: text,
+			ok: false
+		};
+	}
 }
-export {
-  detectJsonShape,
-  formatJsonValue,
-  fromJsonText,
-  toJsonText
-};
+export { detectJsonShape, formatJsonValue, fromJsonText, toJsonText };

package/dist/form/save-pipeline.d.ts

@@ -1,4 +1,4 @@
-import { type StandardSchemaV1 } from "@tanstack/form-core";
+import { type FormValidateFn, type FormValidateOrFn, type StandardSchemaV1 } from "@tanstack/form-core";
 import type { FormLevelValidate } from "./form-controller.js";
 /**
  * ra parity (exact semantics, TOP-LEVEL keys only): `null`, `''` and
@@ -10,7 +10,7 @@ import type { FormLevelValidate } from "./form-controller.js";
  * narrower than `TValues` (ra types it the same way; the DataProvider
  * receives partials by contract).
  */
-export declare function sanitizeEmptyValues<TValues extends object>(values: TValues, record?: object): TValues;
+export declare function sanitizeEmptyValues<TValues>(values: TValues, record?: object): TValues;
 /**
  * form-core's "global form validation error" shape: `form` is the form-level
  * error, `fields` maps field paths (dot/bracket, `items[0].sku`) to errors.
@@ -27,8 +27,6 @@ export interface FormErrorMapValue {
  * Nullish entries are dropped; returns `undefined` when nothing remains.
  */
 export declare function toFormErrorMapValue(errors: Record<string, unknown> | null | undefined): FormErrorMapValue | undefined;
-/** Thenable detection — how the pipeline tells async validate fns from sync ones. */
-export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
 export interface ComposeFormValidatorConfig<TFormData> {
     /** Resource schema (zod or any Standard Schema) — the D6 default validator. */
     schema?: StandardSchemaV1<TFormData, unknown>;
@@ -38,8 +36,10 @@ export interface ComposeFormValidatorConfig<TFormData> {
      * The user's own `formOptions.validators.onDynamic` escape hatch (fn or
      * Standard Schema) — composed after the schema and validate fn.
      */
-    userValidator?: unknown;
+    userValidator?: FormValidateOrFn<TFormData>;
 }
+/** What form-core hands a form-level validator fn: `value` and `formApi`. */
+export type FormValidatorProps<TFormData> = Parameters<FormValidateFn<TFormData>>[0];
 /**
  * Composes the D6 validator stack into ONE sync `onDynamic` validator:
  * schema -> validate fn (sync results only) -> user onDynamic. Field errors
@@ -57,6 +57,4 @@ export interface ComposeFormValidatorConfig<TFormData> {
  *
  * Returns `undefined` when there is nothing to compose.
  */
-export declare function composeFormValidator<TFormData>(config: ComposeFormValidatorConfig<TFormData>): ((props: {
-    value: TFormData;
-}) => unknown) | undefined;
+export declare function composeFormValidator<TFormData>(config: ComposeFormValidatorConfig<TFormData>): ((props: FormValidatorProps<TFormData>) => FormErrorMapValue | undefined) | undefined;

package/dist/form/save-pipeline.js

@@ -1,88 +1,97 @@
-import { standardSchemaValidators, isStandardSchemaValidator } from "@tanstack/form-core";
+import { isRecord, isThenable } from "../guards.js";
+import { isStandardSchemaValidator, standardSchemaValidators } from "@tanstack/form-core";
+// src/form/save-pipeline.ts
+/**
+* ra parity (exact semantics, TOP-LEVEL keys only): `null`, `''` and
+* `undefined` values become `null` when the key exists on `record`, and are
+* OMITTED otherwise; `0`, `false`, empty arrays and empty objects are NOT
+* empty and pass through. Always returns a fresh object.
+*
+* NOTE the return type is nominal — omitted keys make the runtime value
+* narrower than `TValues` (ra types it the same way; the DataProvider
+* receives partials by contract).
+*/
 function sanitizeEmptyValues(values, record) {
-  const result = {};
-  for (const [key, value] of Object.entries(values)) {
-    if (value === void 0 || value === null || value === "") {
-      if (record && key in record) result[key] = null;
-    } else {
-      result[key] = value;
-    }
-  }
-  return result;
+	if (typeof values !== "object" || values === null) return values;
+	const result = {};
+	for (const [key, value] of Object.entries(values)) if (value === void 0 || value === null || value === "") {
+		if (record && key in record) result[key] = null;
+	} else result[key] = value;
+	return result;
 }
+/**
+* Converts an ra-shaped error record (field path -> error, `root` reserved
+* for the form-level message) — the form-level validate fn contract AND the
+* P4 save `FieldErrors` contract — into form-core's global error-map value.
+* Nullish entries are dropped; returns `undefined` when nothing remains.
+*/
 function toFormErrorMapValue(errors) {
-  if (errors == null) return void 0;
-  const { root, ...rest } = errors;
-  const fields = {};
-  for (const [key, value] of Object.entries(rest)) {
-    if (value != null) fields[key] = value;
-  }
-  if (root == null && Object.keys(fields).length === 0) return void 0;
-  return { form: root ?? void 0, fields };
-}
-function isThenable(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
-}
-function isRecordObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+	if (errors == null) return void 0;
+	const { root, ...rest } = errors;
+	const fields = {};
+	for (const [key, value] of Object.entries(rest)) if (value != null) fields[key] = value;
+	if (root == null && Object.keys(fields).length === 0) return void 0;
+	return {
+		form: root ?? void 0,
+		fields
+	};
 }
+/**
+* Composes the D6 validator stack into ONE sync `onDynamic` validator:
+* schema -> validate fn (sync results only) -> user onDynamic. Field errors
+* merge FIRST-WINS per path (ra's composeValidators short-circuit parity);
+* the form-level slot also keeps the first non-nullish value.
+*
+* The composed validator runs on the SYNC slot deliberately: async
+* form-level validators do not block a field-less `handleSubmit` (probed on
+* form-core 1.33), so vanilla submit-only forms would save invalid data.
+* An async validate fn is detected on its first call, skipped here from then
+* on, and re-run by the submit pipeline instead (on-submit semantics). The
+* pipeline absorbs sync AND async results from the latched fn — ra's
+* contract legally mixes sync fast-path errors with async server checks, and
+* a latched fn's later sync error can only surface through the pipeline.
+*
+* Returns `undefined` when there is nothing to compose.
+*/
 function composeFormValidator(config) {
-  const { schema, validate, userValidator } = config;
-  if (!schema && !validate && !userValidator) return void 0;
-  let validateIsAsync = false;
-  return (props) => {
-    let formError;
-    const fields = {};
-    const absorb = (result) => {
-      if (result == null) return;
-      if (isRecordObject(result) && "fields" in result) {
-        const global = result;
-        if (formError === void 0 && global.form != null) {
-          formError = global.form;
-        }
-        if (isRecordObject(global.fields)) {
-          for (const [key, error] of Object.entries(global.fields)) {
-            if (error != null && !(key in fields)) fields[key] = error;
-          }
-        }
-        return;
-      }
-      if (formError === void 0) formError = result;
-    };
-    if (schema) {
-      absorb(
-        standardSchemaValidators.validate(
-          { value: props.value, validationSource: "form" },
-          schema
-        )
-      );
-    }
-    if (validate && !validateIsAsync) {
-      const result = validate(props.value);
-      if (isThenable(result)) {
-        validateIsAsync = true;
-        void Promise.resolve(result).catch(() => void 0);
-      } else {
-        absorb(toFormErrorMapValue(result));
-      }
-    }
-    if (userValidator) {
-      absorb(
-        isStandardSchemaValidator(userValidator) ? standardSchemaValidators.validate(
-          { value: props.value, validationSource: "form" },
-          userValidator
-        ) : userValidator(props)
-      );
-    }
-    if (formError === void 0 && Object.keys(fields).length === 0) {
-      return void 0;
-    }
-    return { form: formError, fields };
-  };
+	const { schema, validate, userValidator } = config;
+	if (!schema && !validate && !userValidator) return void 0;
+	/** Latched on the first thenable result — async fns never run in the sync slot again. */
+	let validateIsAsync = false;
+	return (props) => {
+		let formError;
+		const fields = {};
+		const absorb = (result) => {
+			if (result == null) return;
+			if (isRecord(result) && "fields" in result) {
+				if (formError === void 0 && result.form != null) formError = result.form;
+				if (isRecord(result.fields)) {
+					for (const [key, error] of Object.entries(result.fields)) if (error != null && !(key in fields)) fields[key] = error;
+				}
+				return;
+			}
+			if (formError === void 0) formError = result;
+		};
+		if (schema) absorb(standardSchemaValidators.validate({
+			value: props.value,
+			validationSource: "form"
+		}, schema));
+		if (validate && !validateIsAsync) {
+			const result = validate(props.value);
+			if (isThenable(result)) {
+				validateIsAsync = true;
+				Promise.resolve(result).catch(() => void 0);
+			} else absorb(toFormErrorMapValue(result));
+		}
+		if (userValidator) absorb(isStandardSchemaValidator(userValidator) ? standardSchemaValidators.validate({
+			value: props.value,
+			validationSource: "form"
+		}, userValidator) : userValidator(props));
+		if (formError === void 0 && Object.keys(fields).length === 0) return;
+		return {
+			form: formError,
+			fields
+		};
+	};
 }
-export {
-  composeFormValidator,
-  isThenable,
-  sanitizeEmptyValues,
-  toFormErrorMapValue
-};
+export { composeFormValidator, sanitizeEmptyValues, toFormErrorMapValue };

package/dist/form/set-form-values.d.ts

@@ -0,0 +1,6 @@
+import type { CheloneFormApi } from "./form-controller.js";
+/**
+ * Writes each key of `data` into the form, so a programmatic save sees the
+ * values it was handed. A key not in `data` keeps its value.
+ */
+export declare function setFormValues<TValues>(form: CheloneFormApi<TValues>, data: Partial<NoInfer<TValues>>): void;

package/dist/form/set-form-values.js

@@ -0,0 +1,10 @@
+import { toFieldName } from "./field-name.js";
+// src/form/set-form-values.ts
+/**
+* Writes each key of `data` into the form, so a programmatic save sees the
+* values it was handed. A key not in `data` keeps its value.
+*/
+function setFormValues(form, data) {
+	for (const [key, value] of Object.entries(data)) form.setFieldValue(toFieldName(key), value);
+}
+export { setFormValues };

package/dist/form/source.js

@@ -1,76 +1,108 @@
+// src/form/source.ts
+/**
+* Joins two path fragments: bracket fragments (`[0]`, `[0].sku`) concatenate
+* directly (form-core index syntax), everything else joins with a dot.
+*/
 function composeSource(parent, child) {
-  if (!child) return parent;
-  if (!parent) return child;
-  return child.startsWith("[") ? `${parent}${child}` : `${parent}.${child}`;
+	if (!child) return parent;
+	if (!parent) return child;
+	return child.startsWith("[") ? `${parent}${child}` : `${parent}.${child}`;
 }
+/**
+* Rewrite a dot-spelled array index as form-core's bracket spelling:
+* `tags.0.label` -> `tags[0].label`. Without it an input written with a dot
+* index binds a field named `tags.0.label`, which no validator, error or
+* field group matches, while the same path read as data (a `DataTable.Col`)
+* works — form-core's `getBy`/`setBy` accept both spellings, so only the
+* FIELD NAME differs.
+*
+* Only a digits-only member that FOLLOWS another member is an index: a
+* leading numeral (`0.a`) is a field name, and bracket spellings, non-numeric
+* members and the empty string pass through untouched. Labels never go
+* through this — translation keys keep the spelling as written.
+*/
 function normalizeSource(source) {
-  let out = "";
-  let depth = 0;
-  let afterMember = false;
-  for (let i = 0; i < source.length; i++) {
-    const char = source[i];
-    if (char === "[") depth++;
-    if (char === "]") depth--;
-    if (char === "." && depth === 0 && afterMember) {
-      let end = i + 1;
-      while (end < source.length && source[end] !== "." && source[end] !== "[") {
-        end++;
-      }
-      const member = source.slice(i + 1, end);
-      if (/^\d+$/.test(member)) {
-        out += `[${member}]`;
-        i = end - 1;
-        continue;
-      }
-    }
-    out += char;
-    if (char !== ".") afterMember = true;
-  }
-  return out;
+	let out = "";
+	/** Bracket depth: inside a group the spelling is already form-core's. */
+	let depth = 0;
+	/** True once a member has been emitted — a dot before the next one is a join. */
+	let afterMember = false;
+	for (let i = 0; i < source.length; i++) {
+		const char = source[i];
+		if (char === "[") depth++;
+		if (char === "]") depth--;
+		if (char === "." && depth === 0 && afterMember) {
+			let end = i + 1;
+			while (end < source.length && source[end] !== "." && source[end] !== "[") end++;
+			const member = source.slice(i + 1, end);
+			if (/^\d+$/.test(member)) {
+				out += `[${member}]`;
+				i = end - 1;
+				continue;
+			}
+		}
+		out += char;
+		if (char !== ".") afterMember = true;
+	}
+	return out;
 }
-const rootSourceScope = {
-  getSource: (source) => normalizeSource(source),
-  getLabel: (source) => source
+/**
+* What a top-level form provides: the identity scope for everything but a
+* dot-spelled index, which it rewrites to form-core's bracket spelling.
+*/
+var rootSourceScope = {
+	getSource: (source) => normalizeSource(source),
+	getLabel: (source) => source
 };
+/**
+* The scope an array input provides to its iterator: sources nest under the
+* array's own (scoped) path, labels under its index-free label path.
+*
+* `getSource('')` resolves the array field itself — how an iterator finds
+* the path it pushes/removes on.
+*/
 function createArraySourceScope(parent, arraySource) {
-  const arrayPath = parent.getSource(arraySource);
-  return {
-    // Normalizing the JOIN, not just the child: a child of `0` composes to
-    // `tags.0`, where the index only follows a member once the array is there.
-    // Row and locale scopes need neither — they hand the whole path to a
-    // parent that normalizes it.
-    getSource: (source) => normalizeSource(composeSource(arrayPath, source)),
-    getLabel: (source) => parent.getLabel(composeSource(arraySource, source))
-  };
+	const arrayPath = parent.getSource(arraySource);
+	return {
+		getSource: (source) => normalizeSource(composeSource(arrayPath, source)),
+		getLabel: (source) => parent.getLabel(composeSource(arraySource, source))
+	};
 }
+/**
+* The scope an iterator row provides to its children: sources gain the row's
+* `[index]` fragment; labels pass through UNCHANGED so translation keys stay
+* index-free (`orders.date`, not `orders.0.date`).
+*
+* Scalar rows (`<ArrayInput source="tags">` with a sourceless child) call
+* `getSource('')` and bind the row itself (`tags[2]`).
+*/
 function createRowSourceScope(parent, index) {
-  return {
-    getSource: (source) => parent.getSource(source ? `[${index}].${source}` : `[${index}]`),
-    getLabel: (source) => parent.getLabel(source)
-  };
+	return {
+		getSource: (source) => parent.getSource(source ? `[${index}].${source}` : `[${index}]`),
+		getLabel: (source) => parent.getLabel(source)
+	};
 }
+/**
+* The scope a translatable group provides for one locale: each child source
+* gains the locale as a trailing member (`title` -> `title.fr`). Labels pass
+* through so every locale shares one translation key.
+*
+* A translatable group has no value of its own, so a sourceless child has
+* nothing to bind and throws.
+*/
 function createLocaleSourceScope(parent, locale) {
-  const requireSource = (source) => {
-    if (!source) {
-      throw new Error("Children of a translatable group must have a source");
-    }
-  };
-  return {
-    getSource: (source) => {
-      requireSource(source);
-      return parent.getSource(`${source}.${locale}`);
-    },
-    getLabel: (source) => {
-      requireSource(source);
-      return parent.getLabel(source);
-    }
-  };
+	const requireSource = (source) => {
+		if (!source) throw new Error("Children of a translatable group must have a source");
+	};
+	return {
+		getSource: (source) => {
+			requireSource(source);
+			return parent.getSource(`${source}.${locale}`);
+		},
+		getLabel: (source) => {
+			requireSource(source);
+			return parent.getLabel(source);
+		}
+	};
 }
-export {
-  composeSource,
-  createArraySourceScope,
-  createLocaleSourceScope,
-  createRowSourceScope,
-  normalizeSource,
-  rootSourceScope
-};
+export { composeSource, createArraySourceScope, createLocaleSourceScope, createRowSourceScope, normalizeSource, rootSourceScope };

package/dist/form/text-of.d.ts

@@ -0,0 +1,2 @@
+/** A form value as text: `""` for `null` and `undefined`, the string itself, `String(value)` for anything else. */
+export declare function textOf(value: unknown): string;

package/dist/form/text-of.js

@@ -0,0 +1,7 @@
+// src/form/text-of.ts
+/** A form value as text: `""` for `null` and `undefined`, the string itself, `String(value)` for anything else. */
+function textOf(value) {
+	if (value == null) return "";
+	return typeof value === "string" ? value : String(value);
+}
+export { textOf };