Page MenuHomePhabricator

Add Field component to Codex
Closed, ResolvedPublic3 Estimated Story Points

Description

Background

Description

The Field component is used to collect user input in form layouts. A good Field component should be easy to scan and easy to interact with.

User stories

  • As a designer or developer I need to create forms with label, field and other information for the user such as helper text, validation messages or tooltips.

History

There was some discussion of a Field component in T293271 when we were first discussing the scope of the TextInput component. Other discussions about Required/Optional field were started in T306427.

Known use cases

Users of Codex should be able to wrap inputs and controls within forms in a component that provides a consistent experience in terms of accessibility and error feedback across all forms.

Create account.png (700×2 px, 271 KB)
Helper text and inline feedback message in Create account
Captura de Pantalla 2023-02-27 a las 11.13.03.png (1×2 px, 963 KB)
Wikifunctions
Captura de Pantalla 2023-02-27 a las 11.15.31.png (1×2 px, 390 KB)
When the user fills an error, a tooltip with a feedback message appears in user's preferences
Captura de Pantalla 2023-02-27 a las 11.17.09.png (1×2 px, 1 MB)
Label (and description) before the field (on the left) like in this example from Wikifunctions
Captura de Pantalla 2023-02-27 a las 11.21.06.png (528×1 px, 234 KB)
Required field with asterisk next to the label in Wikidata
Captura de Pantalla 2023-02-27 a las 11.22.01.png (522×1 px, 345 KB)
Required field with asterisk within the field in the Calendar widget
Captura de Pantalla 2023-02-27 a las 11.23.30.png (1×1 px, 487 KB)
Optional field and tooltip in Event creation

Existing implementations

These artifacts are listed for historical context. The figma spec, linked below, is the source of truth for the new component.

Wikimedia community:

External libraries:

  • Vuetify: Has a Form component, with some field functionality contained in form inputs/controls (e.g. labeling and validation within the TextField component)
  • Buefy: Has a Field component with label, help text, grouping, and other layout features

Codex implementation

Component task owners

Open questions

NOTE: Open questions were explored in T330419.
  • Component architecture: Do we want a Form component or a Field component, or maybe both? Could any of this be handled within the input/control components themselves via composables?
  • Required/Optional: Since all form fields are required by default, we will indicate just the optional ones in order to avoid too many asterisks across the form page. Optional text will appear next to the label and it will be included within the text when the label is multiline. It will be indicated with the whole word in order to be translated into different languages.
    Captura de Pantalla 2023-02-24 a las 11.23.32.png (1×836 px, 60 KB)
  • Tooltip: it will be placed next to the label (also when the label wraps into two lines) to be always connected with the label text.
    Captura de Pantalla 2023-03-02 a las 13.23.02.png (940×1 px, 408 KB)
  • Characters counter: it will not be implemented as part of the MVP task. It will be implemented in this other task T331000
  • Helper text Vs. Inline message: For this MVP task, we will implement the same as we have in production to avoid possible problems. So inline message will appear bellow the helper text and both texts will be visible in the Field in some cases.
  • Padding between label and field: we will use 4px padding between label, field and helper text.
  • Description text: The description will be implemented as part of the MVP and we will provide guidelines to indicate when the designers should use the description text and when should they use other field elements such as helper text or a tooltip.
    Captura de Pantalla 2023-03-02 a las 13.32.10.png (652×2 px, 503 KB)
  • Field action: Inline or stacked action could be displayed as part of the Field component. So we will implement them as properties.
    Captura de Pantalla 2023-03-02 a las 13.57.08.png (858×1 px, 253 KB)
  • Label placement: We will implement the label on top for the MVP task. The option with the label on the left will be implemented in future iterations just if it's really needed in the product.
    Captura de Pantalla 2023-03-10 a las 10.31.24.png (792×2 px, 449 KB)
  • Stacked fields vs. FieldSet: We will implement both the Field component (in this task) and the FieldSet (a combination of different Field components, this one will be implemented in another task).

