@chelone/core 0.6.0 → 0.7.0

package/dist/form/validators.d.ts

@@ -1,4 +1,7 @@
+import type { StandardSchemaV1, StandardSchemaV1Issue } from "@tanstack/form-core";
+import type { TranslateParamValues } from "../i18n/messages.js";
 import type { TranslatableMessage } from "./form-controller.js";
+import { type ChoiceValueOf } from "./input-values.js";
 /**
  * What a validator may return on failure: a plain string (an i18n key or
  * pre-translated text) or a translatable payload with interpolation args.
@@ -8,35 +11,62 @@ import type { TranslatableMessage } from "./form-controller.js";
 export type ValidationErrorMessage = string | TranslatableMessage;
 /** A validator's verdict: nullish means the value passes. */
 export type ValidatorResult = ValidationErrorMessage | null | undefined;
+/**
+ * The values ra's skip-empty gate lets into a validator's value slot next to
+ * the field's own type: the holes, and an unset multi-input's `[]`. Every
+ * built-in except `required` stands down on them, so a validator written for a
+ * `string` field is still legal on a field whose value is momentarily empty.
+ */
+export type EmptyValue = null | undefined | readonly unknown[];
+/**
+ * The third validator argument (ra's `props` slot): a field binding always
+ * fills `source` with the final source path and merges its `validatorMeta`
+ * (input props in the React layer) in. `source` is optional because a validator
+ * is also a plain function an app can call with no field behind it. The open
+ * bag is the boundary — Chelone cannot know what an input passes there.
+ */
+export interface FieldValidatorMeta {
+    /** The FINAL field path the value came from, when a binding ran the stack. */
+    source?: string;
+    [key: string]: unknown;
+}
 /**
  * The ra validator contract: `(value, allValues, meta)`. `meta` carries the
- * final source path plus whatever the binding merged in (`validatorMeta` —
- * the React layer passes input props there). Sync or async.
+ * final source path plus whatever the binding merged in (`validatorMeta` — the
+ * React layer passes input props there); it is optional so a validator that
+ * reads only the value can say only the value. Sync or async.
+ *
+ * Generic in the value and the values it is handed: `Validator<string, Post>`
+ * is a validator for a `Post`'s `string` field (its value slot also holds
+ * {@link EmptyValue}), and one written for the widest pair (`Validator`, the
+ * default) fits any field.
  */
-export type Validator = (value: unknown, values: unknown, meta: unknown) => ValidatorResult | Promise<ValidatorResult>;
+export type Validator<TValue = unknown, TValues = unknown> = (value: TValue | EmptyValue, values: TValues, meta?: FieldValidatorMeta) => ValidatorResult | Promise<ValidatorResult>;
 /** `required()`'s return: a validator tagged for {@link isRequired} detection. */
