@orkestrel/form 0.0.11 → 0.0.13

package/dist/src/core/index.d.cts

@@ -12,7 +12,7 @@ export declare const ALPHANUMERIC_PATTERN: Readonly<RegExp>;
  *
  * @remarks
  * The runtime control-membership check keeps this boundary total for JavaScript callers that
- * bypass the declared {@link FieldControl} contract.
+ * pass values outside the declared {@link FieldControl} contract.
  *
  * @param control - The field control to inspect.
  * @param rule - The named rule to inspect.
@@ -354,7 +354,7 @@ export declare interface FieldChoice {
  * const control: FieldControl = 'select'
  * ```
  */
-export declare type FieldControl = 'text' | 'editor' | 'password' | 'number' | 'date' | 'time' | 'datetime' | 'color' | 'confirm' | 'select' | 'checkbox' | 'file';
+export declare type FieldControl = 'text' | 'editor' | 'password' | 'number' | 'date' | 'time' | 'datetime' | 'color' | 'confirm' | 'select' | 'checkbox' | 'list' | 'file';
 
 /**
  * Represents one failed check against one field.
@@ -377,11 +377,12 @@ export declare interface FieldError {
  * `minimum` and `maximum` measure whatever the control makes countable: characters for
  * `text`, `editor`, and `password`; magnitude for `number`; chronology for `date`, `time`,
  * and `datetime`, whose operand is a string written in that control's own format; and the
- * number of selections for `checkbox` and `file`.
+ * number of entries for `checkbox`, `list`, and `file`.
  *
  * `step` is the interval a numeric value must land on. `pattern` is regular-expression
  * source. `email`, `url`, `integer`, and `alphanumeric` each assert one shape over the whole
- * value. `custom` runs last and is the only rule that sees the rest of the form.
+ * value, or each entry of a `list`. `required` requires an entry for `list` and presence
+ * for other controls. `custom` runs last and is the only rule that sees the rest of the form.
  *
  * @example
  * ```ts
@@ -415,7 +416,7 @@ export declare type FieldRuleName = Exclude<keyof FieldRule, 'custom'>;
  *
  * @remarks
  * It runs after every named rule, and it runs on an absent value as well as a present one. That
- * is what makes a rule such as "required once the sibling says yes" expressible, and it means an
+ * is what makes a rule such as "required after the sibling says yes" expressible, and it means an
  * unanswered field can carry both a `required` message and this validator's own.
  *
  * @param value - The value the field holds, or `undefined` when nobody has answered it.
@@ -440,7 +441,7 @@ export declare type FieldValidator = (value: FieldValue | undefined, values: For
  *
  * @remarks
  * The variant follows the control: text-like controls hold a `string`, `number` holds a
- * `number`, `confirm` holds a `boolean`, and `checkbox` holds its checked values as a
+ * `number`, `confirm` holds a `boolean`, and `checkbox`, `list`, and `file` hold a
  * `readonly string[]`.
  */
 export declare type FieldValue = string | number | boolean | readonly string[];
@@ -753,7 +754,7 @@ export declare type FormEventMap = {
  * }
  * ```
  */
-export declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | FileField;
+export declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | ListField | FileField;
 
 /**
  * Represents a named section of a form.
@@ -772,7 +773,7 @@ export declare interface FormGroup {
  * Declares the contract a form exposes: the state it holds and the calls that move it.
  *
  * @remarks
- * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
+ * `valid` is true when the last completed evaluation found no error, and `dirty` is true when
  * an answer differs from its acknowledged baseline. Both are derived, never stored.
  *
  * `touched` holds the fields somebody has visited, which is what lets a renderer withhold an
@@ -1202,6 +1203,26 @@ export declare function isFormValues(input: unknown): input is FormValues;
 /** Caps the number of entries one list-valued answer may hold, at 1024. */
 export declare const LIST_LIMIT = 1024;
 
+/**
+ * Represents an ordered list of free-text strings.
+ *
+ * @remarks
+ * `required` requires at least one entry. `minimum` and `maximum` count entries.
+ * `pattern`, `email`, `url`, `integer`, and `alphanumeric` check each entry and name
+ * the failing value in its message. `custom` checks the whole list. Duplicates are retained.
+ *
+ * @example
+ * ```ts
+ * const to: ListField = {
+ * 	control: 'list', name: 'to', rule: { required: true, email: true },
+ * }
+ * ```
+ */
+export declare interface ListField extends FieldBase {
+    readonly control: 'list';
+    readonly default?: readonly string[];
+}
+
 /**
  * Decides whether a raw binding value projects to an answered field.
  *
@@ -1209,7 +1230,7 @@ export declare const LIST_LIMIT = 1024;
  * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
  * value and a string containing only whitespace as unanswered. Every other field value is an
  * answer, including an empty list, `false`, and zero. Core evaluation does not use this projection:
- * its `required` rule remains presence-only.
+ * its `required` rule remains presence-only except that `list` requires an entry.
  *
  * @param value - The raw field value, or absence.
  * @returns True if the binding preserves the value as an answer; false otherwise.

package/dist/src/core/index.d.ts

@@ -12,7 +12,7 @@ export declare const ALPHANUMERIC_PATTERN: Readonly<RegExp>;
  *
  * @remarks
  * The runtime control-membership check keeps this boundary total for JavaScript callers that
- * bypass the declared {@link FieldControl} contract.
+ * pass values outside the declared {@link FieldControl} contract.
  *
  * @param control - The field control to inspect.
  * @param rule - The named rule to inspect.
@@ -354,7 +354,7 @@ export declare interface FieldChoice {
  * const control: FieldControl = 'select'
  * ```
  */
-export declare type FieldControl = 'text' | 'editor' | 'password' | 'number' | 'date' | 'time' | 'datetime' | 'color' | 'confirm' | 'select' | 'checkbox' | 'file';
+export declare type FieldControl = 'text' | 'editor' | 'password' | 'number' | 'date' | 'time' | 'datetime' | 'color' | 'confirm' | 'select' | 'checkbox' | 'list' | 'file';
 
 /**
  * Represents one failed check against one field.
@@ -377,11 +377,12 @@ export declare interface FieldError {
  * `minimum` and `maximum` measure whatever the control makes countable: characters for
  * `text`, `editor`, and `password`; magnitude for `number`; chronology for `date`, `time`,
  * and `datetime`, whose operand is a string written in that control's own format; and the
- * number of selections for `checkbox` and `file`.
+ * number of entries for `checkbox`, `list`, and `file`.
  *
  * `step` is the interval a numeric value must land on. `pattern` is regular-expression
  * source. `email`, `url`, `integer`, and `alphanumeric` each assert one shape over the whole
- * value. `custom` runs last and is the only rule that sees the rest of the form.
+ * value, or each entry of a `list`. `required` requires an entry for `list` and presence
+ * for other controls. `custom` runs last and is the only rule that sees the rest of the form.
  *
  * @example
  * ```ts
@@ -415,7 +416,7 @@ export declare type FieldRuleName = Exclude<keyof FieldRule, 'custom'>;
  *
  * @remarks
  * It runs after every named rule, and it runs on an absent value as well as a present one. That
- * is what makes a rule such as "required once the sibling says yes" expressible, and it means an
+ * is what makes a rule such as "required after the sibling says yes" expressible, and it means an
  * unanswered field can carry both a `required` message and this validator's own.
  *
  * @param value - The value the field holds, or `undefined` when nobody has answered it.
@@ -440,7 +441,7 @@ export declare type FieldValidator = (value: FieldValue | undefined, values: For
  *
  * @remarks
  * The variant follows the control: text-like controls hold a `string`, `number` holds a
- * `number`, `confirm` holds a `boolean`, and `checkbox` holds its checked values as a
+ * `number`, `confirm` holds a `boolean`, and `checkbox`, `list`, and `file` hold a
  * `readonly string[]`.
  */
 export declare type FieldValue = string | number | boolean | readonly string[];
@@ -753,7 +754,7 @@ export declare type FormEventMap = {
  * }
  * ```
  */
-export declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | FileField;
+export declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | ListField | FileField;
 
 /**
  * Represents a named section of a form.
@@ -772,7 +773,7 @@ export declare interface FormGroup {
  * Declares the contract a form exposes: the state it holds and the calls that move it.
  *
  * @remarks
- * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
+ * `valid` is true when the last completed evaluation found no error, and `dirty` is true when
  * an answer differs from its acknowledged baseline. Both are derived, never stored.
  *
  * `touched` holds the fields somebody has visited, which is what lets a renderer withhold an
@@ -1202,6 +1203,26 @@ export declare function isFormValues(input: unknown): input is FormValues;
 /** Caps the number of entries one list-valued answer may hold, at 1024. */
 export declare const LIST_LIMIT = 1024;
 
+/**
+ * Represents an ordered list of free-text strings.
+ *
+ * @remarks
+ * `required` requires at least one entry. `minimum` and `maximum` count entries.
+ * `pattern`, `email`, `url`, `integer`, and `alphanumeric` check each entry and name
+ * the failing value in its message. `custom` checks the whole list. Duplicates are retained.
+ *
+ * @example
+ * ```ts
+ * const to: ListField = {
+ * 	control: 'list', name: 'to', rule: { required: true, email: true },
+ * }
+ * ```
+ */
+export declare interface ListField extends FieldBase {
+    readonly control: 'list';
+    readonly default?: readonly string[];
+}
+
 /**
  * Decides whether a raw binding value projects to an answered field.
  *
@@ -1209,7 +1230,7 @@ export declare const LIST_LIMIT = 1024;
  * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
  * value and a string containing only whitespace as unanswered. Every other field value is an
  * answer, including an empty list, `false`, and zero. Core evaluation does not use this projection:
- * its `required` rule remains presence-only.
+ * its `required` rule remains presence-only except that `list` requires an entry.
  *
  * @param value - The raw field value, or absence.
  * @returns True if the binding preserves the value as an answer; false otherwise.

package/dist/src/core/index.js

@@ -14,6 +14,7 @@ var FIELD_CONTROLS = Object.freeze([
 	"confirm",
 	"select",
 	"checkbox",
+	"list",
 	"file"
 ]);
 /** Lists the members every field declares, whatever its control. */
@@ -66,6 +67,7 @@ var FIELD_KEYS = Object.freeze({
 		"choices",
 		"default"
 	]),
+	list: Object.freeze([...FIELD_BASE_KEYS, "default"]),
 	file: Object.freeze([
 		...FIELD_BASE_KEYS,
 		"accept",
@@ -324,6 +326,7 @@ function isFormField(input) {
 				const fallback = hasDefault ? input.default : void 0;
 				return arrayOf(isFieldChoice)(choices) && (!hasDefault || arrayOf(isString)(fallback));
 			}
+			case "list": return !Object.hasOwn(input, "default") || arrayOf(isString)(input.default);
 			case "file": {
 				const hasAccept = Object.hasOwn(input, "accept");
 				const accept = hasAccept ? input.accept : void 0;
@@ -448,6 +451,12 @@ function cloneFormField(field) {
 			choices: cloneChoices(field.choices),
 			...field.default === void 0 ? {} : { default: cloneValue(field.default) }
 		});
+		case "list": return Object.freeze({
+			...field,
+			...rule,
+			...meta,
+			...field.default === void 0 ? {} : { default: cloneValue(field.default) }
+		});
 		case "file": return Object.freeze({
 			...field,
 			...rule,
@@ -572,6 +581,7 @@ function matchesField(field, value) {
 		case "confirm": return isBoolean(value);
 		case "select": return isString(value) && !field.choices.some((choice) => choice.value === value && choice.disabled === true) && (field.open === true || field.choices.some((choice) => choice.value === value && choice.disabled !== true));
 		case "checkbox": return entries !== void 0 && entries.every((entry) => isString(entry) && field.choices.some((choice) => choice.value === entry && choice.disabled !== true)) && new Set(entries).size === entries.length;
+		case "list": return entries !== void 0;
 		case "file": return entries !== void 0 && (field.multiple === true || entries.length <= 1);
 	}
 }
@@ -582,7 +592,7 @@ function matchesField(field, value) {
 * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
 * value and a string containing only whitespace as unanswered. Every other field value is an
 * answer, including an empty list, `false`, and zero. Core evaluation does not use this projection:
-* its `required` rule remains presence-only.
+* its `required` rule remains presence-only except that `list` requires an entry.
 *
 * @param value - The raw field value, or absence.
 * @returns True if the binding preserves the value as an answer; false otherwise.
@@ -595,7 +605,7 @@ function matchesAnswer(value) {
 *
 * @remarks
 * The runtime control-membership check keeps this boundary total for JavaScript callers that
-* bypass the declared {@link FieldControl} contract.
+* pass values outside the declared {@link FieldControl} contract.
 *
 * @param control - The field control to inspect.
 * @param rule - The named rule to inspect.
@@ -630,7 +640,7 @@ function appliesRule(control, rule) {
 function evaluateField(field, value, values, messages) {
 	const errors = [];
 	const rule = field.rule;
-	if (value === void 0) {
+	if (value === void 0 || field.control === "list" && isArray(value) && value.length === 0) {
 		if (rule?.required === true && appliesRule(field.control, "required")) errors.push(createFieldError(field, "required", void 0, messages));
 	}
 	if (rule === void 0) return Object.freeze(errors);
@@ -651,6 +661,7 @@ function evaluateField(field, value, values, messages) {
 				failed = isString(value) && isString(rule.minimum) && value < rule.minimum;
 				break;
 			case "checkbox":
+			case "list":
 			case "file": failed = isArray(value) && isFiniteNumber(rule.minimum) && value.length < rule.minimum;
 		}
 		if (failed) errors.push(createFieldError(field, "minimum", rule.minimum, messages));
@@ -672,6 +683,7 @@ function evaluateField(field, value, values, messages) {
 				failed = isString(value) && isString(rule.maximum) && value > rule.maximum;
 				break;
 			case "checkbox":
+			case "list":
 			case "file": failed = isArray(value) && isFiniteNumber(rule.maximum) && value.length > rule.maximum;
 		}
 		if (failed) errors.push(createFieldError(field, "maximum", rule.maximum, messages));
@@ -680,19 +692,45 @@ function evaluateField(field, value, values, messages) {
 		const multiple = (value - (isFiniteNumber(rule.minimum) ? rule.minimum : 0)) / rule.step;
 		if (!isFiniteNumber(rule.step) || rule.step === 0 || !isFiniteNumber(multiple) || Math.abs(multiple - Math.round(multiple)) > 1e-9) errors.push(createFieldError(field, "step", rule.step, messages));
 	}
-	if (isString(value)) {
-		if (rule.pattern !== void 0 && appliesRule(field.control, "pattern")) {
-			const pattern = rule.pattern;
-			if (pattern.length > 256) errors.push(createFieldError(field, "pattern", void 0, messages));
-			else {
-				const outcome = attempt(() => new RegExp(pattern).test(value));
-				if (!outcome.success || !outcome.value) errors.push(createFieldError(field, "pattern", void 0, messages));
+	const entries = isString(value) ? [value] : field.control === "list" && isArray(value) ? value : [];
+	for (const constraint of [
+		"pattern",
+		"email",
+		"url",
+		"alphanumeric",
+		"integer"
+	]) {
+		if (!appliesRule(field.control, constraint)) continue;
+		for (const entry of entries) {
+			let failed = false;
+			switch (constraint) {
+				case "pattern": {
+					const pattern = rule.pattern;
+					if (pattern !== void 0) {
+						const outcome = attempt(() => pattern.length <= 256 && new RegExp(pattern).test(entry));
+						failed = !outcome.success || !outcome.value;
+					}
+					break;
+				}
+				case "email":
+					failed = rule.email === true && !EMAIL_PATTERN.test(entry);
+					break;
+				case "url":
+					failed = rule.url === true && !URL_PATTERN.test(entry);
+					break;
+				case "alphanumeric":
+					failed = rule.alphanumeric === true && !ALPHANUMERIC_PATTERN.test(entry);
+					break;
+				case "integer": failed = rule.integer === true && !INTEGER_PATTERN.test(entry);
+			}
+			if (failed) {
+				const error = createFieldError(field, constraint, void 0, messages);
+				errors.push(field.control === "list" ? Object.freeze({
+					...error,
+					message: `${JSON.stringify(entry)}: ${error.message}`
+				}) : error);
 			}
 		}
-		if (rule.email === true && appliesRule(field.control, "email") && !EMAIL_PATTERN.test(value)) errors.push(createFieldError(field, "email", void 0, messages));
-		if (rule.url === true && appliesRule(field.control, "url") && !URL_PATTERN.test(value)) errors.push(createFieldError(field, "url", void 0, messages));
-		if (rule.alphanumeric === true && appliesRule(field.control, "alphanumeric") && !ALPHANUMERIC_PATTERN.test(value)) errors.push(createFieldError(field, "alphanumeric", void 0, messages));
-		if (rule.integer === true && appliesRule(field.control, "integer") && !INTEGER_PATTERN.test(value)) errors.push(createFieldError(field, "integer", void 0, messages));
 	}
 	if (value !== void 0 && field.control === "number" && rule.integer === true && appliesRule(field.control, "integer") && !isInteger(value)) errors.push(createFieldError(field, "integer", void 0, messages));
 	if (rule.custom !== void 0) {
@@ -736,6 +774,7 @@ function computeDefaults(schema) {
 	const defaults = {};
 	for (const field of schema.fields) switch (field.control) {
 		case "checkbox":
+		case "list":
 			if (field.default !== void 0) defineEntry(defaults, field.name, cloneValue(field.default));
 			break;
 		case "password":
@@ -923,6 +962,9 @@ function serializeForm(schema) {
 				});
 				if (field.default !== void 0) entry.default = field.default;
 				break;
+			case "list":
+				if (field.default !== void 0) entry.default = field.default;
+				break;
 			case "file":
 				if (field.accept !== void 0) entry.accept = field.accept;
 				if (field.multiple !== void 0) entry.multiple = field.multiple;
@@ -1074,7 +1116,8 @@ function auditSchema(schema) {
 			case "color":
 			case "confirm":
 			case "select":
-			case "checkbox": if (field.default !== void 0 && !matchesField(field, field.default)) faults.push(`Field "${field.name}" has an invalid default`);
+			case "checkbox":
+			case "list": if (field.default !== void 0 && !matchesField(field, field.default)) faults.push(`Field "${field.name}" has an invalid default`);
 		}
 		if (field.control === "select" || field.control === "checkbox") {
 			const choices = /* @__PURE__ */ new Set();
@@ -1093,6 +1136,11 @@ function auditSchema(schema) {
 		}
 		const rule = field.rule;
 		if (rule === void 0) continue;
+		if (field.control === "list") {
+			for (const bound of [rule.minimum, rule.maximum]) if (isFiniteNumber(bound) && (!isInteger(bound) || bound < 0)) faults.push(`Field "${field.name}" has a count that is not a nonnegative integer`);
+			if (isFiniteNumber(rule.minimum) && rule.minimum > 1024) faults.push(`Field "${field.name}" has minimum greater than ${LIST_LIMIT}`);
+			if (rule.required === true && isFiniteNumber(rule.maximum) && rule.maximum < 1) faults.push(`Field "${field.name}" is required but permits no entries`);
+		}
 		const temporal = field.control === "date" || field.control === "time" || field.control === "datetime";
 		if (rule.minimum !== void 0 && !appliesRule(field.control, "minimum")) faults.push(`Field "${field.name}" has minimum on ${field.control}`);
 		else if (isString(rule.minimum) && !temporal) faults.push(`Field "${field.name}" has a string minimum on ${field.control}`);