DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
# frozen_string_literal: true
|
|
|
|
|
|
|
|
module PageObjects
|
|
|
|
module Components
|
2024-08-01 21:36:17 +08:00
|
|
|
class FormKitContainer < PageObjects::Components::Base
|
|
|
|
attr_reader :component
|
|
|
|
|
|
|
|
def initialize(input)
|
|
|
|
if input.is_a?(Capybara::Node::Element)
|
|
|
|
@component = input
|
|
|
|
else
|
|
|
|
@component = find(input)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def has_content?(content)
|
|
|
|
component.has_content?(content)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
class FormKitField < PageObjects::Components::Base
|
|
|
|
attr_reader :component
|
|
|
|
|
|
|
|
def initialize(input)
|
|
|
|
if input.is_a?(Capybara::Node::Element)
|
|
|
|
@component = input
|
|
|
|
else
|
|
|
|
@component = find(input)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def value
|
|
|
|
case control_type
|
|
|
|
when /input-/, "password"
|
|
|
|
component.find("input").value
|
|
|
|
when "icon"
|
|
|
|
picker = PageObjects::Components::SelectKit.new(component)
|
|
|
|
picker.value
|
|
|
|
when "checkbox"
|
|
|
|
component.find("input[type='checkbox']").checked?
|
|
|
|
when "menu"
|
|
|
|
component.find(".fk-d-menu__trigger")["data-value"]
|
|
|
|
when "select"
|
|
|
|
component.find("select").value
|
2024-07-26 00:07:38 +08:00
|
|
|
when "composer"
|
|
|
|
component.find("textarea").value
|
DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def unchecked?
|
|
|
|
if control_type != "checkbox"
|
|
|
|
raise "'unchecked?' is only supported for control type: #{control_type}"
|
|
|
|
end
|
|
|
|
|
|
|
|
expect(self.value).to eq(false)
|
|
|
|
end
|
|
|
|
|
|
|
|
def checked?
|
|
|
|
if control_type != "checkbox"
|
|
|
|
raise "'checked?' is only supported for control type: #{control_type}"
|
|
|
|
end
|
|
|
|
|
|
|
|
expect(self.value).to eq(true)
|
|
|
|
end
|
|
|
|
|
|
|
|
def has_value?(expected_value)
|
|
|
|
expect(self.value).to eq(expected_value)
|
|
|
|
end
|
|
|
|
|
2024-10-14 13:19:53 +08:00
|
|
|
def has_errors?(*messages)
|
|
|
|
within component do
|
|
|
|
messages.all? { |m| find(".form-kit__errors", text: m) }
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def has_no_errors?
|
|
|
|
!has_css?(".form-kit__errors")
|
|
|
|
end
|
|
|
|
|
DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
def control_type
|
|
|
|
component["data-control-type"]
|
|
|
|
end
|
|
|
|
|
|
|
|
def toggle
|
|
|
|
case control_type
|
|
|
|
when "checkbox"
|
|
|
|
component.find("input[type='checkbox']").click
|
|
|
|
when "password"
|
|
|
|
component.find(".form-kit__control-password-toggle").click
|
|
|
|
else
|
|
|
|
raise "'toggle' is not supported for control type: #{control_type}"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def fill_in(value)
|
|
|
|
case control_type
|
2024-09-12 11:35:33 +08:00
|
|
|
when "input-text", "password", "input-date"
|
DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
component.find("input").fill_in(with: value)
|
|
|
|
when "textarea", "composer"
|
|
|
|
component.find("textarea").fill_in(with: value, visible: :all)
|
|
|
|
when "code"
|
|
|
|
component.find(".ace_text-input", visible: :all).fill_in(with: value)
|
|
|
|
else
|
|
|
|
raise "Unsupported control type: #{control_type}"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def select(value)
|
|
|
|
case control_type
|
|
|
|
when "icon"
|
|
|
|
selector = component.find(".form-kit__control-icon")["id"]
|
|
|
|
picker = PageObjects::Components::SelectKit.new("#" + selector)
|
|
|
|
picker.expand
|
|
|
|
picker.search(value)
|
|
|
|
picker.select_row_by_value(value)
|
|
|
|
when "select"
|
2024-10-21 18:11:43 +08:00
|
|
|
selector = component.find(".form-kit__control-select")
|
|
|
|
selector.find(".form-kit__control-option[value='#{value}']").select_option
|
|
|
|
selector.execute_script(<<~JS, selector)
|
|
|
|
var selector = arguments[0];
|
|
|
|
selector.dispatchEvent(new Event("input", { bubbles: true, cancelable: true }));
|
|
|
|
JS
|
DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
when "menu"
|
|
|
|
trigger = component.find(".fk-d-menu__trigger.form-kit__control-menu")
|
|
|
|
trigger.click
|
|
|
|
menu = find("[aria-labelledby='#{trigger["id"]}']")
|
|
|
|
item = menu.find(".form-kit__control-menu-item[data-value='#{value}'] .btn")
|
|
|
|
item.click
|
|
|
|
when "radio-group"
|
|
|
|
radio = component.find("input[type='radio'][value='#{value}']")
|
|
|
|
radio.click
|
|
|
|
when "question"
|
|
|
|
if value == true
|
|
|
|
accept
|
|
|
|
else
|
|
|
|
refuse
|
|
|
|
end
|
|
|
|
else
|
|
|
|
raise "Unsupported control type: #{control_type}"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def accept
|
|
|
|
if control_type == "question"
|
|
|
|
component.find(".form-kit__control-radio[value='true']").click
|
|
|
|
else
|
|
|
|
raise "'accept' is not supported for control type: #{control_type}"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def refuse
|
|
|
|
if control_type == "question"
|
|
|
|
component.find(".form-kit__control-radio[value='false']").click
|
|
|
|
else
|
|
|
|
raise "'accept' is not supported for control type: #{control_type}"
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def disabled?
|
|
|
|
component["data-disabled"] == ""
|
|
|
|
end
|
|
|
|
|
|
|
|
def enabled?
|
|
|
|
!disabled?
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
class FormKit < PageObjects::Components::Base
|
|
|
|
attr_reader :component
|
|
|
|
|
|
|
|
def initialize(component)
|
|
|
|
@component = component
|
|
|
|
end
|
|
|
|
|
|
|
|
def submit
|
|
|
|
page.execute_script(
|
|
|
|
"var form = arguments[0]; form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }));",
|
|
|
|
find(component),
|
|
|
|
)
|
|
|
|
end
|
|
|
|
|
|
|
|
def reset
|
|
|
|
page.execute_script(
|
|
|
|
"var form = arguments[0]; form.dispatchEvent(new Event('reset', { bubbles: true, cancelable: true }));",
|
|
|
|
find(component),
|
|
|
|
)
|
|
|
|
end
|
|
|
|
|
|
|
|
def has_an_alert?(message)
|
|
|
|
within component do
|
|
|
|
find(".form-kit__alert-message", text: message)
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def field(name)
|
|
|
|
within component do
|
|
|
|
FormKitField.new(find(".form-kit__field[data-name='#{name}']"))
|
|
|
|
end
|
|
|
|
end
|
2024-08-01 21:36:17 +08:00
|
|
|
|
2024-10-21 18:11:43 +08:00
|
|
|
def has_field_with_name?(name)
|
|
|
|
has_css?(".form-kit__field[data-name='#{name}']")
|
|
|
|
end
|
|
|
|
|
|
|
|
def has_no_field_with_name?(name)
|
|
|
|
has_no_css?(".form-kit__field[data-name='#{name}']")
|
|
|
|
end
|
|
|
|
|
2024-08-01 21:36:17 +08:00
|
|
|
def container(name)
|
|
|
|
within component do
|
|
|
|
FormKitContainer.new(find(".form-kit__container[data-name='#{name}']"))
|
|
|
|
end
|
|
|
|
end
|
|
|
|
|
|
|
|
def choose_conditional(name)
|
|
|
|
find(".form-kit__conditional-display .form-kit__control-radio[value='#{name}']").click
|
|
|
|
end
|
DEV: form-kit
This PR introduces FormKit, a component-based form library designed to simplify form creation and management. This library provides a single `Form` component, various field components, controls, validation mechanisms, and customization options. Additionally, it includes helpers to facilitate testing and writing specifications for forms.
1. **Form Component**:
- The main component that encapsulates form logic and structure.
- Yields various utilities like `Field`, `Submit`, `Alert`, etc.
**Example Usage**:
```gjs
import Form from "discourse/form";
<template>
<Form as |form|>
<form.Field
@name="username"
@title="Username"
@validation="required"
as |field|
>
<field.Input />
</form.Field>
<form.Field @name="age" @title="Age" as |field|>
<field.Input @type="number" />
</form.Field>
<form.Submit />
</Form>
</template>
```
2. **Validation**:
- Built-in validation rules such as `required`, `number`, `length`, and `url`.
- Custom validation callbacks for more complex validation logic.
**Example Usage**:
```javascript
validateUsername(name, value, data, { addError }) {
if (data.bar / 2 === value) {
addError(name, "That's not how maths work.");
}
}
```
```hbs
<form.Field @name="username" @validate={{this.validateUsername}} />
```
3. **Customization**:
- Plugin outlets for extending form functionality.
- Styling capabilities through propagated attributes.
- Custom controls with properties provided by `form` and `field`.
**Example Usage**:
```hbs
<Form class="my-form" as |form|>
<form.Field class="my-field" as |field|>
<MyCustomControl id={{field.id}} @onChange={{field.set}} />
</form.Field>
</Form>
```
4. **Helpers for Testing**:
- Test assertions for form and field validation.
**Example usage**:
```javascript
assert.form().hasErrors("the form shows errors");
assert.form().field("foo").hasValue("bar", "user has set the value");
```
- Helper for interacting with he form
**Example usage**:
```javascript
await formKit().field("foo").fillIn("bar");
```
5. **Page Object for System Specs**:
- Page objects for interacting with forms in system specs.
- Methods for submitting forms, checking alerts, and interacting with fields.
**Example Usage**:
```ruby
form = PageObjects::Components::FormKit.new(".my-form")
form.submit
expect(form).to have_an_alert("message")
```
**Field Interactions**:
```ruby
field = form.field("foo")
expect(field).to have_value("bar")
field.fill_in("bar")
```
6. **Collections handling**:
- A specific component to handle array of objects
**Example Usage**:
```gjs
<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
<form.Collection @name="foo" as |collection|>
<collection.Field @name="bar" @title="Bar" as |field|>
<field.Input />
</collection.Field>
</form.Collection>
</Form>
```
2024-07-17 17:59:35 +08:00
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|