-export interface RequiredValidator {
-    (value: unknown, values: unknown, meta: unknown): ValidatorResult | Promise<ValidatorResult>;
+export interface RequiredValidator<TValue = unknown, TValues = unknown> {
+    (value: TValue | EmptyValue, values: TValues, meta?: FieldValidatorMeta): ValidatorResult | Promise<ValidatorResult>;
     readonly isRequired: true;
 }
+/** A validator, or the `false`/nullish ra passes when a rule is switched off. */
+export type ValidatorInput<TValue = unknown, TValues = unknown> = Validator<TValue, TValues> | false | null | undefined;
+/** One `validate` slot: a single validator or a list of them (ra call style). */
+export type ValidatorSlot<TValue = unknown, TValues = unknown> = ValidatorInput<TValue, TValues> | ReadonlyArray<ValidatorInput<TValue, TValues>>;
 /** Params handed to a message factory when the error message is a function. */
-export interface ValidationMessageParams {
-    args: Record<string, unknown> | undefined;
-    value: unknown;
-    values: unknown;
+export interface ValidationMessageParams<TValue = unknown, TValues = unknown> {
+    args: TranslateParamValues | undefined;
+    value: TValue | EmptyValue;
+    values: TValues;
 }
 /** Builds an error message dynamically from the failing value/args. */
-export type MessageFactory = (params: ValidationMessageParams) => ValidationErrorMessage;
+export type MessageFactory<TValue = unknown, TValues = unknown> = (params: ValidationMessageParams<TValue, TValues>) => ValidationErrorMessage;
 /** A built-in's `message` option: an i18n key/string or a factory. */
-export type ValidationMessage = string | MessageFactory;
+export type ValidationMessage<TValue = unknown, TValues = unknown> = string | MessageFactory<TValue, TValues>;
 /**
  * ra's emptiness notion — the skip-empty gate every built-in except
  * `required` applies: `undefined`, `null`, `''` and `[]` are empty; `0`,
  * `false` and whitespace are values.
  */
 export declare function isEmpty(value: unknown): boolean;
-/** Loose input accepted by {@link composeValidators} and {@link isRequired}. */
-type ValidatorInput = Validator | false | null | undefined;
 /**
  * Composes validators into one (ra contract): runs them SEQUENTIALLY,
  * short-circuits on the first error, and stays synchronous while every
@@ -48,13 +78,13 @@ type ValidatorInput = Validator | false | null | undefined;
  * options rather than react-hook-form rules, so fresh identities per render
  * cannot re-trigger anything.
  */
-export declare function composeValidators(...validators: ReadonlyArray<ValidatorInput | ReadonlyArray<ValidatorInput>>): Validator;
+export declare function composeValidators<TValue = unknown, TValues = unknown>(...validators: ReadonlyArray<ValidatorSlot<TValue, TValues>>): Validator<TValue, TValues>;
 /**
  * Errors when the value is empty. The ONLY built-in that fails on emptiness —
  * every other one skips empty values so optional fields stay optional.
  * The returned validator is tagged `.isRequired` for {@link isRequired}.
  */
-export declare function required(message?: ValidationMessage): RequiredValidator;
+export declare function required<TValue = unknown, TValues = unknown>(message?: ValidationMessage<TValue, TValues>): RequiredValidator<TValue, TValues>;
 /** Errors when a string/array value is shorter than `min`. Skips empty values. */
 export declare function minLength(min: number, message?: ValidationMessage): Validator;
 /** Errors when a string/array value is longer than `max`. Skips empty values. */
@@ -72,12 +102,21 @@ export declare function number(message?: ValidationMessage): Validator;
 export declare function regex(pattern: RegExp, message?: ValidationMessage): Validator;
 /** Errors when the value is not a valid email address. Skips empty values. */
 export declare function email(message?: ValidationMessage): Validator;
-/** Errors when the value is not one of `list`. Skips empty values. */
-export declare function choices(list: readonly unknown[], message?: ValidationMessage): Validator;
+/**
+ * Errors when the value is not one of `list`. Skips empty values.
+ *
+ * Generic in the choices: {@link ChoiceValueOf} maps the list to the value the
+ * field holds for one (a `{id, name}` pair stores its `id`), so
+ * `choices([{ id: 1, name: 'm' }])` is a validator for a number field.
+ */
+export declare function choices<TChoice>(list: readonly TChoice[], message?: ValidationMessage<ChoiceValueOf<TChoice>>): Validator<ChoiceValueOf<TChoice>>;
 /**
  * Detects requiredness from the RAW `validate` prop — a single validator or
  * any array member tagged `.isRequired === true` (the `required()` tag).
  * Inputs use this to render the required marker without running validation.
  */
-export declare function isRequired(validate: ValidatorInput | ReadonlyArray<ValidatorInput>): boolean;
-export {};
+export declare function isRequired<TValue = unknown, TValues = unknown>(validate: ValidatorSlot<TValue, TValues>): boolean;
+/** The validator stack a field binding runs: schema issues or a validator error. */
+export type FieldValidatorStackResult = ValidatorResult | readonly StandardSchemaV1Issue[];
+/** A field schema outcome: issues, or a thenable of them (an async schema). */
+export type SchemaOutcome = ReturnType<StandardSchemaV1["~standard"]["validate"]>;

package/dist/form/validators.js

@@ -1,99 +1,125 @@
-import { isThenable } from "./save-pipeline.js";
-const EMAIL_REGEX = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+import { isThenable } from "../guards.js";
+import { choiceIdOf } from "./input-values.js";
+// src/form/validators.ts
+var EMAIL_REGEX = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
+/**
+* ra's emptiness notion — the skip-empty gate every built-in except
+* `required` applies: `undefined`, `null`, `''` and `[]` are empty; `0`,
+* `false` and whitespace are values.
+*/
 function isEmpty(value) {
-  return value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0;
+	return value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0;
 }
+/** Resolves a {@link ValidationMessage} into the error payload (ra's getMessage). */
 function getMessage(message, args, value, values) {
-  if (typeof message === "function") return message({ args, value, values });
-  return args ? { message, args } : message;
+	if (typeof message === "function") return message({
+		args,
+		value,
+		values
+	});
+	return args ? {
+		message,
+		args
+	} : message;
 }
+/**
+* Composes validators into one (ra contract): runs them SEQUENTIALLY,
+* short-circuits on the first error, and stays synchronous while every
+* consulted validator is synchronous — an async member switches the tail of
+* the run (and only that run) to promise chaining. Accepts a rest list or a
+* single array (ra call style); non-function members are filtered out.
+*
+* Unlike ra there is no memoization: bindings hold validators in mutable
+* options rather than react-hook-form rules, so fresh identities per render
+* cannot re-trigger anything.
+*/
 function composeValidators(...validators) {
-  const head = validators[0];
-  const list = (Array.isArray(head) ? head : validators).filter(
-    (candidate) => typeof candidate === "function"
-  );
-  const runFrom = (start, value, values, meta) => {
-    for (let index = start; index < list.length; index++) {
-      const validator = list[index];
-      const result = validator(value, values, meta);
-      if (isThenable(result)) {
-        return Promise.resolve(result).then(
-          (resolved) => resolved ? resolved : runFrom(index + 1, value, values, meta)
-        );
-      }
-      if (result) return result;
-    }
-    return void 0;
-  };
-  return (value, values, meta) => runFrom(0, value, values, meta);
+	const head = validators[0];
+	const list = (Array.isArray(head) ? head : validators).filter((candidate) => typeof candidate === "function");
+	const runFrom = (start, value, values, meta) => {
+		for (let index = start; index < list.length; index++) {
+			const validator = list[index];
+			if (validator === void 0) continue;
+			const result = validator(value, values, meta);
+			if (isThenable(result)) return Promise.resolve(result).then((resolved) => resolved ? resolved : runFrom(index + 1, value, values, meta));
+			if (result) return result;
+		}
+	};
+	return (value, values, meta) => runFrom(0, value, values, meta);
 }
+/**
+* Errors when the value is empty. The ONLY built-in that fails on emptiness —
+* every other one skips empty values so optional fields stay optional.
+* The returned validator is tagged `.isRequired` for {@link isRequired}.
+*/
 function required(message = "chelone.validation.required") {
-  return Object.assign(
-    (value, values, _meta) => isEmpty(value) ? getMessage(message, void 0, value, values) : void 0,
-    { isRequired: true }
-  );
+	return Object.assign((value, values) => isEmpty(value) ? getMessage(message, void 0, value, values) : void 0, { isRequired: true });
 }
+/** The length of a string/array value; `undefined` for anything else (skip). */
 function lengthOf(value) {
-  if (typeof value === "string" || Array.isArray(value)) return value.length;
-  return void 0;
+	if (typeof value === "string" || Array.isArray(value)) return value.length;
 }
+/** Errors when a string/array value is shorter than `min`. Skips empty values. */
 function minLength(min, message = "chelone.validation.minLength") {
-  return (value, values) => {
-    if (isEmpty(value)) return void 0;
-    const length = lengthOf(value);
-    return length !== void 0 && length < min ? getMessage(message, { min }, value, values) : void 0;
-  };
+	return (value, values) => {
+		if (isEmpty(value)) return void 0;
+		const length = lengthOf(value);
+		return length !== void 0 && length < min ? getMessage(message, { min }, value, values) : void 0;
+	};
 }
+/** Errors when a string/array value is longer than `max`. Skips empty values. */
 function maxLength(max, message = "chelone.validation.maxLength") {
-  return (value, values) => {
-    if (isEmpty(value)) return void 0;
-    const length = lengthOf(value);
-    return length !== void 0 && length > max ? getMessage(message, { max }, value, values) : void 0;
-  };
+	return (value, values) => {
+		if (isEmpty(value)) return void 0;
+		const length = lengthOf(value);
+		return length !== void 0 && length > max ? getMessage(message, { max }, value, values) : void 0;
+	};
 }
+/** Errors when the value is below `min` (`0` IS validated). Skips empty values. */
 function minValue(min, message = "chelone.validation.minValue") {
-  return (value, values) => !isEmpty(value) && value < min ? getMessage(message, { min }, value, values) : void 0;
+	return (value, values) => !isEmpty(value) && Number(value) < min ? getMessage(message, { min }, value, values) : void 0;
 }
+/** Errors when the value is above `max`. Skips empty values. */
 function maxValue(max, message = "chelone.validation.maxValue") {
-  return (value, values) => !isEmpty(value) && value > max ? getMessage(message, { max }, value, values) : void 0;
+	return (value, values) => !isEmpty(value) && Number(value) > max ? getMessage(message, { max }, value, values) : void 0;
 }
+/** Errors when the value is not coercible to a number. Skips empty values. */
 function number(message = "chelone.validation.number") {
-  return (value, values) => !isEmpty(value) && Number.isNaN(Number(value)) ? getMessage(message, void 0, value, values) : void 0;
+	return (value, values) => !isEmpty(value) && Number.isNaN(Number(value)) ? getMessage(message, void 0, value, values) : void 0;
 }
+/**
+* Errors when a STRING value does not match `pattern` (non-strings skip, ra
+* parity). The pattern rides the error args stringified for interpolation.
+*/
 function regex(pattern, message = "chelone.validation.regex") {
-  return (value, values) => !isEmpty(value) && typeof value === "string" && !pattern.test(value) ? getMessage(message, { pattern: String(pattern) }, value, values) : void 0;
+	return (value, values) => !isEmpty(value) && typeof value === "string" && !pattern.test(value) ? getMessage(message, { pattern: String(pattern) }, value, values) : void 0;
 }
+/** Errors when the value is not a valid email address. Skips empty values. */
 function email(message = "chelone.validation.email") {
-  return regex(EMAIL_REGEX, message);
+	return regex(EMAIL_REGEX, message);
 }
+/**
+* Errors when the value is not one of `list`. Skips empty values.
+*
+* Generic in the choices: {@link ChoiceValueOf} maps the list to the value the
+* field holds for one (a `{id, name}` pair stores its `id`), so
+* `choices([{ id: 1, name: 'm' }])` is a validator for a number field.
+*/
 function choices(list, message = "chelone.validation.oneOf") {
-  return (value, values) => !isEmpty(value) && !list.includes(value) ? getMessage(
-    message,
-    { options: list.map(String).join(", ") },
-    value,
-    values
-  ) : void 0;
+	const options = list.map(choiceIdOf);
+	return (value, values) => !isEmpty(value) && !options.includes(value) ? getMessage(message, { options: options.map(String).join(", ") }, value, values) : void 0;
 }
+/**
+* Detects requiredness from the RAW `validate` prop — a single validator or
+* any array member tagged `.isRequired === true` (the `required()` tag).
+* Inputs use this to render the required marker without running validation.
+*/
 function isRequired(validate) {
-  if (!validate) return false;
-  if (Array.isArray(validate)) {
-    return validate.some(
-      (candidate) => typeof candidate === "function" && candidate.isRequired === true
-    );
-  }
-  return validate.isRequired === true;
+	if (Array.isArray(validate)) return validate.some((candidate) => typeof candidate === "function" && hasRequiredTag(candidate));
+	return typeof validate === "function" && hasRequiredTag(validate);
 }
-export {
-  choices,
-  composeValidators,
-  email,
-  isEmpty,
-  isRequired,
-  maxLength,
-  maxValue,
-  minLength,
-  minValue,
-  number,
-  regex,
-  required
-};
+/** The `required()` tag, read through an `in` check rather than a cast. */
+function hasRequiredTag(validator) {
+	return "isRequired" in validator && validator.isRequired === true;
+}
+export { choices, composeValidators, email, isEmpty, isRequired, maxLength, maxValue, minLength, minValue, number, regex, required };

package/dist/geo/bbox.d.ts

@@ -1,15 +1,16 @@
-import type { GeoBBox, GeoGeometry, GeoPolygon } from "./geojson.js";
+import type { Geometry, Polygon } from "geojson";
+import type { LngLatBox } from "./bounds.js";
 /**
  * The closed rectangle ring of a bbox; `null` unless it is four finite numbers.
  * A box with west greater than east crosses 180: its ring runs east of 180.
  */
-export declare function bboxToPolygon(bbox: unknown): GeoPolygon | null;
+export declare function bboxToPolygon(bbox: unknown): Polygon | null;
 /** The box around a Polygon, west greater than east across 180; `null` for any other geometry. */
-export declare function polygonToBBox(geometry: GeoGeometry): GeoBBox | null;
+export declare function polygonToBBox(geometry: Geometry): LngLatBox | null;
 /**
  * Builds a polygon-to-bbox function whose box has width over height equal to
  * `ratio`. The box grows around the old centre, never shrinks. A zero width,
  * a zero height or a `ratio` that is not a positive finite number yields the
  * plain bbox.
  */
-export declare function aspectLockedBBox(ratio: number): (geometry: GeoGeometry) => GeoBBox | null;
+export declare function aspectLockedBBox(ratio: number): (geometry: Geometry) => LngLatBox | null;

package/dist/geo/bbox.js

@@ -1,56 +1,77 @@
 import { geoBounds } from "./bounds.js";
 import { isGeoBBox } from "./geojson.js";
+// src/geo/bbox.ts
+/**
+* The closed rectangle ring of a bbox; `null` unless it is four finite numbers.
+* A box with west greater than east crosses 180: its ring runs east of 180.
+*/
 function bboxToPolygon(bbox) {
-  if (!isGeoBBox(bbox)) return null;
-  const [west, south, rawEast, north] = bbox;
-  const east = west > rawEast ? rawEast + 360 : rawEast;
-  return {
-    type: "Polygon",
-    coordinates: [
-      [
-        [west, south],
-        [east, south],
-        [east, north],
-        [west, north],
-        [west, south]
-      ]
-    ]
-  };
+	if (!isGeoBBox(bbox)) return null;
+	const [west, south, rawEast, north] = bbox;
+	const east = west > rawEast ? rawEast + 360 : rawEast;
+	return {
+		type: "Polygon",
+		coordinates: [[
+			[west, south],
+			[east, south],
+			[east, north],
+			[west, north],
+			[west, south]
+		]]
+	};
 }
+/** The box around a Polygon, west greater than east across 180; `null` for any other geometry. */
 function polygonToBBox(geometry) {
-  return geometry.type === "Polygon" ? geoBounds(geometry, "explicit") : null;
+	return geometry.type === "Polygon" ? geoBounds(geometry, "explicit") : null;
 }
-const RATIO_TOLERANCE = 1e-9;
-const wrapLongitude = (longitude) => longitude > 180 ? longitude - 360 : longitude < -180 ? longitude + 360 : longitude;
+var RATIO_TOLERANCE = 1e-9;
+var wrapLongitude = (longitude) => longitude > 180 ? longitude - 360 : longitude < -180 ? longitude + 360 : longitude;
+/**
+* Builds a polygon-to-bbox function whose box has width over height equal to
+* `ratio`. The box grows around the old centre, never shrinks. A zero width,
+* a zero height or a `ratio` that is not a positive finite number yields the
+* plain bbox.
+*/
 function aspectLockedBBox(ratio) {
-  return (geometry) => {
-    const bbox = polygonToBBox(geometry);
-    if (!bbox || !Number.isFinite(ratio) || ratio <= 0) return bbox;
-    const [west, south, east, north] = bbox;
-    const crossing = west > east;
-    const unwrappedEast = crossing ? east + 360 : east;
-    const width = unwrappedEast - west;
-    const height = north - south;
-    if (width <= 0 || height <= 0) return bbox;
-    const current = width / height;
-    if (Math.abs(current - ratio) <= RATIO_TOLERANCE * ratio) return bbox;
-    if (current < ratio) {
-      const grow2 = (height * ratio - width) / 2;
-      if (!crossing) return [west - grow2, south, east + grow2, north];
-      if (width + 2 * grow2 >= 360) return [-180, south, 180, north];
-      return [
-        wrapLongitude(west - grow2),
-        south,
-        wrapLongitude(unwrappedEast + grow2),
-        north
-      ];
-    }
-    const grow = (width / ratio - height) / 2;
-    return [west, south - grow, east, north + grow];
-  };
+	return (geometry) => {
+		const bbox = polygonToBBox(geometry);
+		if (!bbox || !Number.isFinite(ratio) || ratio <= 0) return bbox;
+		const [west, south, east, north] = bbox;
+		const crossing = west > east;
+		const unwrappedEast = crossing ? east + 360 : east;
+		const width = unwrappedEast - west;
+		const height = north - south;
+		if (width <= 0 || height <= 0) return bbox;
+		const current = width / height;
+		if (Math.abs(current - ratio) <= RATIO_TOLERANCE * ratio) return bbox;
+		if (current < ratio) {
+			const grow = (height * ratio - width) / 2;
+			if (!crossing) return [
+				west - grow,
+				south,
+				east + grow,
+				north
+			];
+			if (width + 2 * grow >= 360) return [
+				-180,
+				south,
+				180,
+				north
+			];
+			return [
+				wrapLongitude(west - grow),
+				south,
+				wrapLongitude(unwrappedEast + grow),
+				north
+			];
+		}
+		const grow = (width / ratio - height) / 2;
+		return [
+			west,
+			south - grow,
+			east,
+			north + grow
+		];
+	};
 }
-export {
-  aspectLockedBBox,
-  bboxToPolygon,
-  polygonToBBox
-};
+export { aspectLockedBBox, bboxToPolygon, polygonToBBox };

package/dist/geo/bounds.d.ts

@@ -1,4 +1,15 @@
-import type { GeoBBox, GeoJsonValue } from "./geojson.js";
+import type { Feature, FeatureCollection, Geometry } from "geojson";
+import type { JsonObject } from "../guards.js";
+/**
+ * `[west, south, east, north]`. Not geojson's `BBox`, which also allows six
+ * numbers.
+ */
+export type LngLatBox = [
+    west: number,
+    south: number,
+    east: number,
+    north: number
+];
 /**
  * How `geoBounds` picks west and east. `narrowest` takes whichever arc is
  * narrower, as for framing features. `explicit` goes across 180 only when a
@@ -12,9 +23,9 @@ export type CrossingMode = "narrowest" | "explicit";
  * longitudes are narrower going round the antimeridian, west is greater than
  * east.
  */
-export declare function geoBounds(value: GeoJsonValue, mode?: CrossingMode): GeoBBox | null;
+export declare function geoBounds(value: Geometry | Feature<Geometry | null, JsonObject | null> | FeatureCollection<Geometry | null, JsonObject | null>, mode?: CrossingMode): LngLatBox | null;
 /**
  * Whether every corner is a valid longitude and latitude. MapLibre throws on a
  * latitude outside ±90, so a box failing this is never fitted.
  */
-export declare function isLngLatBox(box: readonly number[] | null): box is [number, number, number, number];
+export declare function isLngLatBox(box: readonly number[] | null): box is LngLatBox;