foldkit-form 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Patrick Glenn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,304 @@
1
+ # foldkit-form
2
+
3
+ A form as a Foldkit Submodel: built from the input an operation accepts, holding
4
+ what the user is typing, and handing the parent a decoded value when it is
5
+ valid. It adds no state system. Field state is Foldkit core's
6
+ `fieldValidation`, and the form is a [`foldkit-bundle`](../bundle/README.md)
7
+ Bundle the parent places like any other.
8
+
9
+ > **Status:** headless. It owns the Model, Messages, validation, and a
10
+ > description of each control, and draws nothing.
11
+ > [`foldkit-mixins-form`](../mixins-form/README.md) draws it through Mixins
12
+ > slots; or draw from `controls` yourself.
13
+
14
+ ## What it owns
15
+
16
+ | Fact | Owner |
17
+ | --- | --- |
18
+ | What may be submitted, and when it is valid | the input `Schema.Struct` |
19
+ | What each input key means (a field, a relation's id) | [`Entity.input`](../entity/README.md#reading-an-operations-input) |
20
+ | The draft in each control, and whether it has been checked | `foldkit-form`, in the parent's Model |
21
+ | What happens to a submitted value | the parent: a Remote mutation, a Sync operation, a plain `update` |
22
+ | Whether a submit is in flight, and its failure | whoever performs it; not the form |
23
+ | The options of a relation picker | the application; the form only names the target Entity |
24
+
25
+ ## Mental model
26
+
27
+ ```text
28
+ Schema.Struct (the operation's input)
29
+ +
30
+ Entity.input (what each key means)
31
+ |
32
+ v
33
+ Form.make ──► controls: key · control · label · required (draw these)
34
+ |
35
+ v
36
+ Bundle
37
+ Model: one fieldValidation Field per key, holding the draft
38
+ Changed / Blurred ──► validate the draft against the key's schema
39
+ Submitted ──► every key valid, input decoded ──► out Message { value }
40
+ ```
41
+
42
+ A **draft** is what the control holds, which is not the value it submits. A
43
+ number being typed is text (`"4."` is a fine thing to have typed), an unchosen
44
+ relation is `""`. The draft becomes a value only when it is checked.
45
+
46
+ ## Install
47
+
48
+ ```sh
49
+ pnpm add effect foldkit foldkit-bundle foldkit-entity foldkit-form
50
+ ```
51
+
52
+ ## Example
53
+
54
+ ```ts
55
+ import { Schema } from 'effect'
56
+ import { Bundle } from 'foldkit-bundle'
57
+ import { Entity } from 'foldkit-entity'
58
+ import { Form } from 'foldkit-form'
59
+ import { defineMessageUnion } from 'foldkit/message'
60
+
61
+ const Post = Entity.define(
62
+ 'Post',
63
+ Schema.Struct({
64
+ id: Schema.String,
65
+ title: Schema.String.check(Schema.isMinLength(1)).annotate({ title: 'Title' }),
66
+ }),
67
+ )
68
+
69
+ // The operation's input, declared once. Give the same value to the operation.
70
+ const RenameInput = Schema.Struct({ id: Schema.String, title: Post.fields.title.schema })
71
+
72
+ const Rename = Form.make('Rename', Entity.input(Post, RenameInput))
73
+
74
+ // Place it: a Model field and a Message variant of the page.
75
+ const Slot = Bundle.declare(Rename.bundle, 'rename')
76
+ const Model = Schema.Struct({ ...Slot.fields, saved: Schema.Array(RenameInput) })
77
+ const Message = defineMessageUnion({ ...Slot.cases })
78
+
79
+ const Page = Bundle.parent({ Model, Message })
80
+ const RenameForm = Page.at(Slot, {
81
+ // `submitted.value` is a decoded RenameInput. What it means is the page's.
82
+ onOut: submitted => model => ({
83
+ model: { ...model, saved: [...model.saved, submitted.value] },
84
+ }),
85
+ })
86
+ ```
87
+
88
+ - `Form.make` takes the name and an `Entity.input`. It resolves a control per
89
+ key and throws if it cannot, so a form that is made is a form that can be
90
+ drawn.
91
+ - `Rename.bundle` is an ordinary Bundle. `onOut` is required, so a submit is
92
+ never dropped by omission.
93
+ - `Rename.Message` builds the form's Messages for your view to dispatch:
94
+ `Changed({ key, value })`, `Blurred({ key })`, `Submitted()`, `Reset()`.
95
+ - `Rename.controls` lists the keys in the input's order, each with its
96
+ `control`, `label`, `description`, `required`, and the Entity `member`.
97
+ - `Rename.field(model.rename, key)` reads one key's state as `Field<Draft>`, for
98
+ a view that walks `controls`; `model.rename.fields.title` is the same value
99
+ typed to its key.
100
+
101
+ ## Controls
102
+
103
+ A control is data: the kind of editing, with nothing about how it is drawn.
104
+
105
+ | Control | Draft | Chosen when |
106
+ | --- | --- | --- |
107
+ | `Text`, `Multiline` | `string` | the schema is a string (`Multiline` only when asked for) |
108
+ | `Hidden` | `string` | only when asked for: a key the form carries and does not show, such as the id being edited |
109
+ | `Number` | `string` | the schema is a number |
110
+ | `Toggle` | `boolean` | the schema is a boolean |
111
+ | `Select` | `string` | the schema is a union of string literals; carries `options` |
112
+ | `RelationOne` | `string` (an id, `""` for none) | the key is `Relation.input` of a `one` |
113
+ | `RelationMany` | `string[]` | the key is `Relation.input` of a `many` |
114
+
115
+ The resolver goes from the most to the least explicit source:
116
+
117
+ 1. `inputs` given to `Form.make`, for this form only.
118
+ 2. `Input.of(control)` metadata on the Entity member, for that member everywhere.
119
+ 3. The relation the key writes.
120
+ 4. The shape of the key's schema.
121
+
122
+ If none of them says, `Form.make` throws and names the key. It does not guess.
123
+
124
+ ```ts
125
+ import { Form, Input } from 'foldkit-form'
126
+
127
+ const Cms = Post.pipe(Entity.annotateMembers({ title: Input.of(Input.multiline()) }))
128
+
129
+ Form.make('Rename', Entity.input(Cms, RenameInput), { inputs: { id: Input.text() } })
130
+ ```
131
+
132
+ ### Labels
133
+
134
+ A label is the schema's own `title` annotation, and the description its
135
+ `description`, first on the input key's schema and then on the Entity field's.
136
+ Those annotations already reach JSON Schema, so an agent tool and a form read
137
+ the same words. A relation has no schema to annotate, so it takes
138
+ `Form.label('Author', 'Who wrote it')` as Entity metadata. With neither, the
139
+ label is the key.
140
+
141
+ ## Validation
142
+
143
+ Each key is checked against **the input's own schema for that key**, not the
144
+ Entity's: the operation decides what is valid, and may be stricter.
145
+
146
+ - **An edit** (`Changed`) checks the new draft at once.
147
+ - **Leaving a control** (`Blurred`) checks the draft as it stands, which is how
148
+ a required key left empty comes to say so.
149
+ - **Empty** means `""` or `[]`. What an empty draft submits is whatever the
150
+ schema admits for it, tried in order: leaving the key out, `null`, then the
151
+ empty value itself. A key is `required` exactly when none is admitted, so
152
+ `Schema.optional`, `Schema.NullOr`, and an array need no flag from you. A
153
+ plain `Schema.String` admits `""`; add `Schema.isMinLength(1)` to require it.
154
+ - **A number** that does not parse reads `Enter a number`; one that parses is
155
+ checked by the schema. Only spaces is nothing entered, not zero.
156
+ - **Submit** checks every key, so every failure shows. When all pass, the whole
157
+ input is decoded; a rule that spans keys fails there and lands in
158
+ `model.errors`, since it belongs to no one control. The next edit clears
159
+ them.
160
+
161
+ Field state is `foldkit/fieldValidation`'s `Field`: `NotValidated`, `Validating`
162
+ (a check is running), `Valid`, `Invalid` with its `errors`. Read it with that module's `match`, `isInvalid`,
163
+ and the rest.
164
+
165
+ ### Checks: rules only something else can answer
166
+
167
+ Whether a slug is taken is not in the schema. A check is an Effect the form is
168
+ given; it answers with what is wrong, or nothing:
169
+
170
+ ```ts
171
+ const PostForm = Form.make('PostForm', Entity.input(Post, PostInput), {
172
+ checks: {
173
+ // The decoded value, and whatever else in the form decodes right now.
174
+ slug: (slug, { values }) =>
175
+ isSlugTaken(slug, values.id).pipe(
176
+ Effect.map(taken => (taken ? `"${slug}" is taken` : undefined)),
177
+ ),
178
+ },
179
+ debounce: '300 millis',
180
+ })
181
+ ```
182
+
183
+ - A check runs **after** the key's own schema passes, never instead of it, so it
184
+ receives a decoded value: a number, not the text that was typed.
185
+ - While it runs the key reads `Validating`, which is Foldkit core's own state for
186
+ this. `Valid` on a checked key means the check passed.
187
+ - The form does not know what answers. The check's requirements (`R`) become the
188
+ Bundle's, so a check that needs `RemoteClient` makes the placement need it.
189
+ - Each edit asks again after `debounce`, and an answer for a draft the key no
190
+ longer holds is dropped.
191
+ - **A submit waits.** Submitted while a check runs, the form sets `submitPending`
192
+ and sends the value when the last check passes, or nothing if one fails. An
193
+ edit in between cancels the wait. A filled form (`fill` validates nothing) is
194
+ checked on submit the same way.
195
+ - `context.values` holds the other keys that currently decode, which is how an
196
+ edit form lets a post keep its own slug.
197
+
198
+ ### Messages
199
+
200
+ Say a rule in its own words on the rule, where Effect Schema already takes
201
+ them:
202
+
203
+ ```ts
204
+ Schema.String.check(Schema.isMinLength(3, { message: 'Give it at least 3 letters' }))
205
+ ```
206
+
207
+ The form has three things to say for itself, and `messages` words them, or
208
+ rewrites what Schema says by default, which is also how a form is translated:
209
+
210
+ ```ts
211
+ const Rename = Form.make('Rename', Entity.input(Post, RenameInput), {
212
+ messages: {
213
+ required: field => `${field.label} is missing`,
214
+ notANumber: field => `${field.label} must be a number`,
215
+ invalid: (field, message) => `${field.label}: ${message}`,
216
+ form: message => message,
217
+ },
218
+ })
219
+ ```
220
+
221
+ | Message | Said when | Default |
222
+ | --- | --- | --- |
223
+ | `required(field)` | an empty draft the schema does not admit | `Required` |
224
+ | `notANumber(field)` | a `Number` control whose draft is not a number | `Enter a number` |
225
+ | `invalid(field, message)` | the key's schema rejects the draft; `message` is the check's own, or Schema's | `message` |
226
+ | `form(message)` | the input as a whole fails: a rule that spans keys | `message` |
227
+
228
+ `field` is the key, its label, and its control.
229
+
230
+ ## Nested input
231
+
232
+ A key mapped with [`Relation.nested`](../entity/README.md#an-input-that-holds-the-target-itself)
233
+ holds the relation's target, not an id. **A nested form is a form**: the key
234
+ holds rows, each a Model of the form built from the nested input.
235
+
236
+ ```ts
237
+ const NewComment = Entity.input(Blog.Comment, Schema.Struct({ body: Schema.String }))
238
+ const CreatePost = Entity.input(
239
+ Blog.Post,
240
+ Schema.Struct({ title: Schema.String, comments: Schema.Array(NewComment.schema) }),
241
+ { comments: Relation.nested(Blog.Post.relations.comments, NewComment) },
242
+ )
243
+
244
+ const PostForm = Form.make('PostForm', CreatePost, {
245
+ // A nested key's form takes what any form takes.
246
+ nested: { comments: { inputs: { body: Input.multiline() } } },
247
+ })
248
+
249
+ PostForm.Message.RowAdded({ key: 'comments' })
250
+ PostForm.Message.RowRemoved({ key: 'comments', row: 'r0' })
251
+ PostForm.rows(PostForm.initial, 'comments') // [{ id, model }], each a Model of the nested form
252
+ ```
253
+
254
+ | The key is | Rows |
255
+ | --- | --- |
256
+ | a `one` whose schema must be there | exactly one, from the start; it cannot be removed |
257
+ | a `one` that admits `null` or `undefined` | none or one; none submits that nothing |
258
+ | a `many` | any number, starting with none |
259
+
260
+ - A row is edited with the nested form's own Messages, wrapped:
261
+ `Message.Nested({ key, row, message })`. A Message for a row that is gone, or
262
+ that is not one of the nested form, is dropped. A row's id is never reused.
263
+ - A nested key's control is `{ _tag: 'Nested', cardinality, optional, form }`;
264
+ `form` is the nested form, with its own `controls`, `field`, and `rows`. Nested
265
+ keys are in `model.rows`, not `model.fields`.
266
+ - A submit validates every row too and shows every failure; it waits for a check
267
+ running in a row as it does for its own. A rule on the list itself
268
+ (`Schema.isMaxLength(5)`) is a failure of the whole, in `errors`.
269
+ - `fill` fills rows from values, and nesting goes as deep as the inputs do.
270
+ - `messages` and `debounce` reach nested forms unless they bring their own.
271
+
272
+ ## Editing existing values
273
+
274
+ `fill` shows values as drafts, for an edit form. Keys you do not pass keep their
275
+ draft.
276
+
277
+ ```ts
278
+ const load = RenameForm.helpers.fill({ id: 'p1', title: 'Hello' }) // an Update.Step of the page
279
+ ```
280
+
281
+ What to load, and how a loaded value becomes input values, both follow from the
282
+ form's input, which the form keeps as `Rename.input`:
283
+
284
+ ```ts
285
+ const Current = Entity.selectFor(Rename.input) // a Selection of `id` and `title`
286
+
287
+ declare const loaded: typeof Current.schema.Type
288
+ const prefill = RenameForm.helpers.fill(Entity.valuesFor(Rename.input, loaded))
289
+ ```
290
+
291
+ A relation is loaded as a ref and read back as the id the form holds. See
292
+ [`foldkit-entity`](../entity/README.md#showing-what-is-there).
293
+ [`foldkit-admin`](../admin/README.md) does this, the save, and its status for you.
294
+
295
+ ## Limits
296
+
297
+ - Headless: no view here (see `foldkit-mixins-form`), and no relation picker data. `RelationOne` and
298
+ `RelationMany` carry the target Entity; listing its options is a query the
299
+ application makes.
300
+ - One `Changed` Message carries any draft, so a view can dispatch a draft of the
301
+ wrong kind for a key. The form ignores it rather than storing it.
302
+ - A key whose value is a struct is editable only as a nested input of a
303
+ relation's target; a free-standing struct has no control. Rows keep the order
304
+ they were added in; there is no reordering.
@@ -0,0 +1,330 @@
1
+ import { Duration, Effect, Schema } from "effect";
2
+ import { Bundle } from "foldkit-bundle";
3
+ import { Metadata } from "foldkit-metadata";
4
+ import * as FieldValidation from "foldkit/fieldValidation";
5
+ import { AnyEntity, EntityInput, InputMember, NestedInput } from "foldkit-entity";
6
+ //#region src/input.d.ts
7
+ type Control = {
8
+ readonly _tag: 'Text';
9
+ } |
10
+ /** Carried and submitted, not shown: the id of the thing being edited. Set it with `fill`. */
11
+ {
12
+ readonly _tag: 'Hidden';
13
+ } | {
14
+ readonly _tag: 'Multiline';
15
+ } | {
16
+ readonly _tag: 'Number';
17
+ } | {
18
+ readonly _tag: 'Toggle';
19
+ } | {
20
+ readonly _tag: 'Select';
21
+ readonly options: ReadonlyArray<string>;
22
+ } |
23
+ /** Chooses one of `target`. The options are the application's to supply. */
24
+ {
25
+ readonly _tag: 'RelationOne';
26
+ readonly target: AnyEntity;
27
+ } | {
28
+ readonly _tag: 'RelationMany';
29
+ readonly target: AnyEntity;
30
+ } |
31
+ /**
32
+ * The target itself, edited through a form of its own (`Relation.nested`). The
33
+ * key holds rows of that form: exactly one, at most one, or any number.
34
+ */
35
+ {
36
+ readonly _tag: 'Nested';
37
+ readonly cardinality: 'one' | 'many';
38
+ /** Whether the rows may be none: always for a `many`, for a `one` when its schema admits nothing. */
39
+ readonly optional: boolean;
40
+ readonly form: NestedForm;
41
+ };
42
+ /** One row of a nested key: a Model of the nested form, under an id that outlives reordering. */
43
+ interface FormRow<Model = unknown> {
44
+ readonly id: string;
45
+ readonly model: Model;
46
+ }
47
+ /** What a view needs of a nested form to draw its rows. Every form `Form.make` returns is one. */
48
+ interface NestedForm {
49
+ readonly controls: ReadonlyArray<{
50
+ readonly key: string;
51
+ readonly control: Control;
52
+ readonly label: string;
53
+ readonly description: string | undefined;
54
+ readonly required: boolean;
55
+ }>;
56
+ readonly field: (model: never, key: never) => unknown;
57
+ readonly rows: (model: never, key: never) => ReadonlyArray<FormRow>;
58
+ readonly Message: {
59
+ readonly Changed: (payload: never) => unknown;
60
+ readonly Blurred: (payload: never) => unknown;
61
+ readonly Nested: (payload: never) => unknown;
62
+ readonly RowAdded: (payload: never) => unknown;
63
+ readonly RowRemoved: (payload: never) => unknown;
64
+ };
65
+ }
66
+ /**
67
+ * What a control holds while it is edited, which is not the value it submits: a
68
+ * number being typed is text, and an unchosen relation is the empty string.
69
+ */
70
+ type Draft = string | boolean | ReadonlyArray<string>;
71
+ export declare const Input: {
72
+ text: () => Control;
73
+ hidden: () => Control;
74
+ multiline: () => Control;
75
+ number: () => Control;
76
+ toggle: () => Control;
77
+ select: (options: ReadonlyArray<string>) => Control;
78
+ /**
79
+ * Entity metadata: the control a member is edited with wherever it appears,
80
+ * e.g. `Entity.annotateMembers({ body: Input.of(Input.multiline()) })`.
81
+ */
82
+ of: (control: Control) => Metadata;
83
+ /**
84
+ * The control for one input key, from the most to the least explicit source:
85
+ * the member's `Input.of` metadata, the relation it writes, then the shape of
86
+ * its schema. `undefined` when none of them says, which a form reports rather
87
+ * than guessing.
88
+ */
89
+ resolve: (member: InputMember, schema: Schema.Top) => Control | undefined;
90
+ };
91
+ //#endregion
92
+ //#region src/index.d.ts
93
+ /** The draft a key holds, as far as the input's type says: a flag, a list of ids, or text. */
94
+ export type DraftOf<Value> = [Exclude<Value, null | undefined>] extends [boolean] ? boolean : [Exclude<Value, null | undefined>] extends [ReadonlyArray<unknown>] ? ReadonlyArray<string> : string;
95
+ /** The keys of an input that hold a nested input (`Relation.nested`): rows of a form, not a draft. */
96
+ export type NestedKey<Members> = { [K in keyof Members]: Members[K] extends NestedInput<any, any> ? K : never; }[keyof Members];
97
+ /** The Model of the form a nested key's rows hold. */
98
+ export type NestedModel<Member> = Member extends NestedInput<any, EntityInput<any, infer Fields, infer Members>> ? FormModel<Fields, Members> : never;
99
+ export interface FormModel<Fields extends Schema.Struct.Fields, Members = {}> {
100
+ readonly fields: { readonly [K in keyof Fields as K extends NestedKey<Members> ? never : K]: FieldValidation.Field<DraftOf<Schema.Schema.Type<Fields[K]>>>; };
101
+ /** The rows of each nested key, each a Model of the nested form. */
102
+ readonly rows: { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: ReadonlyArray<FormRow<NestedModel<Members[K & keyof Members]>>>; };
103
+ /** Counts the rows ever added, so a row's id is never reused. */
104
+ readonly nextRow: number;
105
+ /** Failures of the input as a whole, from the last submit: a rule that spans keys. */
106
+ readonly errors: ReadonlyArray<string>;
107
+ /** A submit is waiting for checks still running; it goes out when the last one passes. */
108
+ readonly submitPending: boolean;
109
+ }
110
+ /**
111
+ * A rule only something outside the form can answer: is this slug taken? It is
112
+ * given the decoded value of the key and whatever else in the form currently
113
+ * decodes, and answers with what is wrong, or nothing. It runs after the schema
114
+ * of the key passes, never instead of it.
115
+ */
116
+ export type FormCheck<A, Values, R = never> = (value: A, context: {
117
+ readonly values: Values;
118
+ }) => Effect.Effect<string | undefined, never, R>;
119
+ /** The form's out Message: every key is valid and the input decoded. */
120
+ export interface Submitted<Value> {
121
+ readonly _tag: 'Submitted';
122
+ readonly value: Value;
123
+ }
124
+ /** One key of the form, with everything a view needs to draw it except the pixels. */
125
+ export interface FormControl<Key extends string = string> {
126
+ readonly key: Key;
127
+ readonly control: Control;
128
+ /** The schema's `title` annotation, else `Form.label` metadata, else the key. */
129
+ readonly label: string;
130
+ readonly description: string | undefined;
131
+ /** Whether an empty draft fails. */
132
+ readonly required: boolean;
133
+ readonly member: InputMember;
134
+ }
135
+ /** The key a message is about, for wording that names it. */
136
+ export interface MessageField<Key extends string = string> {
137
+ readonly key: Key;
138
+ readonly label: string;
139
+ readonly control: Control;
140
+ }
141
+ /**
142
+ * The form's words. A rule's own wording belongs on the rule
143
+ * (`Schema.isMinLength(3, { message: '…' })`) and arrives here as `message`;
144
+ * these cover what the form says itself, and let an application translate or
145
+ * rewrite what Schema says by default.
146
+ */
147
+ export interface FormMessages<Key extends string = string> {
148
+ /** An empty draft the schema does not admit. Default `Required`. */
149
+ readonly required?: (field: MessageField<Key>) => string;
150
+ /** A `Number` control whose draft is not a number. Default `Enter a number`. */
151
+ readonly notANumber?: (field: MessageField<Key>) => string;
152
+ /** A draft the key's schema rejects. `message` is the check's own, or Schema's. Default: `message`. */
153
+ readonly invalid?: (field: MessageField<Key>, message: string) => string;
154
+ /** A failure of the input as a whole: a rule that spans keys. Default: `message`. */
155
+ readonly form?: (message: string) => string;
156
+ }
157
+ /** What `Form.make` takes beside the input. A nested key's form takes the same, under `nested`. */
158
+ export interface FormOptions<Fields extends Schema.Struct.Fields, Members, R> {
159
+ /**
160
+ * The control for a key the resolver cannot decide, or should not: an unmapped
161
+ * key with an unusual schema, or text that wants a multiline control here only.
162
+ */
163
+ readonly inputs?: { readonly [K in Exclude<keyof Fields, NestedKey<Members>>]?: Control; };
164
+ /** The form's own words, and a rewrite of Schema's: for wording and for translation. */
165
+ readonly messages?: FormMessages<keyof Fields & string>;
166
+ /** Rules answered outside the form, by key. The key reads `Validating` while one runs. */
167
+ readonly checks?: { readonly [K in Exclude<keyof Fields, NestedKey<Members>>]?: FormCheck<Schema.Schema.Type<Fields[K]>, Partial<Schema.Struct.Type<Fields>>, R>; };
168
+ /** How long a key rests before its check runs, so typing does not ask per keystroke. Default 300ms. */
169
+ readonly debounce?: Duration.Input;
170
+ /** The options of each nested key's form. `messages` and `debounce` are inherited when not given. */
171
+ readonly nested?: { readonly [K in NestedKey<Members> & keyof Fields]?: Members[K] extends NestedInput<any, EntityInput<any, infer NestedFields, infer NestedMembers>> ? FormOptions<NestedFields, NestedMembers, R> : never; };
172
+ }
173
+ export declare const Form: {
174
+ /**
175
+ * A form for one operation's input. A key mapped with `Relation.nested` holds
176
+ * rows of a form of its own, built here from the nested input; every other key
177
+ * holds a draft. `options` names what the input cannot say: a control, the
178
+ * words, the checks.
179
+ */
180
+ make: <const Name extends string, E extends AnyEntity, Fields extends Schema.Struct.Fields, Members extends { readonly [K in keyof Fields]: InputMember; }, R = never>(name: Name, input: EntityInput<E, Fields, Members>, options?: FormOptions<Fields, Members, R>) => {
181
+ bundle: Bundle.Bundle<Name, void, FormModel<Fields, Members>, {
182
+ readonly _tag: "Changed";
183
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
184
+ readonly value: string | boolean | readonly string[];
185
+ } | {
186
+ readonly _tag: "Blurred";
187
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
188
+ } | {
189
+ readonly _tag: "Submitted";
190
+ } | {
191
+ readonly _tag: "Reset";
192
+ } | {
193
+ readonly _tag: "Checked";
194
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
195
+ readonly draft: string | boolean | readonly string[];
196
+ readonly error: string | null;
197
+ } | {
198
+ readonly _tag: "Nested";
199
+ readonly key: string;
200
+ readonly row: string;
201
+ readonly message: unknown;
202
+ } | {
203
+ readonly _tag: "RowAdded";
204
+ readonly key: string;
205
+ } | {
206
+ readonly _tag: "RowRemoved";
207
+ readonly key: string;
208
+ readonly row: string;
209
+ }, Submitted<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>, R, never, void, {}, {
210
+ fill: (model: FormModel<Fields, Members>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
211
+ readonly model: FormModel<Fields, Members>;
212
+ };
213
+ }>;
214
+ Message: import("foldkit/message").MessageUnion<{
215
+ readonly Changed: {
216
+ readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
217
+ readonly value: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
218
+ };
219
+ /** Validates the key as it stands, so a required key left empty says so. */
220
+ readonly Blurred: {
221
+ readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
222
+ };
223
+ readonly Submitted: {};
224
+ readonly Reset: {};
225
+ /** The answer of a check for the draft it was asked about; one for an older draft is dropped. */
226
+ readonly Checked: {
227
+ readonly key: Schema.Literals<readonly [Exclude<keyof Fields & string, NestedKey<Members>>, ...Exclude<keyof Fields & string, NestedKey<Members>>[]]>;
228
+ readonly draft: Schema.Union<readonly [Schema.String, Schema.Boolean, Schema.$Array<Schema.String>]>;
229
+ readonly error: Schema.NullOr<Schema.String>;
230
+ };
231
+ /** A Message of the nested form in one row of a nested key. One that row does not take is dropped. */
232
+ readonly Nested: {
233
+ readonly key: Schema.String;
234
+ readonly row: Schema.String;
235
+ readonly message: Schema.Unknown;
236
+ };
237
+ /** A new, empty row. A `one` that already has its row takes no other. */
238
+ readonly RowAdded: {
239
+ readonly key: Schema.String;
240
+ };
241
+ /** Removes a row. A `one` that must be there stays. */
242
+ readonly RowRemoved: {
243
+ readonly key: Schema.String;
244
+ readonly row: Schema.String;
245
+ };
246
+ }>;
247
+ /** The reading the form was made from, for `Entity.selectFor` and `Entity.valuesFor`. */
248
+ input: EntityInput<E, Fields, Members>;
249
+ /** The `fill` helper as a plain function of the form's Model, for a package that wraps the form. */
250
+ fill: (model: FormModel<Fields, Members>, values: Partial<Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>>>) => {
251
+ readonly model: FormModel<Fields, Members>;
252
+ };
253
+ /** The Model the form starts from and resets to: every key empty and not validated. */
254
+ initial: FormModel<Fields, Members>;
255
+ /** The keys in the input's order, each with its control, label, and member. */
256
+ controls: FormControl<keyof Fields & string>[];
257
+ /**
258
+ * One key's state with its draft as any `Draft`, for a view that walks
259
+ * `controls`. `model.fields.title` is the same value, typed to that key. A
260
+ * nested key has rows and no draft.
261
+ */
262
+ field: (model: FormModel<Fields, Members>, key: Exclude<keyof Fields & string, NestedKey<Members>>) => FieldValidation.Field<Draft>;
263
+ /** The rows of a nested key, each a Model of `control.form`. */
264
+ rows: (model: FormModel<Fields, Members>, key: Extract<keyof Fields & string, NestedKey<Members>>) => { readonly [K in keyof Fields as K extends NestedKey<Members> ? K : never]: readonly FormRow<NestedModel<Members[K & keyof Members]>>[]; }[Extract<keyof Fields & string, NestedKey<Members>>];
265
+ /**
266
+ * Whether a submit now could go through: nothing is invalid. A check still
267
+ * running does not stop it; the submit waits for the answer.
268
+ */
269
+ canSubmit: (model: FormModel<Fields, Members>) => boolean;
270
+ /** The form as the form that nests it drives it. */
271
+ engine: {
272
+ submit: (model: FormModel<Fields, Members>) => {
273
+ model: FormModel<Fields, Members>;
274
+ commands: readonly Readonly<{
275
+ name: string;
276
+ args?: Record<string, unknown>;
277
+ key?: string;
278
+ effect: Effect.Effect<{
279
+ readonly _tag: "Changed";
280
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
281
+ readonly value: string | boolean | readonly string[];
282
+ } | {
283
+ readonly _tag: "Blurred";
284
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
285
+ } | {
286
+ readonly _tag: "Submitted";
287
+ } | {
288
+ readonly _tag: "Reset";
289
+ } | {
290
+ readonly _tag: "Checked";
291
+ readonly key: Exclude<keyof Fields & string, NestedKey<Members>>;
292
+ readonly draft: string | boolean | readonly string[];
293
+ readonly error: string | null;
294
+ } | {
295
+ readonly _tag: "Nested";
296
+ readonly key: string;
297
+ readonly row: string;
298
+ readonly message: unknown;
299
+ } | {
300
+ readonly _tag: "RowAdded";
301
+ readonly key: string;
302
+ } | {
303
+ readonly _tag: "RowRemoved";
304
+ readonly key: string;
305
+ readonly row: string;
306
+ }, never, R>;
307
+ }>[];
308
+ };
309
+ isValidating: (model: FormModel<Fields, Members>) => boolean;
310
+ /** The decoded input when every key and row is valid as it stands; validates nothing. */
311
+ value: (model: FormModel<Fields, Members>) => Schema.Struct.View<Fields, "Type", Schema.Struct.TypeOptionalKeys<Fields>, Schema.Struct.TypeMutableKeys<Fields>> | undefined;
312
+ };
313
+ };
314
+ /**
315
+ * Entity metadata: the label of a member that has no schema to annotate (a
316
+ * relation, a derived member). A field is labelled on its schema, with
317
+ * `Schema.String.annotate({ title })`.
318
+ */
319
+ label: (label: string, description?: string) => Metadata;
320
+ /**
321
+ * What `Form.label` attached to an Entity member, for a package that labels
322
+ * the same member elsewhere, such as a table column.
323
+ */
324
+ labelOf: (member: {
325
+ readonly metadata: Metadata;
326
+ }) => string | undefined;
327
+ };
328
+ //#endregion
329
+ export type { Control, Draft, FormRow, NestedForm };
330
+ //# sourceMappingURL=index.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/input.ts","../src/index.ts"],"mappings":"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"}