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>
   ```
This commit is contained in:
chapoi
2024-07-17 11:59:35 +02:00
committed by GitHub
parent bae492efee
commit 2ca06ba236
141 changed files with 6047 additions and 851 deletions

View File

@@ -2091,6 +2091,25 @@ en:
modal:
close: "close"
dismiss_error: "Dismiss error"
form_kit:
reset: Reset
optional: optional
errors_summary_title: "This form contains errors:"
dirty_form: "You didn't submit your changes! Are you sure you want to leave?"
errors:
required: "Required"
invalid_url: "Must be a valid URL"
not_accepted: "Must be accepted"
not_a_number: "Must be a number"
too_high: "Must be at most %{count}"
too_low: "Must be at least %{count}"
too_long:
one: "Must be at most %{count} character"
other: "Must be at most %{count} characters"
too_short:
one: "Must be at least %{count} character"
other: "Must be at least %{count} characters"
close: "Close"
assets_changed_confirm: "This site just received a software update. Get the latest version now?"
logout: "You were logged out."
@@ -6869,6 +6888,8 @@ en:
confirm: "Yes, update password policy"
badges:
disable_system: This badge is a system badge and cannot be disabled and/or deleted.
status: Status
title: Badges
new_badge: New Badge
new: New
@@ -6876,8 +6897,8 @@ en:
badge: Badge
display_name: Display Name
description: Description
long_description: Long Description
badge_type: Badge Type
long_description: Long description
badge_type: Badge type
badge_grouping: Group
badge_groupings:
modal_title: Badge Groupings
@@ -6906,10 +6927,10 @@ en:
icon: Icon
image: Image
graphic: Graphic
icon_or_image: A badge requires an icon or an image
icon_help: "Enter a Font Awesome icon name (use prefix 'far-' for regular icons and 'fab-' for brand icons)"
image_help: "Uploading an image overrides icon field if both are set."
select_an_icon: "Select an Icon"
upload_an_image: "Upload an Image"
select_an_icon: "Select an icon"
upload_an_image: "Upload an image"
read_only_setting_help: "Customize text"
query: Badge Query (SQL)
target_posts: Query targets posts