@chelone/core 0.5.0 → 0.7.0

package/dist/form/input-binding.js

@@ -1,125 +1,176 @@
+import { isThenable } from "../guards.js";
+import { toFieldName } from "./field-name.js";
+import { composeValidators, isRequired } from "./validators.js";
 import { FieldApi } from "@tanstack/form-core";
-import { isThenable } from "./save-pipeline.js";
-import { isRequired, composeValidators } from "./validators.js";
+// src/form/input-binding.ts
+/**
+* ra's default format: render `null`/`undefined` as `''` so text inputs stay
+* controlled; every other value (including `0`/`false`) passes through.
+*/
 function defaultFormat(value) {
-  return value == null ? "" : value;
+	return value == null ? "" : value;
 }
+/**
+* ra's default parse: store a cleared text input (`''`) as `null` — the
+* shape most backends expect; every other value (including `0`/`false`)
+* passes through.
+*/
 function defaultParse(input) {
-  return input === "" ? null : input;
+	return input === "" ? null : input;
+}
+/** A validator list (ra call style) rather than a single validator. */
+function isValidatorList(validate) {
+	return Array.isArray(validate);
 }
 function createFieldBinding(form, options) {
-  const { source } = options;
-  const name = source;
-  let current = options;
-  const runValidators = (value) => {
-    const runFns = () => {
-      const { validate } = current;
-      if (!validate) return void 0;
-      const composed = Array.isArray(validate) ? composeValidators(validate) : validate;
-      const meta = { source, ...current.validatorMeta };
-      return composed(value, form.store.state.values, meta);
-    };
-    const { schema } = current;
-    if (schema) {
-      const outcome = schema["~standard"].validate(value);
-      if (isThenable(outcome)) {
-        return outcome.then((resolved) => {
-          const issues2 = resolved.issues;
-          return issues2 && issues2.length > 0 ? [...issues2] : runFns();
-        });
-      }
-      const issues = outcome.issues;
-      if (issues && issues.length > 0) return [...issues];
-    }
-    return runFns();
-  };
-  let asyncLatched = false;
-  let pendingRun;
-  const onDynamicAsync = async ({
-    value
-  }) => {
-    const held = pendingRun;
-    pendingRun = void 0;
-    const result = held && Object.is(held.value, value) ? held.result : runValidators(value);
-    return await result ?? void 0;
-  };
-  const bindingValidators = {
-    onDynamic: ({ value }) => {
-      if (asyncLatched) return void 0;
-      const result = runValidators(value);
-      if (isThenable(result)) {
-        asyncLatched = true;
-        pendingRun = { value, result };
-        bindingValidators.onDynamicAsync = onDynamicAsync;
-        return void 0;
-      }
-      return result ?? void 0;
-    }
-  };
-  const buildOptions = () => ({
-    form,
-    name,
-    defaultValue: current.defaultValue !== void 0 && form.getFieldValue(name) === void 0 ? current.defaultValue : void 0,
-    validators: bindingValidators
-  });
-  const field = new FieldApi(buildOptions());
-  let destroyed = false;
-  let unmountField;
-  const subscriptions = /* @__PURE__ */ new Set();
-  const detach = () => {
-    const unmount = unmountField;
-    unmountField = void 0;
-    unmount?.();
-  };
-  return {
-    field,
-    source,
-    subscribe(listener) {
-      if (destroyed) return () => {
-      };
-      const storeSubscription = field.store.subscribe(listener);
-      const subscription = {
-        off: () => storeSubscription.unsubscribe()
-      };
-      const isFirst = subscriptions.size === 0;
-      subscriptions.add(subscription);
-      if (isFirst) {
-        field.update(buildOptions());
-        unmountField = field.mount();
-      }
-      return () => {
-        if (!subscriptions.delete(subscription)) return;
-        subscription.off();
-        if (subscriptions.size === 0 && !destroyed) detach();
-      };
-    },
-    getSnapshot: () => field.store.state,
-    getValue() {
-      const format = current.format ?? defaultFormat;
-      return format(field.store.state.value);
-    },
-    setValue(input) {
-      const parse = current.parse ?? defaultParse;
-      field.handleChange(parse(input));
-    },
-    blur: () => field.handleBlur(),
-    isRequired: () => isRequired(current.validate),
-    update(next) {
-      current = { source, ...next };
-      if (destroyed || unmountField === void 0) return;
-      field.update(buildOptions());
-    },
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      detach();
-      for (const subscription of subscriptions) subscription.off();
-      subscriptions.clear();
-    }
-  };
+	const { source } = options;
+	const name = toFieldName(source);
+	let current = options;
+	/**
+	* Runs the binding's validator stack against a value: field schema first
+	* (its issues short-circuit the fn validators), then the composed ra-style
+	* validators with `(value, allValues, meta)`. Synchronous while every
+	* consulted step is synchronous.
+	*/
+	const runValidators = (value) => {
+		const runFns = () => {
+			const { validate } = current;
+			if (!validate) return void 0;
+			const composed = isValidatorList(validate) ? composeValidators(validate) : validate;
+			const meta = {
+				source,
+				...current.validatorMeta
+			};
+			return composed(value, form.store.state.values, meta);
+		};
+		const { schema } = current;
+		if (schema) {
+			const outcome = schema["~standard"].validate(value);
+			if (isAsyncSchemaOutcome(outcome)) return Promise.resolve(outcome).then((resolved) => {
+				const issues = resolved.issues;
+				return issues && issues.length > 0 ? issues : runFns();
+			});
+			const issues = outcome.issues;
+			if (issues && issues.length > 0) return issues;
+		}
+		return runFns();
+	};
+	/**
+	* True once a validation run returned a thenable. From then on the sync slot
+	* stands down and the async slot (lazily injected below) owns the stack —
+	* awaited results land under the same `onDynamic` errorMap key.
+	* Deliberately sticky: un-latching on option updates would re-probe (and
+	* double-run) async validators on every render.
+	*/
+	let asyncLatched = false;
+	/** The first thenable, kept so the async slot consumes it instead of re-running the stack. */
+	let pendingRun;
+	const onDynamicAsync = async ({ value }) => {
+		const held = pendingRun;
+		pendingRun = void 0;
+		return await (held && Object.is(held.value, value) ? held.result : runValidators(value)) ?? void 0;
+	};
+	const bindingValidators = { onDynamic: ({ value }) => {
+		if (asyncLatched) return void 0;
+		const result = runValidators(value);
+		if (isThenable(result)) {
+			asyncLatched = true;
+			pendingRun = {
+				value,
+				result
+			};
+			bindingValidators.onDynamicAsync = onDynamicAsync;
+			return;
+		}
+		return result ?? void 0;
+	} };
+	/** A value for this path, spelled as form-core's `DeepValue` for the write. */
+	const toFieldData = (value) => value;
+	/**
+	* The FieldApi options for the CURRENT binding options and form values.
+	* `defaultValue` carries ra precedence, not form-core's: form-core seeds a
+	* field-level default over any untouched form value (probed on 1.33 —
+	* mount and update both overwrite), so the default is passed through ONLY
+	* while the slot is a hole (`undefined`). Re-evaluated on every attach and
+	* update, which is also what re-seeds a reopened hole after a reset.
+	*/
+	const buildOptions = () => ({
+		form,
+		name,
+		defaultValue: current.defaultValue !== void 0 && form.getFieldValue(name) === void 0 ? toFieldData(current.defaultValue) : void 0,
+		validators: bindingValidators
+	});
+	const field = new FieldApi(buildOptions());
+	let destroyed = false;
+	/** Non-undefined exactly while attached (mount cleanup). */
+	let unmountField;
+	const subscriptions = /* @__PURE__ */ new Set();
+	/** Runs the mount cleanup at most once per attach cycle. */
+	const detach = () => {
+		const unmount = unmountField;
+		unmountField = void 0;
+		unmount?.();
+	};
+	/** The binding's `format`, or the ra default, applied to the stored value. */
+	const formatValue = () => {
+		const value = field.store.state.value;
+		const { format } = current;
+		if (format !== void 0) return format(value);
+		return defaultFormat(value);
+	};
+	/** The binding's `parse`, or the ra default, applied to the input. */
+	const parseInput = (input) => {
+		const { parse } = current;
+		return toFieldData(parse ? parse(input) : defaultParse(input));
+	};
+	return {
+		field,
+		source,
+		subscribe(listener) {
+			if (destroyed) return () => {};
+			const storeSubscription = field.store.subscribe(listener);
+			const subscription = { off: () => storeSubscription.unsubscribe() };
+			const isFirst = subscriptions.size === 0;
+			subscriptions.add(subscription);
+			if (isFirst) {
+				field.update(buildOptions());
+				unmountField = field.mount();
+			}
+			return () => {
+				if (!subscriptions.delete(subscription)) return;
+				subscription.off();
+				if (subscriptions.size === 0 && !destroyed) detach();
+			};
+		},
+		getSnapshot: () => field.store.state,
+		store: field.store,
+		getValue: formatValue,
+		setValue: (input) => field.handleChange(parseInput(input)),
+		blur: () => field.handleBlur(),
+		isRequired: () => isRequired(current.validate),
+		update(next) {
+			current = {
+				source,
+				...next
+			};
+			if (destroyed || unmountField === void 0) return;
+			field.update(buildOptions());
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			detach();
+			for (const subscription of subscriptions) subscription.off();
+			subscriptions.clear();
+		}
+	};
+}
+/**
+* A schema outcome that is a thenable of an outcome. `isThenable` already
+* answers the question for any thenable; the predicate keeps the resolved
+* value typed so the async branch reads `issues` off it.
+*/
+function isAsyncSchemaOutcome(outcome) {
+	return isThenable(outcome);
 }