Design spec

Anatomy
  • Label style will be Bold as default and it could be customized to Regular. Regular will be used in field layouts where a combination of fields is grouped.
  • Label section could display the following optional properties:
    • Start icon
    • Optional indicator when the form field is not required
    • Tooltip. It will be created with a small 24px icon-only quiet button.
  • Additional information could be added in the field using the following optional properties:
    • Description text that could contain a link
    • Helper text that could contain a link
  • Inline action. The field component can contain an action that will affect the entire component, such as remove.
  • Validation message. An InlineMessage will appear to provide feedback related to the field when warning, error or success.
  • Field item can be replaced with any form item (such as text input, select, file input, etc.) or group (such as checkbox group, radio group or toggle switch group)
Style
  • Label will be Bold as default and will use color-base
  • Optional indicator will be Regular and color-subtle
  • Description will be Regular and color-subtle
  • Helper text will be Regular and color-subtle
  • Padding between label section, field and helper text will be 4px on desktop and 8px on mobile
Interaction

The following states will be implemented:

  • Default
  • Hover, Active-Focus (just on field item)
  • Read-only
  • Disabled
  • Loading (when we implement skeleton T311874)
  • Filled
  • Warning (the warning inline message will be displayed just when filled)
  • Success (the warning inline message will be displayed just when filled)
  • Error default (if the field is required and the user doesn't fill it, an error message will appear indicating that this field is mandatory)
  • Error focus
  • Error filled (an error message will appear indicating to the user how to fix the error)
Documentation

The configurable demo should include:

  • Label + Field (text input) + Helper text will be displayed by default in the configurable demo
  • Configurable properties:
    • startIcon: the user will be able to type in a text input the icon they want to display
    • optional field
    • tooltip: the user will be able to type the text they want to display in the tooltip when hover/select it
    • description: the user will be able to type in a text input the text they want to display in the demo
    • helper text: the user will be able to type in a text input the text they want to display in the demo
    • status: the user will select with radios the different status (warning, error or success) and an inline message will appear below the field
    • disabled: the user will be able to select the disabled state with a toggle switch
    • Reading direction: LTR/RTL will be selected with radios

Other standalone demos could include:

  • A field component displaying the description with a link within the text
  • A field component displaying the helper text with a link within the text
  • A field component displaying another form item that is not a text input (e.g. a select)
  • A field component displaying a group of form items (e.g. a checkbox group)
  • A field component displaying an inline action that affects the entire field (e.g. remove)

Acceptance criteria

Minimum viable product

This task covers the minimum viable product (MVP) version of this component. MVP includes basic layout, default states, and most important functionality.

MVP scope

  • A baseline set of components is supported for use within Field (Checkbox, Combobox, Lookup, Radio, SearchInput, Select, TextInput, ToggleSwitch)
  • Single inputs or groups of inputs are supported
  • <label> element (or <legend> for fieldsets) that is paired with an input or control component in a consistent way. See T309246 for MVP scope of the Label component. Description and optional flag are included here.
  • Helper text
  • Validation message (error only)
  • Demos with various inputs (TextInput, Radio group, and other groups of inputs)

Design

  • Design the Figma spec sheet and add a link to it in this task
  • Update the component in the Figma library. This step will be done by a DST member.

Code

  • Implement the component in Codex

Future work

  • Add field action (T338801)
  • Add tooltip (actually part of Label) (T338282)
  • Support warning and success messages (T338802)
  • Support other components within field if needed (possibly ToggleButton, ButtonGroup, ToggleButtonGroup)
  • Add Field's loading state (T339074)

Related Objects

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

After reviewing the Field component yesterday during our Engineering/Design sync and presenting the proposals today with the designers where I collected important feedback, we've decided the following for the MVP task:

Required/Optional:
  • Asterisk can not be used to indicate the required label since its not enough translatable to other languages. If we decide to indicate the required one, it should be indicated with the whole word (not with asterisk). Also, asterisk shouldn’t be indicated within the field since it’s not applicable to Selects or Comboboxes.
  • Since all form fields are required by default, we could indicate just the optional ones in order to avoid too many asterisks across the form page.
  • @KieranMcCann will finish to define this in T330419
Tooltip:

It will be added next to the label (also when label text wraps into more than one line) so the tooltip is always connected with the label.

Helper text Vs. Inline message:

For this MVP task, we will implement the same as we have in production to avoid possible problems. So inline message will appear bellow the helper text and both texts will be visible in the Field in some cases.
Since both helper and inline message will be visible at the same time, what if we redesign the Inline Message from Bold to Regular and we use a 16px icon instead (Op.2 B)? cc: @KieranMcCann

Characters counter:

It will not be implemented as part of this MVP task and we will implement it in this separate task T331000.

Label + Description:

The description will be implemented as part of the MVP and we will provide guidelines to indicate when the designers should use the description text and when should they use other field elements such as helper text or a tooltip.

Field action:

Inline or stacked action could be displayed as part of the Field component. So we will implement them as properties.

Stacked fields vs. FieldSet:

We will implement both the Field component (in this task) and the FieldSet (a combination of different Field components, this one will be implemented in another task).

Since we the design explorations were solved in T330419 and we made some decisions on implementation during our last Engineering/Design sync, I'm moving this task to the sprint to start working on the Figma spec sheet.

bmartinezcalvo renamed this task from Add form/field functionality to Codex form inputs and controls to Add Field component to Codex.Mar 20 2023, 2:37 PM

I've created the Field component's spec sheet and it's pending from @KieranMcCann review. I need your review in the following:

  1. Generic visual review of the component and the spec sheet recommendations.
  2. Mobile paddings and styles. Since mobile components use 16px base font, I've updated the styles in the mobile version of the Field, so let me know if you agree (I left you a comment in Figma about it).
  3. I used the layout spec on the left to provide some guidelines about placing the field components in a form page and the padding we should use between form item rows on each device. I've used 40px for desktop and tablet and 24px for mobile. Let me know what you think.

Thanks @bmartinezcalvo. Following on from my comments in the Figma file I can confirm all looks good to me now.

Thanks @bmartinezcalvo. Following on from my comments in the Figma file I can confirm all looks good to me now.

@KieranMcCann great thanks. @RHo for visibility in case you want to do a last check before moving the task to Ready for development.

Thanks @bmartinezcalvo. Following on from my comments in the Figma file I can confirm all looks good to me now.

@KieranMcCann great thanks. @RHo for visibility in case you want to do a last check before moving the task to Ready for development.

Thanks, LGTM too

Change 893011 abandoned by Anne Tomasevich:

[design/codex@main] [proof of concept] Demo Field functionality within input components

Reason:

https://gerrit.wikimedia.org/r/893011

Change 893010 abandoned by Anne Tomasevich:

[design/codex@main] [proof of concept] Demonstrate experimental Field component

Reason:

https://gerrit.wikimedia.org/r/893010

AnneT changed the task status from Open to In Progress.May 22 2023, 5:57 PM
AnneT claimed this task.

Change 923428 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] [wip do not merge] Field and Label

