Forms

sds-field#

One line of whatever a reader types. It has two shapes, and caption is the difference. An answer of more than one line is sds-textarea, and a list of answers is sds-select. Both share this box and little else.

<sds-field caption="Your email" field-id="email" name="email"
  type="email" hint="Used for the reply and for nothing else."
  required></sds-field>

<sds-field icon="actions-search" value="Filter tools"
  label="Filter tools" min-width="260"></sds-field>

sds-textarea#

An answer of more than one line: a real <textarea> in the field's own box. Its own element, not a taller field. It shares the box with a text field, and nothing a caller writes.

<sds-textarea caption="What did the tool answer?" field-id="message"
  name="message" rows="6" required
  hint="The tool name and the question are enough to reproduce it."
></sds-textarea>

sds-select#

One answer out of a list the reader does not need to see. Its own element, not a shape a field takes. A select and a text field share a box and nothing else. A select has a list, with headings, and entries on it but not on offer. It has nothing to type, no length, no pattern, no keyboard to choose.

The element draws the list, and it is the one place this system rebuilds a native control. A browser's own list opens in a window the page has no reach into, in the operating system's colours. So a dark page opens a light list, and the headings of a grouped one come out in a grey nobody chose.

The cost is everything the platform did, and the element puts all of it back by hand. role="combobox" over role="listbox", the arrows, Home and End, type-ahead, Enter and Escape. And aria-activedescendant, so the focus stays on the button. The list is a popover, so the top layer holds it. No ancestor's overflow clips it, and a press outside is the platform's own dismissal.

The real <select> stays underneath and carries the value. It is what the form submits, and the whole control on a page with no script. The drawn list hides until the element upgrades. After that, the native control leaves the reading and the tab order. Its required moves to the element's own validity, reported on the visible button.

<sds-select caption="Which release is this about?" field-id="release"
  name="release" value="13.4" filled
  .options="${[{ label: '14.3', group: 'Supported' },
               { label: '13.4', group: 'Supported' },
               { label: '11.5', group: 'Out of support', disabled: true }]}"
></sds-select>

sds-field-group#

A control and what stands with it, as one thing. A field, a row of actions and a hint each owe no step of their own. A container or a set spaces them, so loose on a page they touch. The group is the set that pays: the normal step between its parts, and the flow step around itself.

<sds-field-group>
  <sds-field icon="actions-search" value="Search 392 glyphs"
    label="Search the glyph set" min-width="420"></sds-field>
  <div class="sds-actions">
    <sds-button variant="primary">Browse all 392</sds-button>
  </div>
</sds-field-group>

Use it where a control is what a page is for: a search hero, a finder above the wall it filters. Inside a form nothing changes. A field with a caption already renders the row a form owes it, and sds-form holds the column.

sds-field-error#

The message under an invalid field, with its own glyph, because colour alone is not a message.

<sds-field-error message="An address needs an @ in it."></sds-field-error>

An element of its own, not a slot on the field. Whatever validated the value often writes the error, and that is not always what drew the box. sds-field renders one for you with error.

It has the size of the control, not of a hint, and it follows a compact control down the way that control's label does. The sentence stands between a reader and the send, and the form's summary says the same one in the reading register.

sds-checkbox#

One thing that is either so or not. The platform's own control in this system's colours, not a box with a glyph in it.

<sds-checkbox name="digest" value="weekly" label="Send me the weekly digest"
  hint="One message, on Fridays. Unsubscribe from any of them."></sds-checkbox>

A real <label> wraps both, so the words are part of the target. A 16px box is hard to hit, and the sentence beside it is not.

sds-checkbox-group#

Tick any of these, under one question. sds-checkbox is one fact on its own; this is the other shape a set of boxes takes. As loose checkboxes it is a heading above some rows. Nothing binds them, so nothing reads them out as one question either.

The set is the component, as for sds-radio. The legend, the shared name and the ticked entries are three things a caller otherwise keeps in step by hand.

<sds-checkbox-group legend="What may we attach?" name="scope"
  .values="${['versions']}"
  .choices="${[{ label: 'Installed versions', value: 'versions' },
               { label: 'File contents', value: 'files',
                 hint: 'Not on offer while the project is public.',
                 disabled: true }]}"
></sds-checkbox-group>

sds-switch#

A setting that takes effect where it stands.

A checkbox answers a question the form asks, and the submit sends it. A switch turns something on now. That is the whole difference, and why the two look nothing alike. A reader who has to press Save after a flip got the wrong message from the control.

<sds-switch name="theme" label="Follow the system theme" checked></sds-switch>

sds-range#

A value along a run of them. For a quantity where the position is the answer and the exact number is not: a zoom, a weight, a threshold. Where the reader knows the number, that is a field with type="number", which takes typed and pasted input.

<sds-range caption="Preview width" field-id="w" name="w"
  min="320" max="1440" step="10" value="960" unit="px"></sds-range>

sds-file#

The one native control that looks like nothing else on a page. A file input is a button and a sentence the browser draws itself, and the picker opens only for a press on a real one. So the real one stays, and ::file-selector-button paints its button. The sentence beside it is the browser's, in its own language, and names the chosen file.

<sds-file caption="Attach a screenshot" field-id="shot" name="shot"
  accept="image/*" hint="PNG or JPEG, up to 5 MB."></sds-file>

sds-radio#

One answer out of a few, all visible. The set is the component, and a single button is not. What makes one a choice is the set it belongs to, the shared name, and that exactly one holds.

<sds-radio legend="How should we reply?" name="reply" value="email"
  .choices="${[{ label: 'By email', value: 'email' },
               { label: 'In the issue', value: 'issue',
                 hint: 'Public, and the thread stays with the code.' }]}"
></sds-radio>

sds-form-errors#

What stopped the form, at the top of it.

<sds-form-errors announce
  .errors="${[{ message: 'The message is empty', for: 'message' }]}"
></sds-form-errors>

A mark on the boxes is enough for a reader who sees the whole form at once, and nothing for one who does not. A phone comes back to a page that looks the same, and a screen reader hears nothing. So the summary is where the reader lands: first, focusable, announced, and every line a link to its field.

It renders sds-note instead of a second error block. What a failure looks like has one decision.

Sent, and reset#

Two behaviours to know before you assemble a form out of these.

A button in a form is not a submit unless it says so. sds-button defaults to type="button" for that reason; see Controls. Give the one button that sends the form type="submit". Enter in a text field then submits too, and only that button carries it.

A reset puts back what the markup said. Every control here keeps the state of the page's first draw and restores it on a reset of the form. Not the last click, which a mirror of the live state into the attribute restores.

The form knows the elements themselves. Each one is form-associated through ElementInternals, which makes it a member of the form, not a box with a control in it. Four things follow that a hand-rolled control never gets right:

What internals do not carry, on purpose, is the value. Every control here renders a real named <input>, <select> or <textarea> into the light DOM, and the browser submits that. That holds on a prerendered page with no script. A setFormValue as well sends every answer twice.