DEV: form-kit improvements (#27966)

- correctly support @title on fields
- correctly support @subtitle on fields
- improves error message when a field name is incorrect in assertions

app/assets/javascripts/discourse/app/form-kit/components/fk/control-wrapper.gjs

@@ -94,7 +94,7 @@ export default class FKControlWrapper extends Component {
         </@component>
 
         <FKMeta
-          @description={{@description}}
+          @description={{@field.description}}
           @value={{@value}}
           @field={{@field}}
           @error={{this.error}}

app/assets/javascripts/discourse/app/form-kit/components/fk/field.gjs

@@ -48,6 +48,8 @@ export default class FKField extends Component {
     this.field = this.args.registerField(this.name, {
       triggerRevalidationFor: this.args.triggerRevalidationFor,
       title: this.args.title,
+      subtitle: this.args.subtitle,
+      description: this.args.description,
       showTitle: this.args.showTitle,
       collectionIndex: this.args.collectionIndex,
       set: this.args.set,

app/assets/javascripts/discourse/app/form-kit/lib/fk-field-data.js

@@ -34,6 +34,8 @@ export default class FKFieldData {
    * @param {boolean} [options.disabled=false] - Indicates if the field is disabled.
    * @param {Function} [options.validate] - The custom validation function.
    * @param {Function} [options.title] - The custom field title.
+   * @param {Function} [options.subtitle] - The custom field subtitle.
+   * @param {Function} [options.description] - The custom field description.
    * @param {Function} [options.showTitle=true] - Indicates if the field title should be shown.
    * @param {Function} [options.triggerRevalidationFor] - The function to trigger revalidation.
    * @param {Function} [options.addError] - The function to add an error message.
@@ -47,6 +49,8 @@ export default class FKFieldData {
       disabled = false,
       validate,
       title,
+      subtitle,
+      description,
       showTitle = true,
       triggerRevalidationFor,
       collectionIndex,
@@ -55,6 +59,8 @@ export default class FKFieldData {
   ) {
     this.name = name;
     this.title = title;
+    this.subtitle = subtitle;
+    this.description = description;
     this.collectionIndex = collectionIndex;
     this.addError = addError;
     this.showTitle = showTitle;

app/assets/javascripts/discourse/tests/helpers/form-kit-assertions.js

@@ -3,12 +3,17 @@ import QUnit from "qunit";
 import { query } from "discourse/tests/helpers/qunit-helpers";
 
 class FieldHelper {
-  constructor(element, context) {
+  constructor(element, context, name) {
     this.element = element;
+    this.name = name;
     this.context = context;
   }
 
   get value() {
+    this.context
+      .dom(this.element)
+      .exists(`Could not find element (name: ${this.name}).`);
+
     switch (this.element.dataset.controlType) {
       case "image": {
         return this.element
@@ -70,9 +75,25 @@ class FieldHelper {
   }
 
   get isDisabled() {
+    this.context
+      .dom(this.element)
+      .exists(`Could not find field (name: ${this.name}).`);
+
     return this.element.dataset.disabled === "";
   }
 
+  hasSubtitle(subtitle, message) {
+    this.context
+      .dom(this.element.querySelector(".form-kit__container-subtitle"))
+      .hasText(subtitle, message);
+  }
+
+  hasDescription(description, message) {
+    this.context
+      .dom(this.element.querySelector(".form-kit__meta-description"))
+      .hasText(description, message);
+  }
+
   hasCharCounter(current, max, message) {
     this.context
       .dom(this.element.querySelector(".form-kit__char-counter"))
@@ -129,7 +150,8 @@ class FormHelper {
   field(name) {
     return new FieldHelper(
       query(`.form-kit__field[data-name="${name}"]`, this.element),
-      this.context
+      this.context,
+      name
     );
   }
 }
@@ -151,6 +173,12 @@ export function setupFormKitAssertions() {
           doesNotExist: (message) => {
             field.doesNotExist(message);
           },
+          hasSubtitle: (value, message) => {
+            field.hasSubtitle(value, message);
+          },
+          hasDescription: (value, message) => {
+            field.hasDescription(value, message);
+          },
           exists: (message) => {
             field.exists(message);
           },

app/assets/javascripts/discourse/tests/integration/components/form-kit/field-test.gjs

@@ -35,6 +35,30 @@ module("Integration | Component | FormKit | Field", function (hooks) {
     assert.dom(".form-kit__row .form-kit__col.--col-8").hasText("Test");
   });
 
+  test("@subtitle", async function (assert) {
+    await render(<template>
+      <Form as |form|>
+        <form.Field @name="foo" @title="Foo" @subtitle="foo foo" as |field|>
+          <field.Input />
+        </form.Field>
+      </Form>
+    </template>);
+
+    assert.form().field("foo").hasSubtitle("foo foo");
+  });
+
+  test("@description", async function (assert) {
+    await render(<template>
+      <Form as |form|>
+        <form.Field @name="foo" @title="Foo" @description="foo foo" as |field|>
+          <field.Input />
+        </form.Field>
+      </Form>
+    </template>);
+
+    assert.form().field("foo").hasDescription("foo foo");
+  });
+
   test("invalid @name", async function (assert) {
     setupOnerror((error) => {
       assert.deepEqual(error.message, "@name can't include `.` or `-`.");

plugins/styleguide/assets/javascripts/discourse/components/sections/atoms/05-forms.hbs

@@ -16,7 +16,13 @@
     <form.Field @title="Before" @name="before" as |field|>
       <field.Input @before="https://" />
     </form.Field>
-    <form.Field @title="Secret" @name="secret" as |field|>
+    <form.Field
+      @title="Secret"
+      @subtitle="Another secret"
+      @name="secret"
+      @description="An important password"
+      as |field|
+    >
       <field.Password />
     </form.Field>
   </Form>