https://gerrit.wikimedia.org/r/923428

Change 927265 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] Field: Add Field component and enable use with input components

https://gerrit.wikimedia.org/r/927265

Change 927266 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] Field et al: Add demos for supported components

https://gerrit.wikimedia.org/r/927266

@AnneT I'm checking the Field last patch and it seems there is an error to fix with the error state. The helper text should also reflect the error state so it should be content-error color. There was an error in the spec so I've updated it. Could we also update it in the demo? These are the styles we should use in the error. Thank you!

Captura de pantalla 2023-06-06 a las 16.42.25.png (300×2 px, 40 KB)

Change 923428 abandoned by Anne Tomasevich:

[design/codex@main] [wip do not merge] Field and Label

Reason:

Real patches have been opened

https://gerrit.wikimedia.org/r/923428

@bmartinezcalvo Thanks for checking out the demos! You can also see a real-world demo for each component on the demo site for the last patch - e.g. Checkbox.

We're still allowing people to add both helper text and a validation message, right? If so, I would recommend we not change the helper text to red when there is an error. If the helper text turns red when there's an error, that would mean that the helper text must be related to the error, and I think there are many other things people might want to include in the helper text besides information on exactly how to fill out the field to avoid an error. Is the red error validation message enough here?

@AnneT I'm checking the Field last patch and it seems there is an error to fix with the error state. The helper text should also reflect the error state so it should be content-error color. There was an error in the spec so I've updated it. Could we also update it in the demo? These are the styles we should use in the error. Thank you!