-export {
-  createFieldBinding,
-  defaultFormat,
-  defaultParse
-};
+export { createFieldBinding, defaultFormat, defaultParse };

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

@@ -0,0 +1,130 @@
+/**
+ * The value each input family edits, and one guard per family that reads it out
+ * of form state.
+ *
+ * The guards are total — every family has a value for every input, so an input
+ * never has to cast its own value. They convert, not validate: a value the
+ * family cannot hold lands on that family's empty value.
+ */
+/**
+ * A value read out of form state: whatever the data provider put there, until a
+ * guard names the family an input edits.
+ */
+export type FormValue = unknown;
+/** What a date input edits: the `YYYY-MM-DD`/ISO string, the epoch number, a live `Date`, or nothing. */
+export type DateInputValue = string | number | Date | null;
+/** What a file input holds: a picked `File`, the stored reference (a URL) of the file on the record, or nothing. */
+export type FileInputValue = File | string | null;
+/** The storage shape a `<WebhookEndpointInput>` edits. */
+export interface WebhookValue {
+    url: string;
+    secret: string;
+    eventTypes: string[];
+    lastDelivery?: {
+        status: "ok" | "failed" | "pending";
+        at: string;
+    };
+}
+/**
+ * The value a choice list stores for one choice: ra's `choices` carry an `id`
+ * and the form holds that id, while a plain list of scalars holds the scalar.
+ */
+export type ChoiceValueOf<TChoice> = TChoice extends {
+    id: infer TId;
+} ? TId : TChoice;
+/**
+ * The value a choice list stores for one choice: its `id` when it has one (ra's
+ * `choices` carry `{id, name}` pairs), the choice itself otherwise.
+ */
+export declare function choiceIdOf<TChoice>(choice: TChoice): ChoiceValueOf<TChoice>;
+/**
+ * The value a single-choice input holds, which is the value of one of its
+ * choices. An empty field is the empty value the input was given, which no
+ * choice equals, so it is only ever compared.
+ */
+export declare function toChoiceValue<TChoice>(value: FormValue): ChoiceValueOf<TChoice>;
+/**
+ * The value a choice stores: what was read at its `optionValue` path, else its
+ * {@link choiceIdOf id}.
+ */
+export declare function resolveChoiceValue<TChoice>(choice: TChoice, atOptionValue: FormValue): ChoiceValueOf<TChoice>;
+/**
+ * The values a multi-choice input holds: the stored array, one value for a
+ * stored scalar, and a shared empty list for a missing one (so a render that
+ * finds nothing keeps the same reference). `''` is missing too: it is what the
+ * default format makes of a nullish value.
+ */
+export declare function toChoiceValues<TChoice>(value: FormValue): readonly ChoiceValueOf<TChoice>[];
+/** The text a text input edits: `''` for a nullish value so the input stays controlled. */
+export declare function toTextValue(value: FormValue): string;
+/** The rows of a text-array input: every entry as text, `[]` for a non-array. */
+export declare function toTextList(value: FormValue): string[];
+/** A number input's value: `null` for a cleared or non-numeric one (`''` is cleared, `0` is not). */
+export declare function toNumberValue(value: FormValue): number | null;
+/** A boolean input's value: only `false`, `0`, `''`, `"false"`, `"0"` and a nullish value read as false. */
+export declare function toBooleanValue(value: FormValue): boolean;
+/** A tri-state boolean input's value: `true` or `false` as stored, `null` for every other value (unset is not false). */
+export declare function toNullableBooleanValue(value: FormValue): boolean | null;
+/**
+ * A date input's value, unconverted: the string/number/`Date` it can edit,
+ * `null` for a cleared one. Formatting to the input's own shape stays with the
+ * input (it is the family that knows whether it wants `YYYY-MM-DD` or a time).
+ */
+export declare function toDateInputValue(value: FormValue): DateInputValue;
+/**
+ * A file input's value: a live `File`, the stored reference (a URL string) of
+ * the file already on the record, `null` for a cleared one. `File` is checked
+ * through the global so the guard also runs where there is none (Node).
+ */
+export declare function toFileInputValue(value: FormValue): FileInputValue;
+/** A picked `File`, which may carry the object URL its preview holds. */
+export type FileWithPreview = File & {
+    preview?: string;
+};
+/** What `<FileInput>` stores for a dropped file: the file with the preview URL and title a preview child reads. */
+export type TransformedFile = {
+    rawFile: FileWithPreview;
+    src: string;
+    title: string;
+};
+/** A file already on the record: the `{ src, title }` object a data provider stores. Other keys ride along. */
+export type StoredFile = {
+    src?: string;
+    title?: string;
+};
+/** One file a `<FileInput>` holds: a stored file may also be just its URL. */
+export type FileEntry = FileWithPreview | TransformedFile | StoredFile | string;
+/** What a `<FileInput>` holds: one entry, a list of them with `multiple`, or nothing. */
+export type FileSelection = FileEntry | FileEntry[] | null;
+/** The preview record `<FileInput>` makes of a dropped file. */
+export declare function isTransformedFile(value: FormValue): value is TransformedFile;
+/**
+ * A file input's selection: the entry, the entries of a list (anything that is
+ * not a file, a record or a URL string dropped), `null` for a cleared one.
+ */
+export declare function toFileSelection(value: FormValue): FileSelection;
+/** The entries of a file input's value, in order. */
+export declare function toFileEntries(value: FormValue): FileEntry[];
+/** A stable list key for a file entry: the dropped file's name, else the stored `src` or URL, else its place. */
+export declare function fileEntryKey(entry: FileEntry, index: number): string | number;
+/** The object URL a file entry's preview holds, to revoke when it goes. */
+export declare function fileEntryPreview(entry: FileEntry): string | undefined;
+/** A currency input's value: the amount, `null` when cleared (minor-vs-major units stay with the input). */
+export declare function toCurrencyValue(value: FormValue): number | null;
+/** What a multi-currency `<CurrencyInput>` stores: the amount and its currency code, when it has one. */
+export interface CurrencyComposite {
+    amount: number;
+    currency: string | undefined;
+}
+/**
+ * A multi-currency input's value: the amount with its currency, `null` for
+ * anything without a numeric amount (an absent value, or a bare number from
+ * single-currency mode). A currency that is missing or not text reads as
+ * `undefined`, so the saved amount survives it.
+ */
+export declare function toCurrencyComposite(value: FormValue): CurrencyComposite | null;
+/**
+ * A webhook input's value: the endpoint object, filled in from whatever the
+ * record holds so every member the input edits is present.
+ */
+export declare function toWebhookValue(value: FormValue): WebhookValue;

