A platform for community discussion. Free, open, simple.
DEV: update formkit docs (#38575)
Sam10fc3dac4aa4
diff --git a/docs/developer-guides/docs/03-code-internals/21-form-kit.md b/docs/developer-guides/docs/03-code-internals/21-form-kit.mdindex becd0c4f1ce..4264773bb00 100644--- a/docs/developer-guides/docs/03-code-internals/21-form-kit.md+++ b/docs/developer-guides/docs/03-code-internals/21-form-kit.md@@ -53,7 +53,14 @@ export default class MyForm extends Component {### form-The `Form` component yields a `form` object containing components and helpers.+The `Form` component yields a `form` object containing contextual components and helper functions.++Common members include:++- `Field`, `Object`, `Collection`, `Fieldset`, `Row`, `Section`, `Container`+- `Submit`, `Reset`, `Button`, `Alert`, `Actions`+- `CheckboxGroup`, `InputGroup`, `ConditionalContent`+- `set(name, value)`, `setProperties(object)`, `addItemToCollection(name, value)`**Example**@@ -67,7 +74,7 @@ The `Form` component yields a `form` object containing components and helpers.### transientData-`transientData` represents the state of the data at a given time as it's represented in the form, and not yet propagated to `@data`.+`transientData` is the form's current draft state. It starts as a clone of `@data`, updates as the user edits fields, and does not mutate the original `@data` object.> :information_source: This is useful if you want to have conditionals in your form based on other fields.@@ -75,29 +82,31 @@ The `Form` component yields a `form` object containing components and helpers.```hbs<Form as |form transientData|>- <form.Field @name="amount" @type="input-number" as |field|>+ <form.Field @name="amount" @title="Amount" @type="input-number" as |field|><field.Control /></form.Field>{{#if (gt transientData.amount 200)}}- <form.Field @name="confirmed" @type="checkbox" as |field|>+ <form.Field @name="confirmed" @title="Confirm" @type="checkbox" as |field|><field.Control>I know what I'm doing</field.Control></form.Field>{{/if}}</Form>```-## Properties+## Arguments### @data-Initial state of the data you give to the form.+Initial state of the form data.-**The keys matching the `@name`s of the form's fields will be prepopulated.**+**FormKit expects a plain JavaScript object (POJO).** Internally it clones that object into draft state, tracks patches, and only mutates its own internal copy.-> :information_source: `@data` is treated as an immutable object, following Ember's DDAU pattern. This means when the user enters new data for any of the fields, it will not cause a mutation of `@data`! You can mutate your initial object using `@onSet`.+Keys matching field `@name`s are prepopulated automatically, including nested object and collection paths.-When working with an object object we recommend to setup your form data object like this:+> :information_source: `@data` is treated as immutable. Edits do not mutate the original object you pass in. If you need to keep some external state in sync while editing, do that explicitly in `@onSet`.++When deriving a form object from a model, prefer a cached getter:```js@cached@@ -114,7 +123,7 @@ get formData() {```hbs<Form @data={{hash foo="bar"}} as |form|>- <form.Field @name="foo" @type="input" as |field|>+ <form.Field @name="foo" @title="Foo" @type="input" as |field|><!-- This input will have "bar" as its initial value --><field.Control /></form.Field>@@ -123,25 +132,31 @@ get formData() {### @onRegisterApi-Callback called when the form is inserted. It allows the developer to interact with the form through JavaScript.+Callback called when the form instance is created. It allows the developer to interact with the form through JavaScript.**Parameters**- `callback` (Object): The object containing callback functions.- - `callback.submit` (Function): Function to submit the form.- - `callback.reset` (Function): Function to reset the form.- - `callback.set` (Function): Function to set a key/value on the form data object.- - `callback.setProperties` (Function): Function to set an object on the form data object.- - `callback.isDirty` (boolean): Tracked property return the state of the form. It will be true once changes have been done on the form. Resetting the changes will bring it back to false.+- `callback.get` (Function): Returns the current value for a field name.+- `callback.submit` (Function): Function to submit the form.+- `callback.reset` (Function): Function to reset the form.+- `callback.set` (Function): Function to set a key/value on the form data object.+- `callback.setProperties` (Function): Function to set an object on the form data object.+- `callback.addError` (Function): Function to add an error programmatically.+- `callback.removeError` (Function): Function to remove a single field error.+- `callback.removeErrors` (Function): Function to clear all errors.+- `callback.isDirty` (boolean): Tracked property exposing the dirty state of the form. It becomes `true` after changes are made and returns to `false` after reset.**Example**```js-registerAPI({ submit, reset, set }) {+registerAPI({ get, submit, reset, set, addError }) {// Interact with the form API+ get("foo");submit();reset();set("foo", 1);+ addError("foo", { title: "Foo", message: "Something went wrong" });}```@@ -155,7 +170,7 @@ Callback called when the form is submitted **and valid**.**Parameters**-- `data` (Object): The object containing the form data.+- `data` (Object): The current draft data for the form.**Example**@@ -167,19 +182,45 @@ handleSubmit({ username, age }) {```hbs<Form @onSubmit={{this.handleSubmit}} as |form|>- <form.Field @name="username" @type="input" as |field|>+ <form.Field @name="username" @title="Username" @type="input" as |field|><field.Control /></form.Field>- <form.Field @name="age" @type="input-number" as |field|>+ <form.Field @name="age" @title="Age" @type="input-number" as |field|><field.Control /></form.Field><form.Submit /></Form>```+### @onReset++Callback called after FormKit rolls the draft data back to its initial state and clears errors.++**Parameters**++- `data` (Object): The rolled-back draft data.++**Example**++```js+handleReset(data) {+ console.log("reset to", data);+}+```++```hbs+<Form @data={{this.formData}} @onReset={{this.handleReset}} as |form|>+ <form.Field @name="username" @title="Username" @type="input" as |field|>+ <field.Control />+ </form.Field>++ <form.Reset />+</Form>+```+### @validate-A custom validation callback added directly to the form.+A custom validation callback added directly to the form. This runs once per validation pass, after field-level validation.**Example**@@ -212,16 +253,53 @@ async myValidation(data, { addError }) {}```+### @validateOn++Controls when FormKit should validate.++- Accepted values: `submit` (default), `change`, `focusout`, and `input`.++**Example**++```hbs+<Form @validateOn="change" />+```++### @onDirtyCheck++Callback used during route transitions when the form is dirty. Return a truthy value to show the built-in "dirty form" confirmation dialog, or a falsy value to skip it.++**Parameters**++- `transition` (Transition): The Ember route transition being processed.++**Example**++```js+@action+onDirtyCheck(transition) {+ return transition.to?.name !== "wizard.step";+}+```++```hbs+<Form @onDirtyCheck={{this.onDirtyCheck}} />+```+# Field## @name-A field must have a unique name. This name is used to set the value on the data object and is also used for validation.+A field must have a unique name. This name is used to read/write the value on the form data object and is also used for validation.++Names cannot contain `.` or `-`. Dots are reserved for nested paths such as `profile.location.city`.**Example**```hbs-<form.Field @name="foo" />+<form.Field @name="foo" @title="Foo" @type="input" as |field|>+ <field.Control />+</form.Field>```## @title@@ -231,20 +309,24 @@ A field must have a title. It will be displayed above the control and is also us**Example**```hbs-<form.Field @title="Foo" />+<form.Field @name="foo" @title="Foo" @type="input" as |field|>+ <field.Control />+</form.Field>```## @typeA field must have a type. This determines which control component is rendered. The available types are:-- **Input types**: `input` (defaults to text), `input-number`, `input-email`, `input-password`, `input-url`, `input-tel`, `input-date`, `input-time`, `input-datetime-local`, `input-color`, `input-month`, `input-week`, `input-range`, `input-search`, `input-hidden`+- **Input types**: `input` (defaults to text), `input-text`, `input-number`, `input-email`, `input-password`, `input-url`, `input-tel`, `input-date`, `input-time`, `input-datetime-local`, `input-color`, `input-month`, `input-week`, `input-range`, `input-search`, `input-hidden`- **Other controls**: `checkbox`, `code`, `calendar`, `color`, `composer`, `custom`, `emoji`, `icon`, `image`, `menu`, `password`, `question`, `radio-group`, `select`, `tag-chooser`, `textarea`, `toggle`**Example**```hbs-<form.Field @name="foo" @type="input" />+<form.Field @name="foo" @title="Foo" @type="input" as |field|>+ <field.Control />+</form.Field>```## @description@@ -254,7 +336,15 @@ The description is optional and will be shown under the title when set.**Example**```hbs-<form.Field @description="Bar" />+<form.Field+ @name="foo"+ @title="Foo"+ @description="Bar"+ @type="input"+ as |field|+>+ <field.Control />+</form.Field>```## @helpText@@ -264,7 +354,9 @@ The help text is optional and will be shown under the field when set.**Example**```hbs-<form.Field @helpText="Baz" />+<form.Field @name="foo" @title="Foo" @helpText="Baz" @type="input" as |field|>+ <field.Control />+</form.Field>```## @showTitle@@ -274,7 +366,15 @@ By default, the title will be shown on top of the control. You can choose not to**Example**```hbs-<form.Field @showTitle={{false}} />+<form.Field+ @name="foo"+ @title="Foo"+ @showTitle={{false}}+ @type="input"+ as |field|+>+ <field.Control />+</form.Field>```## @disabled@@ -284,7 +384,15 @@ A field can be disabled to prevent any changes to it.**Example**```hbs-<form.Field @disabled={{true}} />+<form.Field+ @name="foo"+ @title="Foo"+ @disabled={{true}}+ @type="input"+ as |field|+>+ <field.Control />+</form.Field>```## @tooltip@@ -338,7 +446,7 @@ By default, when changing the value of a field, this value will be set on the fo```js@action-handleFooChange(value, { set }) {+handleFooChange(value, { set, name, parentName, index }) {set("foo", value + "-bar");}```@@ -346,6 +454,7 @@ handleFooChange(value, { set }) {```hbs<form.Field@name="foo"+ @title="Foo"@type="input"@onSet={{this.handleFooChange}}as |field|@@ -356,6 +465,13 @@ handleFooChange(value, { set }) {> :information_source: You can use `@onSet` to also mutate the initial data object if you need more reactivity for a specific case.+The second argument passed to `@onSet` contains:++- `set(name, value)`: update form draft state+- `name`: the field's full name+- `parentName`: the parent path for nested fields+- `index`: the current collection index when inside a collection+**Example**```js@@ -370,6 +486,7 @@ handleFooChange(value, { set }) {<Form @data={{this.model}} as |form|><form.Field@name="foo"+ @title="Foo"@type="input"@onSet={{this.handleFooChange}}as |field|@@ -384,7 +501,7 @@ handleFooChange(value, { set }) {The field yields a single field object. The control component determined by `@type` is available as `field.Control`.```hbs-<form.Field @name="foo" @type="input" as |field|>+<form.Field @name="foo" @title="Foo" @type="input" as |field|><field.Control /></form.Field>```@@ -393,6 +510,8 @@ The field yields a single field object. The control component determined by `@ty`field.Control` is the control component determined by `@type`. You can pass control-specific attributes directly to it (e.g., `@height`, `@lang`, `placeholder`).+> :information_source: `field.Control` is the supported API. Older yielded names such as `field.Input` are deprecated.+### fieldThe yielded `field` object provides access to the field's data and helpers:@@ -401,8 +520,9 @@ The yielded `field` object provides access to the field's data and helpers:| --------- | --------------------------------------------------- || `Control` | Contextual component for the control set by `@type` || `id` | ID to be used on the control for accessibility |-| `name` | Name of the field |-| `value` | The value of the field |+| `errorId` | ID of the field error container |+| `name` | Full field name, including nested path prefixes |+| `value` | Current value from draft data || `set` | Function to set the field's value |# Controls@@ -469,56 +589,82 @@ Renders an `<input type="checkbox">` element.</Form>```-## Code+## Calendar-Renders an `<AceEditor />` component.+Renders a datepicker and a time input. On mobile the datepicker will be replaced by a date input.-### @height+### @includeTime-Sets the height of the editor.+Displays the time input or not. Defaults to true.-### @lang+**Example**++```hbs+<Form as |form|>+ <form.Field @name="start" @title="Start" @type="calendar" as |field|>+ <field.Control @includeTime={{false}} />+ </form.Field>+</Form>+```++### @expandedDatePickerOnDesktop-Sets the language of the editor.+Displays date picker expanded on desktop. Defaults to true.**Example**```hbs<Form as |form|>- <form.Field @name="query" @title="Query" @type="code" as |field|>- <field.Control @lang="sql" @height={{400}} />+ <form.Field @name="start" @title="Start" @type="calendar" as |field|>+ <field.Control @expandedDatePickerOnDesktop={{false}} /></form.Field></Form>```-## Calendar+## Code-Renders a datepicker and a time input. On mobile the datepicker will be replaced by a date input.+Renders an `<AceEditor />` component.-### @includeTime+### @height-Displays the time input or not. Defaults to true.+Sets the height of the editor in pixels.++### @lang++Sets the editor mode.**Example**```hbs<Form as |form|>- <form.Field @name="start" @title="Start" @type="calendar" as |field|>- <field.Control @includeTime={{false}} />+ <form.Field @name="query" @title="Query" @type="code" as |field|>+ <field.Control @lang="sql" @height={{400}} /></form.Field></Form>```-### @expandedDatePickerOnDesktop+## Color-Displays date picker expanded on desktop. Defaults to true.+Renders a color input with optional preset swatches.++Common control arguments:++- `@colors`: array of preset colors+- `@usedColors`: array of already-used colors+- `@collapseSwatches`: collapse swatches into a menu+- `@collapseSwatchesLabel`: label for the collapsed swatches button+- `@allowNamedColors`: allow named colors instead of only hex values+- `@fallbackValue`: value to restore on blur when left blank**Example**```hbs<Form as |form|>- <form.Field @name="start" @title="Start" @type="calendar" as |field|>- <field.Control @expandedDatePickerOnDesktop={{false}} />+ <form.Field @name="color" @title="Color" @type="color" as |field|>+ <field.Control+ @colors={{array "0088CC" "FFCC00"}}+ @usedColors={{array "FFCC00"}}+ /></form.Field></Form>```@@ -555,6 +701,44 @@ Controls the display the composer preview. Defaults to `false`.</Form>```+## Custom++Renders a wrapper for custom content. This is the right choice when you want to provide your own control markup but still use FormKit field metadata and state.++**Example**++```hbs+<Form as |form|>+ <form.Field @name="slug" @title="Slug" @type="custom" as |field|>+ <field.Control>+ <MyCustomControl+ id={{field.id}}+ @value={{field.value}}+ @onChange={{field.set}}+ />+ </field.Control>+ </form.Field>+</Form>+```++## Emoji++Renders an `<EmojiPicker />` component.++### @context++Passes the picker context through to `<EmojiPicker />`.++**Example**++```hbs+<Form as |form|>+ <form.Field @name="emoji" @title="Emoji" @type="emoji" as |field|>+ <field.Control @context="chat" />+ </form.Field>+</Form>+```+## IconRenders an `<IconPicker />` component.@@ -573,6 +757,11 @@ Renders an `<IconPicker />` component.Renders an `<UppyImageUploader />` component.+Common control arguments:++- `@type`: uploader context passed to `<UppyImageUploader />`+- `@placeholderUrl`: optional placeholder image+### Upload HandlingBy default, the component will set an upload object. It's common to only want the URL and the ID of the upload. To achieve this, you can use the `@onSet` property on the field:@@ -615,7 +804,7 @@ Renders an `<input>` element.### @type-The input variant is specified as part of the field's `@type` using the `input-` prefix. For example, `@type="input"`, `@type="input-number"`, etc. `@type="input"` defaults to text.+The input variant is specified as part of the field's `@type` using the `input-` prefix. For example, `@type="input"`, `@type="input-number"`, or `@type="input-email"`. `@type="input"` defaults to text.### Allowed Types@@ -631,14 +820,15 @@ The input variant is specified as part of the field's `@type` using the `input-`- `input-range`- `input-search`- `input-tel`+- `input-text`- `input-time`- `input-url`- `input-week`### Special Cases-- `file` is supported only for images through image-- checkbox+- `checkbox` and `radio` have dedicated controls+- file uploads should use `@type="image"`**Examples**@@ -684,7 +874,7 @@ Renders text after the input## Menu-Renders a <DMenu /> component.+Renders a `<DMenu />` trigger with yielded menu content.### @selection@@ -729,7 +919,9 @@ Renders a div which will have for content the yielded content.## Password-Renders an `<input />` of type password. This control also includes a button which will allow to toggle the visibility of the text. When toggle the type of the input will be switched to text.+Renders a password input with a visibility toggle.++> :information_source: This is different from `@type="input-password"`. The dedicated `password` control adds the show/hide button.**Example**@@ -821,7 +1013,11 @@ Allows to render a description.## Select-Renders a `<select>` element.+Renders a `<DSelect />` component.++### @includeNone++By default, Select includes a "none" option when the field is blank or when the field is not marked `required`. Override this with `@includeNone`.**Example**@@ -837,7 +1033,31 @@ Renders a `<select>` element.</Form>```-## Text+## Tag Chooser++Renders a `<TagChooser />` component.++Common control arguments:++- `@allowCreate`+- `@categoryId`+- `@showAllTags`+- `@excludeSynonyms`+- `@excludeTagsWithSynonyms`+- `@unlimited`+- `@placeholder`++**Example**++```hbs+<Form as |form|>+ <form.Field @name="tags" @title="Tags" @type="tag-chooser" as |field|>+ <field.Control @categoryId={{1}} @allowCreate={{true}} />+ </form.Field>+</Form>+```++## TextareaRenders a `<textarea>` element.@@ -880,7 +1100,7 @@ Renders a `<DToggleSwitch />` component.Form Kit aims to provide good defaults, allowing you to mainly use fields and controls. However, if you need more control, we provide several helpers: Row and Col, Section, Fieldset, Container and Actions.-You can also use utilities like Submit, Reset,Alert and InputGroup.+You can also use utilities like Submit, Reset, Alert, CheckboxGroup, InputGroup, and ConditionalContent.## Actions@@ -946,10 +1166,44 @@ Specifies the type of alert. Allowed types: `success`, `error`, `warning`, or `i</form.CheckboxGroup>```+## ConditionalContent++`ConditionalContent` helps you switch between mutually exclusive blocks of content using a small radio control.++**Example**++```hbs+<Form as |form|>+ <form.ConditionalContent @activeName="basic" as |conditional|>+ <conditional.Conditions as |Condition|>+ <Condition @name="basic">Basic</Condition>+ <Condition @name="advanced">Advanced</Condition>+ </conditional.Conditions>++ <conditional.Contents as |Content|>+ <Content @name="basic">+ <form.Alert>Basic settings</form.Alert>+ </Content>++ <Content @name="advanced">+ <form.Alert @type="warning">Advanced settings</form.Alert>+ </Content>+ </conditional.Contents>+ </form.ConditionalContent>+</Form>+```+## Container`Container` allows you to render a block similar to a field without tying it to specific data. It is useful for custom controls.+Common arguments:++- `@title`+- `@subtitle`+- `@format`+- `@direction`+**Example**```hbs@@ -1010,7 +1264,7 @@ Sets the name of the fieldset. This is necessary if you want to use the fieldset## Input Group-Input group allows to group multiple inputs together on one line.+Input group allows you to group multiple inputs together on one line.**Example**@@ -1072,6 +1326,10 @@ To customize the `Reset` button further, you can pass additional parameters as n`Section` provides a simple way to create a section with or without a title.+### @subtitle++Displays secondary text in the section header.+**Example**```hbs@@ -1102,7 +1360,7 @@ To customize the `Submit` button further, you can pass additional parameters as# Object-The object component allows to handle an object in your form.+The object component lets you work with a nested object in your form.**Example**@@ -1123,6 +1381,8 @@ The object component allows to handle an object in your form.An object must have a unique name. This name is used as a prefix for the underlying fields.+Like field names, object names should not contain `.` or `-`.+**Example**```hbs@@ -1163,13 +1423,15 @@ An object can accept a nested Object or Collection.# Collection-The collection component allows to handle array of objects in your form.+The collection component lets you work with arrays in your form.++It yields three values: the collection API, the current index, and the current item.**Example**```hbs<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>- <form.Collection @name="foo" as |collection index|>+ <form.Collection @name="foo" as |collection index item|><collection.Field @name="bar" @title="Bar" @type="input" as |field|><field.Control placeholder={{concat "item-" index}} /></collection.Field>@@ -1183,6 +1445,8 @@ A collection must have a unique name. This name is used as a prefix for the undeFor example, if collection has the name "foo", the 2nd field of the collection with the name "bar", will actually have "foo.1.bar" as name.+Like field names, collection names should not contain `.` or `-`.+**Example**```hbs@@ -1191,7 +1455,7 @@ For example, if collection has the name "foo", the 2nd field of the collection w## @tagName-A collection will by default render as a `<div class="form-kit__collection>`, you can alter this behavior by using a `@tagName`.+A collection renders as a `<div class="form-kit__collection">` by default. You can alter this behavior with `@tagName`.**Example**@@ -1303,176 +1567,303 @@ The value must be `"yes"`, `"on"`, `true`, `1`, or `"true"`. Useful for checkbox**Example**```hbs-<form.Field @name="terms" @type="checkbox" @validation="accepted" as |field|>+<form.Field+ @name="terms"+ @title="Terms"+ @type="checkbox"+ @validation="accepted"+ as |field|+><field.Control /></form.Field>```-### Length+### Between-Checks that the input's value is over a given length, or between two length values.+Checks that a numeric value is between a minimum and maximum value.**Example**```hbs-<form.Field @name="username" @type="input" @validation="length:5,16" as |field|>+<form.Field+ @name="amount"+ @title="Amount"+ @type="input-number"+ @validation="between:1,10"+ as |field|+><field.Control /></form.Field>```-### Number--Checks if the input is a valid number as evaluated by `isNaN()`.+### dateAfterOrEqual-> :information_source: When applicable, prefer to use the number input: `@type="input-number"`.+Checks if a calendar value is after or equal to the specified date. Format must be `YYYY-MM-DD`.**Example**```hbs-<form.Field @name="amount" @type="input" @validation="number" as |field|>+<form.Field+ @name="start"+ @title="Start"+ @type="calendar"+ @validation="dateAfterOrEqual:2022-02-01"+ as |field|+><field.Control /></form.Field>```-### Required+### dateBeforeOrEqual-Checks if the input is empty.+Checks if a calendar value is before or equal to the specified date. Format must be `YYYY-MM-DD`.**Example**```hbs-<form.Field @name="username" @type="input" @validation="required" as |field|>+<form.Field+ @name="start"+ @title="Start"+ @type="calendar"+ @validation="dateBeforeOrEqual:2022-02-01"+ as |field|+><field.Control /></form.Field>```-### URL+### EndsWith-Checks if the input value appears to be a properly formatted URL including the protocol. This does not check if the URL actually resolves.+Checks that a string ends with a given suffix.**Example**```hbs-<form.Field @name="endpoint" @type="input-url" @validation="url" as |field|>+<form.Field+ @name="domain"+ @title="Domain"+ @type="input"+ @validation="endsWith:.com"+ as |field|+><field.Control /></form.Field>```-### integer+### Integer-Checks if the input value is an integer.+Checks if the value is an integer.**Example**```hbs-<form.Field @name="age" @type="input-number" @validation="integer" as |field|>+<form.Field+ @name="age"+ @title="Age"+ @type="input-number"+ @validation="integer"+ as |field|+><field.Control /></form.Field>```-### dateAfterOrEqual+### Length-Checks if the calendar data is after or equal to the specified date. Format must be YYYY-MM-DD.+Checks that the input's value is over a given length, or between two length values.**Example**```hbs<form.Field- @name="start"- @type="calendar"- @validation="dateAfterOrEqual:2022-02-01"+ @name="username"+ @title="Username"+ @type="input"+ @validation="length:5,16"as |field|><field.Control /></form.Field>```-### dateBeforeOrEqual+### Number++Checks if the input is a valid number as evaluated by `isNaN()`.-Checks if the calendar data is before or equal to the specified date. Format must be YYYY-MM-DD.+> :information_source: When applicable, prefer to use the number input: `@type="input-number"`.**Example**```hbs<form.Field- @name="start"- @type="calendar"- @validation="dateBeforeOrEqual:2022-02-01"+ @name="amount"+ @title="Amount"+ @type="input"+ @validation="number"as |field|><field.Control /></form.Field>```-## Combining Rules+### Required-Rules can be combined using the pipe operator: `|`.+Checks if the input is empty.++`required:trim` trims leading and trailing whitespace before checking the value.**Example**```hbs<form.Field@name="username"+ @title="Username"@type="input"- @validation="required|length:5,16"+ @validation="required:trim"as |field|><field.Control /></form.Field>```-## Custom Validation--### Field--Field accepts a `@validate` property which allows you to define a callback function to validate the field. Read more about addError in helpers section.--**Parameters**+### StartsWith-- `name` (string): The name of the form field being validated.-- `value` (string): The value of the form field being validated.-- `data` (Object): The data object containing additional information for validation.-- `handlers` (Object): An object containing handler functions.- - `handlers.addError` (Function): A function to add an error if validation fails.+Checks that a string starts with a given prefix.**Example**-```js-validateUsername(name, value, data, { addError }) {- if (data.bar / 2 === value) {- addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });- }-}-```+```hbs+<form.Field+ @name="handle"+ @title="Handle"+ @type="input"+ @validation="startsWith:@"+ as |field|+>+ <field.Control />+</form.Field>+```++### URL++Checks if the input value appears to be a properly formatted URL including the protocol. This does not check if the URL actually resolves.++**Example**```hbs-<form.Field @name="username" @validate={{this.validateUsername}} />+<form.Field+ @name="endpoint"+ @title="Endpoint"+ @type="input-url"+ @validation="url"+ as |field|+>+ <field.Control />+</form.Field>+```++## Combining Rules++Rules can be combined using the pipe operator: `|`.++**Example**++```hbs+<form.Field+ @name="username"+ @title="Username"+ @type="input"+ @validation="required|length:5,16"+ as |field|+>+ <field.Control />+</form.Field>+```++## Custom Validation++### Field++Field accepts a `@validate` property which allows you to define a callback function to validate a single field.++**Parameters**++- `name` (string): The name of the form field being validated.+- `value` (unknown): The current field value.+- `context` (Object)+ - `context.data` (Object): Current form draft data.+ - `context.type` (string): Field control type.+ - `context.addError` (Function): Adds an error if validation fails.++**Example**++```js+@action+validateUsername(name, value, { data, addError }) {+ if (value === data.slug) {+ addError(name, {+ title: "Username",+ message: "Username and slug must differ.",+ });+ }+}+```++```hbs+<form.Field+ @name="username"+ @title="Username"+ @type="input"+ @validate={{this.validateUsername}}+ as |field|+>+ <field.Control />+</form.Field>```### Form-Form accepts a `@validate` property which allows you to define a callback function to validate the form. This will be called for each field of the form.+Form accepts a `@validate` property which allows you to define a callback function to validate the full form state once per validation pass.**Parameters**- `data` (Object): The data object containing additional information for validation.- `handlers` (Object): An object containing handler functions.- `handlers.addError` (Function): A function to add an error if validation fails.+ - `handlers.removeError` (Function): A function to clear an existing error.**Example**```js-validateForm(data, { addError }) {- if (data.bar / 2 === data.baz) {- addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });+@action+validateForm(data, { addError, removeError }) {+ if (data.start && data.end && data.end < data.start) {+ addError("end", {+ title: "End",+ message: "End must be after start.",+ });+ } else {+ removeError("end");}}``````hbs-<Form @validate={{this.validateForm}} />+<Form @validate={{this.validateForm}} as |form|>+ <form.Field @name="start" @title="Start" @type="input-date" as |field|>+ <field.Control />+ </form.Field>++ <form.Field @name="end" @title="End" @type="input-date" as |field|>+ <field.Control />+ </form.Field>++ <form.Submit />+</Form>```+> :information_source: Unknown validation rule names raise at runtime. Keep the rule list above in sync with the implementation when extending FormKit.+# HelpersHelpers are yielded by some blocks, like Form, or provided as parameters to callbacks. They allow you to interact with the form state in a simple and clear way.@@ -1557,7 +1948,7 @@ FormKit works seamlessly with `<PluginOutlet />`. You can use plugin outlets insThen, in your connector, you can use the outlet arguments to add custom fields:```hbs title="connectors/above-foo-form/bar-input.hbs"-<@outletArgs.form.Field @name="bar" @type="input" as |field|>+<@outletArgs.form.Field @name="bar" @title="Bar" @type="input" as |field|><field.Control /></@outletArgs.form.Field>```@@ -1568,7 +1959,13 @@ All FormKit components propagate attributes, allowing you to set classes and dat```hbs<Form class="my-form" as |form|>- <form.Field @name="foo" @type="input" class="my-field" as |field|>+ <form.Field+ @name="foo"+ @title="Foo"+ @type="input"+ class="my-field"+ as |field|+ ><field.Control class="my-control" /></form.Field></Form>@@ -1580,7 +1977,13 @@ Creating a custom control is straightforward with the properties yielded by `for```hbs<Form as |form|>- <form.Field @type="custom" class="my-field" as |field|>+ <form.Field+ @name="foo"+ @title="Foo"+ @type="custom"+ class="my-field"+ as |field|+ ><field.Control><MyCustomControl id={{field.id}} @onChange={{field.set}} /></field.Control>@@ -1588,86 +1991,61 @@ Creating a custom control is straightforward with the properties yielded by `for</Form>```-### Available Parameters on `form`--| Name | Description |-| ----- | ----------------------------------------------------------------- |-| `set` | Allows you to set the value of any field by name: `set("bar", 1)` |+### Common Values on `form`-# Custom Validation+| Name | Description |+| --------------------- | ------------------------------------------- |+| `set` | Set any field by name, e.g. `set("bar", 1)` |+| `setProperties` | Set multiple field values at once |+| `addItemToCollection` | Append an item to a collection by path |-## Field+### Common Values on `field`-The Field component accepts a `@validate` property, allowing you to define a callback function for custom field validation. Read more about addError in the helpers section.+| Name | Description |+| --------- | ------------------------------------ |+| `id` | Input ID |+| `errorId` | Error container ID |+| `name` | Full nested field path |+| `value` | Current field value from draft state |+| `set` | Set the current field value |-**Parameters**+# Javascript assertions-- `name` (string): The name of the form field being validated.-- `value` (string): The value of the form field being validated.-- `data` (Object): The data object containing additional information for validation.-- `handlers` (Object): An object containing handler functions.- - `handlers.addError` (Function): A function to add an error if validation fails.+## Form-**Example**+The form element assertions are available at `assert.form(...).*`. By default it will select the first "form" element.-```js-validateUsername(name, value, data, { addError }) {- if (data.bar / 2 === value) {- addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });- }-}-```+**Parameters**-```hbs-<form.Field @name="username" @validate={{this.validateUsername}} />-```+- `target` (string | HTMLElement): The form element or selector.-## Form+### hasErrors()-The Form component accepts a `@validate` property, allowing you to define a callback function for custom form validation.+Asserts that the form error summary contains the given field errors.**Parameters**-- `data` (Object): The data object containing additional information for validation.-- `handlers` (Object): An object containing handler functions.- - `handlers.addError` (Function): A function to add an error if validation fails.+- `fields` (Object): A map of field names to error messages, e.g. `{ username: "Required" }`.+- `message` (string) [optional]: The description of the test.**Example**```js-validateForm(data, { addError }) {- if (data.bar / 2 === data.baz) {- addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });- }-}+assert.form().hasErrors({ username: "Required" }, "the form shows errors");```-```hbs-<Form @validate={{this.validateForm}} />-```--# Javascript assertions--## Form--The form element assertions are available at `assert.form(...).*`. By default it will select the first "form" element.--**Parameters**--- `target` (string | HTMLElement): The form element or selector.--### hasErrors()+### hasNoErrors()-Asserts that the form has errors.+Asserts that the form error summary is not present.**Parameters**-- `message` (string): The description of the test.+- `message` (string) [optional]: The description of the test.**Example**```js-assert.form().hasErrors("the form shows errors");+assert.form().hasNoErrors("the form is valid");```## Field@@ -1699,6 +2077,20 @@ Asserts that the `value` of the field matches the `expected` text.assert.form().field("foo").hasValue("bar", "user has set the value");```+### hasNoValue()++Asserts that the field is blank.++**Parameters**++- `message` (string) [optional]: The description of the test.++**Example**++```js+assert.form().field("foo").hasNoValue("the field starts blank");+```+### isDisabled()Asserts that the `field` is disabled.@@ -1727,6 +2119,39 @@ Asserts that the `field` is enabled.assert.form().field("foo").isEnabled("the field is enabled");```+### hasTitle()++Asserts that the field title matches the expected text.++**Parameters**++- `expected` (anything): The expected value.+- `message` (string) [optional]: The description of the test.++**Example**++```js+assert.form().field("foo").hasTitle("Foo", "it shows the field title");+```++### hasDescription()++Asserts that the field description matches the expected text.++**Parameters**++- `expected` (anything): The expected value.+- `message` (string) [optional]: The description of the test.++**Example**++```js+assert+ .form()+ .field("foo")+ .hasDescription("Helpful copy", "it shows the description");+```+### hasError()Asserts that the `field` has a specific error.@@ -1767,7 +2192,7 @@ Asserts that the `field` is present.**Example**```js-assert.form().field("foo").exists("it has the food field");+assert.form().field("foo").exists("it has the foo field");```### doesNotExist()@@ -1781,7 +2206,7 @@ Asserts that the `field` is not present.**Example**```js-assert.form().field("foo").doesNotExist("it has no food field");+assert.form().field("foo").doesNotExist("it has no foo field");```### hasCharCounter()@@ -1862,6 +2287,34 @@ Asserts that the fieldset has yielded the `expected` value.assert.form().fieldset("foo").includesText("bar", "it has the correct text");```+### exists()++Asserts that the fieldset is present.++**Parameters**++- `message` (string) [optional]: The description of the test.++**Example**++```js+assert.form().fieldset("foo").exists("the fieldset is rendered");+```++### doesNotExist()++Asserts that the fieldset is not present.++**Parameters**++- `message` (string) [optional]: The description of the test.++**Example**++```js+assert.form().fieldset("foo").doesNotExist("the fieldset is hidden");+```+# Javascript helpers## Form@@ -1871,13 +2324,13 @@ The FormKit helper allows you to manipulate a form and its fields through a clea**Example**```gjs-import formKit from "discourse/tests/helpers/form-kit";+import formKit from "discourse/tests/helpers/form-kit-helper";test("fill in input", async function (assert) {await render(<template><Form class="my-form" as |form data|>- <form.Field @name="foo" @type="input" as |field|>+ <form.Field @name="foo" @title="Foo" @type="input" as |field|><field.Control /></form.Field></Form>@@ -1908,15 +2361,63 @@ Resets the associated form.formKit().reset();```+### field()++Returns a field helper for a named field.++**Parameters**++- `name` (string): The name of the field.++**Example**++```js+const field = formKit().field("foo");+```++### hasField()++Checks whether a field with the given name exists in the form.++**Parameters**++- `name` (string): The name of the field.++**Example**++```js+formKit().hasField("foo");+```+## Field**Parameters**- `name` (string): The name of the field.+### value()++Returns the current UI value for supported controls.++**Example**++```js+formKit().field("foo").value();+```++### options()++Returns the available option values for a `@type="select"` field.++**Example**++```js+formKit().field("foo").options();+```+### fillIn()-Can be used on `@type="input"`, `@type="code"`, `@type="textarea"`, and `@type="composer"` fields.+Can be used on input-like controls such as `@type="input"`, `@type="input-text"`, `@type="input-number"`, `@type="password"`, `@type="color"`, `@type="code"`, `@type="textarea"`, and `@type="composer"`.**Parameters**@@ -1962,7 +2463,7 @@ await formKit().field("foo").refuse();### select()-Can be used on `@type="select"`, `@type="menu"`, `@type="icon"`, and `@type="radio-group"` fields.+Can be used on `@type="select"`, `@type="menu"`, `@type="icon"`, `@type="radio-group"`, and `@type="color"` fields.Will select the given value.@@ -1976,6 +2477,79 @@ Will select the given value.await formKit().field("foo").select("bar");```+### setDay()++Can be used on `@type="calendar"` fields.++**Parameters**++- `day` (integer): The day of the month to select.++**Example**++```js+await formKit().field("start").setDay(15);+```++### setTime()++Can be used on `@type="calendar"` fields.++**Parameters**++- `time` (string): The time to set, e.g. `"14:30"`.++**Example**++```js+await formKit().field("start").setTime("14:30");+```++### isDisabled()++Returns whether the field is disabled.++**Example**++```js+formKit().field("foo").isDisabled();+```++### hasPrefix()++Can be used on `@type="color"` fields. Returns whether the color input renders its prefix.++**Example**++```js+formKit().field("color").hasPrefix();+```++### swatches()++Can be used on `@type="color"` fields. Returns the rendered swatches as `{ color, isUsed, isDisabled }`.++**Example**++```js+formKit().field("color").swatches();+```++### triggerEvent()++Triggers a DOM event on the field's input element.++**Parameters**++- `eventName` (string): The event to trigger.+- `options` (Object) [optional]: Extra event options.++**Example**++```js+await formKit().field("foo").triggerEvent("blur");+```+# System specs page object## Form@@ -1984,7 +2558,7 @@ The FormKit page object component is available to help you write system specs fo**Parameters**-- `target` (string | Capybara::Node::Element): The selector or node of the form.+- `target` (string): The selector of the form.**Example**@@ -1992,13 +2566,9 @@ The FormKit page object component is available to help you write system specs foform = PageObjects::Components::FormKit.new(".my-form")```-```rb-form = PageObjects::Components::FormKit.new(find(".my-form"))-```-### submit-Submits the form+Submits the form.**Example**@@ -2008,7 +2578,7 @@ form.submit### reset-Reset the form+Resets the form.**Example**@@ -2018,7 +2588,7 @@ form.reset### has_an_alert?-Returns if the field is enabled or not.+Checks whether the form renders an alert with the given message.**Example**@@ -2030,6 +2600,47 @@ form.has_an_alert?("message")expect(form).to have_an_alert("message")```+### has_field_with_name?++Checks whether a field with the given `data-name` exists.++**Example**++```rb+form.has_field_with_name?("foo")+```++### has_no_field_with_name?++Checks whether a field with the given `data-name` is absent.++**Example**++```rb+form.has_no_field_with_name?("foo")+```++### container++Returns a container helper for the named container.++**Example**++```rb+container = form.container("advanced-settings")+container.has_content?("More options")+```++### choose_conditional++Chooses a `ConditionalContent` branch by radio value.++**Example**++```rb+form.choose_conditional("advanced")+```+## FieldThe `field` helper allows you to interact with a specific field of a form.@@ -2058,6 +2669,16 @@ field.valueexpect(field).to have_value("bar")```+### has_value?++Checks that the field value matches the expected value.++**Example**++```rb+field.has_value?("bar")+```+### checked?Returns if the control of a checkbox is checked or not.@@ -2116,7 +2737,7 @@ expect(field).to be_enabled### toggle-Allows toggling a field. Only available for: `@type="checkbox"`.+Allows toggling a field. Available for `@type="checkbox"`, `@type="password"`, and `@type="toggle"`.**Example**@@ -2126,7 +2747,7 @@ field.toggle### fill_in-Allows filling a field with a given value. Only available for: `@type="input"`, `@type="textarea"`, `@type="code"`, and `@type="composer"`.+Allows filling a field with a given value. Available for `@type="input"`, `@type="input-*"` variants, `@type="password"`, `@type="color"`, `@type="textarea"`, `@type="code"`, and `@type="composer"`.**Example**@@ -2136,7 +2757,7 @@ field.fill_in("bar")### select-Allows selecting a specified value in a field. Only available for: `@type="select"`, `@type="icon"`, `@type="menu"`, `@type="radio-group"`, and `@type="question"`.+Allows selecting a specified value in a field. Available for `@type="select"`, `@type="icon"`, `@type="menu"`, `@type="radio-group"`, `@type="question"`, tag choosers, and custom multi-select controls.**Example**@@ -2173,3 +2794,33 @@ Takes an image path on the filesystem and uploads it for the field. Only availab```rbfield.upload_image(image_file_path)```++### has_errors?++Checks that the field renders the given error messages.++**Example**++```rb+field.has_errors?("Required")+```++### has_no_errors?++Checks that the field has no errors.++**Example**++```rb+field.has_no_errors?+```++### has_selected_names?++Checks the selected names for a `@type="tag-chooser"` field.++**Example**++```rb+field.has_selected_names?("support", "meta")+```