# Text field

Source: https://material.spynejs.com/components/text-fields
Part of: Material shell gallery, Google's Material Design 3 for SpyneJS. Index: https://material.spynejs.com/llms.txt

Material's outlined text field. Any text input or textarea in an app on the template is one. In the contact form a field is an entry of `formFields`, and three keys of the entry say whether it must be filled in, whether it is disabled, and whether it has several lines.

## In an app model

A field is one entry of the contact form’s `formFields`:

```json
{
  "attrId": "reply-to",
  "attrName": "replyTo",
  "attrType": "email",
  "label": "Reply to",
  "attrPlaceholder": "you@example.com",
  "attrRequired": true
}
```

| Key of an entry of `formFields` | Means | Left out |
| --- | --- | --- |
| `attrId` | the control’s `id`; unique on the page |  |
| `attrName` | the control’s `name`: the name its value is sent under |  |
| `label` | the label’s words |  |
| `attrType` | the input’s `type`, such as `text`, `email`, `tel`, `url`, `number`; left out when `multiline` is true |  |
| `attrPlaceholder` | the placeholder |  |
| `attrRequired` | `true`: the field must be filled in | it need not be |
| `attrDisabled` | `true`: shown, but not to be used | in use |
| `multiline` | `true`: several lines, a `<textarea>` | one line, an `<input>` |

- Leave `attrRequired`, `attrDisabled` and `multiline` out when they are false.
- A disabled field takes no part in validation, so `attrRequired` on one does nothing.
- The form always has a Message field after the entries of `formFields`; it is not an entry. Its words are the form’s `messageLabel` and `attrMessagePlaceholder`.
- The whole form is the page item with `viewClass` `ContactUsView` and the template `contact-us.tmpl.html`. The From a model page writes one out in full.
- The form’s button says “Send Message”. The words are in the form’s template, and no key changes them. Its look is the form’s `button` key, beside `formFields`.
- What the form says once a message is sent is `successMessage`, in the page item’s `props`, beside `data`.

## The markup the styles need

Any `<input>` of a text kind and any `<textarea>` gets the field: its outline, and its hover, focus, error and disabled states. For the floating label and the line for an error, the control sits in a wrapper with its label before it and the error’s line after it:

```html
<div class="contact-us__field">
  <label for="reply-to">Reply to</label>
  <input
    id="reply-to"
    name="replyTo"
    type="email"
    placeholder="you@example.com"
    required
    aria-describedby="reply-to-error"
  />
  <p class="contact-us__field-error" id="reply-to-error"></p>
</div>
```

- The label floats by styles alone: it rests inside the field, and rises when the field is focused or filled. “Filled” is read from the placeholder (`:not(:placeholder-shown)`), so give every field a `placeholder`: without one a field always counts as filled, and its label stays risen.
- The error shows once the visitor has used the field or tried to send the form. Whether a field is wrong is the browser’s own checking, from the control’s `type` and `required`.
- The words of the error are the browser’s own message, copied into the line by the form’s trait.

## Where it is in the template

| File | What it holds | By name |
| --- | --- | --- |
| `src/app/traits/form/form-contact-us-traits.js` | which control an entry asks for; the form’s data as its template needs it; the error’s words | `contactUs$ControlFor`, `contactUs$ShapeData`, `contactUs$MirrorFieldError` |
| `src/app/components/page-items/templates/contact-us.tmpl.html` | the form’s markup: each control once for each case, each in a section of its own |  |
| `src/app/components/page-items/form-contact-us-view.js` | the form’s view, `ContactUsView` |  |
| `src/scss/03-components/material/_text-fields.scss` | the styles |  |

The template is public: https://github.com/spynejs/application-shell-material. An app made from it has these same files.

What it rests on in `@spynejs/grammar`: `op:conditional-via-object-section`, `op:shape-data-for-logicless-template`, `op:safeclone-for-proxified-data`, `op:live-mirror-via-el$`, `record:form-validate-submit`.

## As the page shows it

The page’s own words, in its own order, read from the page as it is drawn in the light colour scheme. They were written for someone looking at the page: “above”, “below” and “marked” mean the drawn page. A thing the page draws is named here in its place (`Button:`, `Field:`, `Switch:`), and a box that reports what the reader does is as it starts, empty. What depends on the reader’s own window is left out.

Any text input in the app is Material’s outlined text field. Where its wrapper also holds the label and a line for an error, as the contact form’s does, the label floats and the error shows under the field.

Field: Reply to

Click into the field to see the label rise. To see the error, type something that is not an address and leave the field. The words of the error are the browser’s own.

- Type: Text, **Email** (shown), Web address, Number
- Lines: **One** (shown), Several
- Required: No, **Yes** (shown)
- State: **Enabled** (shown), Disabled

### Markup the styles need

```html
<div class="contact-us__field">
  <label for="gallery-reply-to">Reply to</label>
  <input
    id="gallery-reply-to"
    name="replyTo"
    type="email"
    placeholder="you@example.com"
    required
    aria-describedby="gallery-reply-to-error"
  />
  <p class="contact-us__field-error" id="gallery-reply-to-error"></p>
</div>
```

### In the app model

```json
{
  "attrId": "gallery-reply-to",
  "attrName": "replyTo",
  "attrType": "email",
  "label": "Reply to",
  "attrPlaceholder": "you@example.com",
  "attrRequired": true
}
```

These keys are settled, and the contact form reads them. attrRequired is the Shell’s own key: true for a field that must be filled in, left out for one that need not be. attrDisabled and multiline are new. Each of the three is left out when it is false. The From a model page shows a form that uses them.