package/dist/form/input-values.js

@@ -0,0 +1,177 @@
+// src/form/input-values.ts
+/**
+* The value a choice list stores for one choice: its `id` when it has one (ra's
+* `choices` carry `{id, name}` pairs), the choice itself otherwise.
+*/
+function choiceIdOf(choice) {
+	if (typeof choice === "object" && choice !== null && "id" in choice) return choice.id;
+	return choice;
+}
+/**
+* The value a single-choice input holds, which is the value of one of its
+* choices. An empty field is the empty value the input was given, which no
+* choice equals, so it is only ever compared.
+*/
+function toChoiceValue(value) {
+	return value;
+}
+/**
+* The value a choice stores: what was read at its `optionValue` path, else its
+* {@link choiceIdOf id}.
+*/
+function resolveChoiceValue(choice, atOptionValue) {
+	return atOptionValue !== void 0 ? toChoiceValue(atOptionValue) : choiceIdOf(choice);
+}
+var NO_CHOICE_VALUES = Object.freeze([]);
+/**
+* The values a multi-choice input holds: the stored array, one value for a
+* stored scalar, and a shared empty list for a missing one (so a render that
+* finds nothing keeps the same reference). `''` is missing too: it is what the
+* default format makes of a nullish value.
+*/
+function toChoiceValues(value) {
+	if (value == null || value === "") return NO_CHOICE_VALUES;
+	if (Array.isArray(value)) return value;
+	return [toChoiceValue(value)];
+}
+/** The text a text input edits: `''` for a nullish value so the input stays controlled. */
+function toTextValue(value) {
+	if (value == null) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return "";
+}
+/** The rows of a text-array input: every entry as text, `[]` for a non-array. */
+function toTextList(value) {
+	return Array.isArray(value) ? value.map(toTextValue) : [];
+}
+/** A number input's value: `null` for a cleared or non-numeric one (`''` is cleared, `0` is not). */
+function toNumberValue(value) {
+	if (value == null || value === "") return null;
+	if (typeof value === "number") return Number.isNaN(value) ? null : value;
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (typeof value !== "string") return null;
+	const parsed = Number(value);
+	return Number.isNaN(parsed) ? null : parsed;
+}
+/** A boolean input's value: only `false`, `0`, `''`, `"false"`, `"0"` and a nullish value read as false. */
+function toBooleanValue(value) {
+	if (typeof value === "boolean") return value;
+	if (value == null) return false;
+	if (typeof value === "number") return value !== 0;
+	if (typeof value === "string") return value !== "" && value !== "false" && value !== "0";
+	return Boolean(value);
+}
+/** A tri-state boolean input's value: `true` or `false` as stored, `null` for every other value (unset is not false). */
+function toNullableBooleanValue(value) {
+	return typeof value === "boolean" ? value : null;
+}
+/**
+* A date input's value, unconverted: the string/number/`Date` it can edit,
+* `null` for a cleared one. Formatting to the input's own shape stays with the
+* input (it is the family that knows whether it wants `YYYY-MM-DD` or a time).
+*/
+function toDateInputValue(value) {
+	if (value == null || value === "") return null;
+	if (typeof value === "string" || typeof value === "number" || value instanceof Date) return value;
+	return null;
+}
+/**
+* A file input's value: a live `File`, the stored reference (a URL string) of
+* the file already on the record, `null` for a cleared one. `File` is checked
+* through the global so the guard also runs where there is none (Node).
+*/
+function toFileInputValue(value) {
+	if (value == null) return null;
+	if (typeof value === "string") return value;
+	if (typeof File !== "undefined" && value instanceof File) return value;
+	return null;
+}
+/** `File` is read through the global so the guards also run where there is none (Node). */
+function isFile(value) {
+	return typeof File !== "undefined" && value instanceof File;
+}
+function isFileEntry(value) {
+	return isFile(value) || typeof value === "string" && value !== "" || typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The preview record `<FileInput>` makes of a dropped file. */
+function isTransformedFile(value) {
+	return typeof value === "object" && value !== null && "rawFile" in value && isFile(value.rawFile) && "src" in value && typeof value.src === "string" && "title" in value && typeof value.title === "string";
+}
+/**
+* A file input's selection: the entry, the entries of a list (anything that is
+* not a file, a record or a URL string dropped), `null` for a cleared one.
+*/
+function toFileSelection(value) {
+	if (Array.isArray(value)) return value.filter(isFileEntry);
+	return isFileEntry(value) ? value : null;
+}
+/** The entries of a file input's value, in order. */
+function toFileEntries(value) {
+	const selection = toFileSelection(value);
+	if (selection === null) return [];
+	return Array.isArray(selection) ? selection : [selection];
+}
+/** A stable list key for a file entry: the dropped file's name, else the stored `src` or URL, else its place. */
+function fileEntryKey(entry, index) {
+	if (typeof entry === "string") return entry;
+	if (isTransformedFile(entry)) return entry.rawFile.name;
+	if (isFile(entry)) return index;
+	return entry.src ?? index;
+}
+/** The object URL a file entry's preview holds, to revoke when it goes. */
+function fileEntryPreview(entry) {
+	if (typeof entry === "string") return void 0;
+	if (isTransformedFile(entry)) return entry.rawFile.preview;
+	return isFile(entry) ? entry.preview : void 0;
+}
+/** A currency input's value: the amount, `null` when cleared (minor-vs-major units stay with the input). */
+function toCurrencyValue(value) {
+	return toNumberValue(value);
+}
+/**
+* A multi-currency input's value: the amount with its currency, `null` for
+* anything without a numeric amount (an absent value, or a bare number from
+* single-currency mode). A currency that is missing or not text reads as
+* `undefined`, so the saved amount survives it.
+*/
+function toCurrencyComposite(value) {
+	if (typeof value !== "object" || value === null) return null;
+	if (!("amount" in value)) return null;
+	const amount = toNumberValue(value.amount);
+	if (amount === null) return null;
+	return {
+		amount,
+		currency: "currency" in value && typeof value.currency === "string" ? value.currency : void 0
+	};
+}
+/** The empty endpoint a webhook input starts from. */
+var EMPTY_WEBHOOK_VALUE = {
+	url: "",
+	secret: "",
+	eventTypes: []
+};
+/** The last-delivery line, read out of a record that may hold anything under it. */
+function toWebhookDelivery(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	if (!("at" in value) || typeof value.at !== "string") return void 0;
+	return {
+		status: "status" in value && (value.status === "ok" || value.status === "failed" || value.status === "pending") ? value.status : "pending",
+		at: value.at
+	};
+}
+/**
+* A webhook input's value: the endpoint object, filled in from whatever the
+* record holds so every member the input edits is present.
+*/
+function toWebhookValue(value) {
+	if (typeof value !== "object" || value === null) return { ...EMPTY_WEBHOOK_VALUE };
+	const lastDelivery = "lastDelivery" in value ? toWebhookDelivery(value.lastDelivery) : void 0;
+	return {
+		url: "url" in value ? toTextValue(value.url) : "",
+		secret: "secret" in value ? toTextValue(value.secret) : "",
+		eventTypes: "eventTypes" in value ? toTextList(value.eventTypes) : [],
+		...lastDelivery === void 0 ? {} : { lastDelivery }
+	};
+}
+export { choiceIdOf, fileEntryKey, fileEntryPreview, isTransformedFile, resolveChoiceValue, toBooleanValue, toChoiceValue, toChoiceValues, toCurrencyComposite, toCurrencyValue, toDateInputValue, toFileEntries, toFileInputValue, toFileSelection, toNullableBooleanValue, toNumberValue, toTextList, toTextValue, toWebhookValue };