Captura de pantalla 2023-06-06 a las 16.42.25.png (300×2 px, 40 KB)

@bmartinezcalvo Thanks for checking out the demos! You can also see a real-world demo for each component on the demo site for the last patch - e.g. Checkbox.

We're still allowing people to add both helper text and a validation message, right? If so, I would recommend we not change the helper text to red when there is an error. If the helper text turns red when there's an error, that would mean that the helper text must be related to the error, and I think there are many other things people might want to include in the helper text besides information on exactly how to fill out the field to avoid an error. Is the red error validation message enough here?

Hi @bmartinezcalvo - my understanding is the same as @AnneT in that that validation/error text would be separated out from Helper text, as captured in T330419

@bmartinezcalvo Thanks for checking out the demos! You can also see a real-world demo for each component on the demo site for the last patch - e.g. Checkbox.

We're still allowing people to add both helper text and a validation message, right? If so, I would recommend we not change the helper text to red when there is an error. If the helper text turns red when there's an error, that would mean that the helper text must be related to the error, and I think there are many other things people might want to include in the helper text besides information on exactly how to fill out the field to avoid an error. Is the red error validation message enough here?

@AnneT oh yes, I forgot about the validation message when the error. So in this case, if the helper text will be the same when error, we should display the error validation message always we have an error state. This should be the error validation behavior:

Captura de pantalla 2023-06-08 a las 20.26.28.png (380×2 px, 56 KB)

Change 927265 merged by jenkins-bot:

[design/codex@main] Field: Add WIP Field component and enable use with input components

https://gerrit.wikimedia.org/r/927265

Status update: The WIP component has been merged and can be viewed here.

It will need design review before it can come out of WIP. I've opened tasks for things that I believe do not need to block taking this component out of WIP. We can determine priority for each task and tackle any of them now, if we think they are critical for an MVP release of Field. See the "future work" section at the bottom of the task description.

cc @CCiufo-WMF @bmartinezcalvo

@AnneT design sign-off done and adding small things to review:

  1. Helper text should be 16/22 so it means the line height should be @line-height-small.
  2. When error, an error inline validation message should appear below the helper text. I think this should appear always since the user needs the reason and instructions to fix the error. So I would include it as default in the configurable demo too.
  3. Complex field with two inputs: the toggle switch is too closed to the fields, could we add more padding? Maybe 40px or 48px.
  4. Error validation message should disappear when focus, since error state disappears when focus.
  5. The keyboard navigation for the links within the helper text and descriptions seems not work. When clicking enter or space, it should navigate to the link.

@AnneT since we are adding the FieldSet with nested fields in the same Field component's demo, I should add it in Figma too. How many Fields could we add in a FieldSet row? The same for the Complex field with two inputs, could this complex fields be more than 2 inputs?

Change 929412 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] Field: Set help text line height and improve demos

https://gerrit.wikimedia.org/r/929412

