Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 | /** Primitive value stored for a rendered form field. */
export type FieldValue = string | number | boolean | null | undefined;
/** Current form values keyed by schema field name. */
export type FormValues = Record<string, FieldValue>;
/** Field types supported by the default renderer set. */
export type BuiltInFieldType =
| "text"
| "email"
| "number"
| "password"
| "textarea"
| "select"
| "checkbox"
| "radio";
/** Built-in field type or a custom renderer type registered by the host application. */
export type FieldType = BuiltInFieldType | (string & {});
/** Option used by `select` and `radio` fields. */
export interface FieldOption {
label: string;
value: string | number | boolean;
}
/** A single declarative visibility condition. */
export interface VisibilityCondition {
/** Field name whose current value should be inspected. */
field: string;
/** The dependent field is visible when the referenced value strictly equals this value. */
equals?: FieldValue;
/** The dependent field is visible when the referenced value does not strictly equal this value. */
notEquals?: FieldValue;
/** The dependent field is visible when the referenced string or array includes this value. */
includes?: FieldValue;
/** The dependent field is visible when the referenced value exists, or does not exist when false. */
exists?: boolean;
}
/** One visibility condition or a simple AND array of conditions. */
export type VisibilityRule = VisibilityCondition | VisibilityCondition[];
/** Built-in validation rule names that can receive custom per-field messages. */
export type ValidationMessageKey =
| "required"
| "minLength"
| "maxLength"
| "min"
| "max"
| "pattern"
| "email"
| "number";
/** Optional per-field overrides for built-in validation messages. */
export type ValidationMessages = Partial<Record<ValidationMessageKey, string>>;
/** Shared schema properties supported by both fields and sections. */
export interface BaseSchemaNode {
/** Optional stable identifier used when deriving DOM IDs and schema paths. */
id?: string;
/** Declarative condition that controls whether this node is currently visible. */
visibleWhen?: VisibilityRule;
}
/** Section/group node used to organize fields without creating a value. */
export interface SectionSchema extends BaseSchemaNode {
/** Discriminator used by the runtime to render a non-value grouping node. */
type: "section";
/** Visible section heading rendered as a fieldset legend. */
title: string;
/** Optional explanatory text rendered safely below the section title. */
description?: string;
/** Child fields or nested sections contained by this section. */
fields: SchemaNode[];
}
/**
* Declarative field definition consumed by the runtime.
*
* Unknown `type` values are allowed only when a matching custom renderer is
* registered through `CreateFormOptions.renderers`.
*/
export interface FieldSchema extends BaseSchemaNode {
/** Built-in field type or custom renderer type. */
type: FieldType;
/** Stable value key used in state, validation errors, and submission values. */
name: string;
/** Visible label associated with the native control. */
label: string;
/** Optional native placeholder text. Never used as a label replacement. */
placeholder?: string;
/** Optional descriptive text referenced through `aria-describedby`. */
helpText?: string;
/** Whether the field must contain a value before submission. */
required?: boolean;
/** Whether the native control is disabled. */
disabled?: boolean;
/** Whether text-like native controls are readonly. */
readonly?: boolean;
/** Options for select and radio fields. */
options?: FieldOption[];
/** Default value used unless `CreateFormOptions.initialValues` overrides it. */
defaultValue?: FieldValue;
/** Minimum string length for text-like values. */
minLength?: number;
/** Maximum string length for text-like values. */
maxLength?: number;
/** Minimum numeric value for number-like fields. */
min?: number;
/** Maximum numeric value for number-like fields. */
max?: number;
/** JavaScript regular expression source used for deterministic pattern validation. */
pattern?: string;
/** Names of synchronous custom validators registered by the host application. */
validators?: string[];
/** Optional field-specific messages for built-in validators. */
validationMessages?: ValidationMessages;
}
/** A schema node is either a value-producing field or a section/group. */
export type SchemaNode = SectionSchema | FieldSchema;
/** Declarative schema passed to `createForm`. */
export interface FormSchema {
/** Stable schema identifier used for generated DOM IDs. */
id: string;
/** Optional form heading rendered above the fields. */
title?: string;
/** Optional safe text rendered under the form title. */
description?: string;
/** Submit button label. Defaults to `Submit`. */
submitLabel?: string;
/** Reset button label. Defaults to `Reset`. */
resetLabel?: string;
/** Top-level fields and sections rendered by the runtime. */
fields: SchemaNode[];
}
export interface NormalizedField extends FieldSchema {
id: string;
path: string[];
}
export interface NormalizedSection extends SectionSchema {
id: string;
path: string[];
fields: NormalizedSchemaNode[];
}
export type NormalizedSchemaNode = NormalizedSection | NormalizedField;
export interface NormalizedFormSchema extends Omit<FormSchema, "fields"> {
fields: NormalizedSchemaNode[];
fieldMap: Map<string, NormalizedField>;
fieldOrder: string[];
}
/** Context passed to synchronous custom validators. */
export interface CustomValidatorContext {
/** Name of the field currently being validated. */
fieldName: string;
/** Snapshot of all current form values. */
values: FormValues;
/** Original public schema for the owning form. */
schema: FormSchema;
}
/**
* Synchronous validator registered by name and referenced from field schemas.
*
* Return a human-readable error message when invalid, or `null` when valid.
*/
export type CustomValidator = (
value: FieldValue,
context: CustomValidatorContext
) => string | null;
/** Custom synchronous validators keyed by the names referenced in field schemas. */
export type CustomValidatorMap = Record<string, CustomValidator>;
/** Single validation error associated with a field. */
export interface FieldError {
/** Name of the field that failed validation. */
fieldName: string;
/** Human-readable validation message. */
message: string;
}
/** Validation errors keyed by field name. */
export type FieldErrors = Record<string, string[]>;
/** Immutable snapshot passed to form event hooks. */
export interface FormStateSnapshot {
/** Current form values keyed by field name. */
values: FormValues;
/** Field names blurred by the user. */
touchedFields: string[];
/** Field names whose current value differs from the initial value. */
dirtyFields: string[];
/** Current validation errors keyed by field name. */
errors: FieldErrors;
/** Whether the current visible form state has no validation errors. */
isValid: boolean;
/** Field names currently visible after evaluating conditions. */
visibleFields: string[];
}
|