Thanks for the feedback, @bmartinezcalvo!

  1. Helper text should be 16/22 so it means the line height should be @line-height-small.

Done!

  1. When error, an error inline validation message should appear below the helper text. I think this should appear always since the user needs the reason and instructions to fix the error. So I would include it as default in the configurable demo too.

Good call; I added an error message to the configurable demo which will display when you select the "error" status. We still don't support object-type props in the configurable demos, which means we can't include the messages prop since this is an object. However, I added a note above the configurable demo pointing to the demo with a validation message and status, which will show people exactly how to add an error message.

  1. Complex field with two inputs: the toggle switch is too closed to the fields, could we add more padding? Maybe 40px or 48px.

I changed this to 40px, let me know what you think (demo here)!

  1. Error validation message should disappear when focus, since error state disappears when focus.

I worry that this would result in 2 issues:

  1. People might want to read the error message text as they're updating the field to fix the error
  2. The error message would disappear and reappear if the user clicked in and out of the input

With the status and error message, we are requiring developer users to determine what the status is at all times and when to show a message. So, a user could set this up so that the status resets to "default" when the input is focused. But I think this will need to be handled differently across use cases, so I would recommend we keep things the way they are and just allow designer and developer users to choose when to show the error message.

  1. The keyboard navigation for the links within the helper text and descriptions seems not work. When clicking enter or space, it should navigate to the link.

This was because they weren't real links, just a link to the current page - I thought this would be better because I'm guessing users won't want to be navigated away to a new page, but it really just makes the demos less realistic. I've changed them to be real link so that they work as expected.

In Chrome and Firefox at least, these links can now be visited with the Enter key, but not space - these browsers always do a page down on space, not activating a link.

@AnneT since we are adding the FieldSet with nested fields in the same Field component's demo, I should add it in Figma too. How many Fields could we add in a FieldSet row? The same for the Complex field with two inputs, could this complex fields be more than 2 inputs?

Technically, people can add as many inputs as they want in a fieldset, and the layout is up to them. We have not implemented any kind of fieldset layout styles in the Field component - all the layout styles you're seeing in those two demos are written specifically for those demos.

Maybe a good future task would be to support a set of layouts, e.g. 2 adjacent inputs with no space between then, 2 columns (like for an address field), etc.? Until then, perhaps we should just add some examples of acceptable layouts in Figma and provide guidelines for how to style fieldsets?

Change 929412 merged by jenkins-bot:

[design/codex@main] Field: Set help text line height and improve demos

https://gerrit.wikimedia.org/r/929412

Thanks for the feedback, @bmartinezcalvo!

  1. Helper text should be 16/22 so it means the line height should be @line-height-small.

Done!

@AnneT it still appears with 16/25.6. It should be 16/22 instead.

Captura de pantalla 2023-06-13 a las 9.55.20.png (600×1 px, 84 KB)

  1. When error, an error inline validation message should appear below the helper text. I think this should appear always since the user needs the reason and instructions to fix the error. So I would include it as default in the configurable demo too.

Good call; I added an error message to the configurable demo which will display when you select the "error" status. We still don't support object-type props in the configurable demos, which means we can't include the messages prop since this is an object. However, I added a note above the configurable demo pointing to the demo with a validation message and status, which will show people exactly how to add an error message.

Great, thank you!

  1. Complex field with two inputs: the toggle switch is too closed to the fields, could we add more padding? Maybe 40px or 48px.

I changed this to 40px, let me know what you think (demo here)!

It looks perfect now.

  1. Error validation message should disappear when focus, since error state disappears when focus.

I worry that this would result in 2 issues:

  1. People might want to read the error message text as they're updating the field to fix the error
  2. The error message would disappear and reappear if the user clicked in and out of the input

With the status and error message, we are requiring developer users to determine what the status is at all times and when to show a message. So, a user could set this up so that the status resets to "default" when the input is focused. But I think this will need to be handled differently across use cases, so I would recommend we keep things the way they are and just allow designer and developer users to choose when to show the error message.

Ok, so I've also included the error inline message in the focus state in the Figma spec.

  1. The keyboard navigation for the links within the helper text and descriptions seems not work. When clicking enter or space, it should navigate to the link.

This was because they weren't real links, just a link to the current page - I thought this would be better because I'm guessing users won't want to be navigated away to a new page, but it really just makes the demos less realistic. I've changed them to be real link so that they work as expected.

In Chrome and Firefox at least, these links can now be visited with the Enter key, but not space - these browsers always do a page down on space, not activating a link.

So this means the space just activates the links in Safari browser?

@AnneT since we are adding the FieldSet with nested fields in the same Field component's demo, I should add it in Figma too. How many Fields could we add in a FieldSet row? The same for the Complex field with two inputs, could this complex fields be more than 2 inputs?

Technically, people can add as many inputs as they want in a fieldset, and the layout is up to them. We have not implemented any kind of fieldset layout styles in the Field component - all the layout styles you're seeing in those two demos are written specifically for those demos.

Maybe a good future task would be to support a set of layouts, e.g. 2 adjacent inputs with no space between then, 2 columns (like for an address field), etc.? Until then, perhaps we should just add some examples of acceptable layouts in Figma and provide guidelines for how to style fieldsets?

Ok, I will create a task for these FieldSet layouts and I will add some examples in Figma as we have in the Codex demo.

Status update: The WIP component has been merged and can be viewed here.

It will need design review before it can come out of WIP. I've opened tasks for things that I believe do not need to block taking this component out of WIP. We can determine priority for each task and tackle any of them now, if we think they are critical for an MVP release of Field. See the "future work" section at the bottom of the task description.

cc @CCiufo-WMF @bmartinezcalvo

@AnneT I wonder if we should create another task to include the loading state once Skeleton T311874 is implemented.

Change 929722 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] Field, Label: Set smaller line height

https://gerrit.wikimedia.org/r/929722

So this means the space just activates the links in Safari browser?

I think it depends on your personal settings for Safari? The space key doesn't click links in my local version.

@AnneT I wonder if we should create another task to include the loading state once Skeleton T311874 is implemented.

Creating a task for this sounds good to me!

@AnneT I'm checking the last patch and the text line height is the right one now @line-height-xx-small. All looks good now so moving this task to Pending Release.

I will create a new task for the Loading state and I'm removing the space from the keyboard navigation table in the Figma spec to avoid confusions.

Regarding Fieldset, I've added some examples of Fieldset in the Figma spec. And, since we already have some examples of Fieldset in the current Field demo, I guess we will not need to create a new task for it.

Captura de pantalla 2023-06-13 a las 20.21.57.png (584×2 px, 113 KB)

Change 929722 merged by jenkins-bot:

[design/codex@main] Field, Label: Set smaller line height

https://gerrit.wikimedia.org/r/929722

Change 929794 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] Field, Label: Move from WIP components to lib

https://gerrit.wikimedia.org/r/929794

Change 929794 merged by jenkins-bot:

[design/codex@main] Field, Label: Move from WIP components to lib

https://gerrit.wikimedia.org/r/929794

Change 927266 merged by jenkins-bot:

[design/codex@main] Field et al: Add demos for supported components

https://gerrit.wikimedia.org/r/927266

Change 931666 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] Update Codex from v0.12.0 to v0.13.0

https://gerrit.wikimedia.org/r/931666

Test wiki created on Patch demo by ATomasevich (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/2c8b23bc31/w

Change 931666 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.12.0 to v0.13.0

https://gerrit.wikimedia.org/r/931666

Test wiki on Patch demo by ATomasevich (WMF) using patch(es) linked to this task was deleted:

https://patchdemo.wmflabs.org/wikis/2c8b23bc31/w/