@warp-ds/elements 2.9.0-next.4 → 2.9.0-next.6

package/dist/docs/textfield/textfield.md

@@ -2,142 +2,360 @@
 
 ## Description
 
-A single line text input element.
-
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-textfield--docs)
+A single-line input component used for entering and editing textual or numeric data.
 
 ## Usage
 
+<style-isolate>
+    <w-textfield label="Email" type="email"></w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Email" type="email"></w-textfield>
+```
+
+### Validation
+
+Set the `invalid` attribute to display a textfield as invalid.
+
+`invalid` should be paired with `help-text` to provide feedback to the user about how to correct the error.
+
+<style-isolate>
+    <w-textfield 
+        label="Email"
+        invalid
+        help-text="An email should have an @ sign and a domain name, for example ola.nordmann@finn.no"
+    ></w-textfield>
+</style-isolate>
+
+```html
+<w-textfield 
+    label="Email"
+    invalid
+    help-text="An email should have an @ sign and a domain name, for example ola.nordmann@finn.no"
+></w-textfield>
+```
+
 ## Accessibility
 
+If a visible label isn't specified, an `aria-label` must be provided to the text field for accessibility. If the field is labeled by a separate element, an `aria-labelledby` property must be provided using the `id` of the labeling element instead.
+
+- Always provide a visible label (do not rely on `placeholder` alone).
+- Do not rely on color alone for interaction feedback (e.g. error states).
+- Interaction patterns should follow platform-native expectations (e.g. tap zones, keyboard navigation, etc) and must not block accessibility tools.
+
+### When used with an affix
+
+When `search` or `clear` set on the [affix](#with-affix) component it renders a button and a default `aria-label`. If the `aria-label` incorrect for your context, you may provide your own describing the action.
+
+```html
+<w-affix search aria-label="Ad Search"></w-affix>
+<w-affix clear aria-label="Clear text input"></w-affix>
+```
+
 ## Examples
 
+### Placeholder
+
+Placeholder text can be used to describe the expected value or formatting for the textfield.
+
+Placeholder text will only appear when the textfield is empty, and must not be used as a
+substitute for labeling the element with a visible label.
+
+<style-isolate>
+    <w-textfield label="Email" placeholder="ola.nordmann@finn.no"></w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Email" placeholder="ola.nordmann@finn.no"></w-textfield>
+```
+
+### Prefix label
+
+<style-isolate>
+  <w-textfield label="Price">
+    <w-affix slot="prefix" label="kr"></w-affix>
+  </w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Price">
+  <w-affix slot="prefix" label="kr"></w-affix>
+</w-textfield>
+```
+
+### Suffix Label
+
+<style-isolate>
+  <w-textfield label="Price">
+    <w-affix slot="suffix" label="kr"></w-affix>
+  </w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Price">
+  <w-affix slot="suffix" label="kr"></w-affix>
+</w-textfield>
+```
+
+### Prefix Search Icon
+
+<style-isolate>
+  <w-textfield label="Search">
+    <w-affix slot="prefix" search></w-affix>
+  </w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Search">
+  <w-affix slot="prefix" search></w-affix>
+</w-textfield>
+```
+
+### Suffix Search Icon
+
+If you wrap the textfield with affix in a form element, clicking the search button will automatically submit the form
+
+<style-isolate>
+  <form>
+    <w-textfield label="Search">
+      <w-affix slot="suffix" search></w-affix>
+    </w-textfield>
+  </form>
+</style-isolate>
+
+```html
+<form>
+  <w-textfield label="Search">
+    <w-affix slot="prefix" search></w-affix>
+  </w-textfield>
+</form>
+```
+
+### Suffix Clear Icon
+
+Clicking the clear button will reset the textfield
+
+<style-isolate>
+  <w-textfield label="Search input">
+    <w-affix slot="suffix" clear></w-affix>
+  </w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Search input">
+  <w-affix slot="suffix" clear></w-affix>
+</w-textfield>
+```
+
+### Affix with arbitrary icon
+
+<style-isolate>
+  <w-textfield label="Award">
+    <w-affix slot="prefix" icon="AwardMedal"></w-affix>
+  </w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Award">
+  <w-affix slot="prefix" icon="AwardMedal"></w-affix>
+</w-textfield>
+```
+
+### Disabled
+
+Keep in mind that using disabled in its current form is an anti-pattern.
+
+There will always be users who don't understand why an element is disabled, or users who can't even see that
+it is disabled because of poor lighting conditions or other reasons.
+
+Please consider more informative alternatives before choosing to use disabled on an element.
+
+<style-isolate>
+    <div class="flex flex-col space-y-32">
+        <w-textfield label="Email" disabled value="ola.nordmann@finn.no"></w-textfield>
+        <w-textfield label="Email" disabled></w-textfield>
+    </div>
+</style-isolate>
+
+```html
+<div class="flex flex-col space-y-32">
+  <w-textfield label="Email" disabled value="ola.nordmann@finn.no"></w-textfield>
+  <w-textfield label="Email" disabled></w-textfield>
+</div>
+```
+
+### Read only
+
+The readonly boolean attribute makes the w-textfield's text content immutable. Unlike disabled the w-textfield remains focusable and the contents can still be copied. See [MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/readOnly) for more information.
+
+<style-isolate>
+  <w-textfield label="Email" type="email" value="ola.nordmann@finn.no" readonly></w-textfield>
+</style-isolate>
+
+```html
+<w-textfield 
+  label="Email" 
+  type="email" 
+  value="ola.nordmann@finn.no" 
+  readonly
+></w-textfield>
+```
+
 ## API Documentation
 
 ### Properties
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| shadowRootOptions | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
-| disabled | `boolean` | `false` | - |
-| invalid | `boolean` | `false` | - |
-| id | `string` | `-` | - |
-| label | `string` | `-` | - |
-| helpText | `string` | `-` | - |
-| size | `string` | `-` | - |
-| max | `number` | `-` | - |
-| min | `number` | `-` | - |
-| minLength | `number` | `-` | - |
-| maxLength | `number` | `-` | - |
-| pattern | `string` | `-` | - |
-| placeholder | `string` | `-` | - |
-| readOnly | `boolean` | `false` | - |
-| readonly | `boolean` | `false` | - |
-| required | `boolean` | `false` | - |
-| type | `string` | `-` | - |
-| value | `string` | `-` | - |
-| name | `string` | `-` | - |
-| step | `number` | `-` | - |
-| autocomplete | `string | undefined` | `-` | - |
-| formatter | `(value: string) => string` | `-` | - |
-| _hasPrefix | `unknown` | `-` | - |
-| _hasSuffix | `unknown` | `-` | - |
+| autocomplete | `string \| undefined` | `-` | A space-separated string that hints to browsers [what type of content it can suggest](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#value) to autofill. |
+| disabled | `boolean` | `false` | Makes the element not focusable and hides it from form submits |
+| formatter | `(value: string) => string` | `-` | Function to format value when the input field |
+| helpText | `string` | `-` | Description shown below the input field |
+| invalid | `boolean` | `false` | Mark the form field as invalid. |
+| label | `string` | `-` | Either a `label` or an `aria-label` must be provided. |
+| max | `number` | `-` | Use with `type="number"` to set the [maximum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength). |
+| maxLength | `number` | `-` | **Deprecated**: Use the native `maxlength` attribute |
+| maxlength | `number` | `-` | For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the [maximum string length](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) allowed. |
+| min | `number` | `-` | Use with `type="number"` to set the [minimum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength). |
+| minLength | `number` | `-` | **Deprecated**: Use the native `minlength` attribute |
+| minlength | `number` | `-` | For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the [minimum string length](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength) required. |
+| name | `string` | `-` | The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form. |
+| pattern | `string` | `-` | Sets a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that the input's value must [match to pass validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#pattern) |
+| placeholder | `string` | `-` | Shown in the textfield when it doesn't have a value |
+| readOnly | `boolean` | `false` | **Deprecated**: Use the native readonly attribute instead. |
+| readonly | `boolean` | `false` | Whether the input can be selected but not changed by the user. |
+| required | `boolean` | `false` | Whether user input is required on the input before form submission. |
+| size | `string` | `-` | Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs. |
+| step | `number` | `-` | Forces `number` inputs to be a whole number of `step` |
+| type | `string` | `-` | The [type of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types). |
+| value | `string` | `-` | Lets you set the current value. |
 
 ### Property Details
 
-#### shadowRootOptions
-
+#### autocomplete
 
+A space-separated string that hints to browsers [what type of content it can suggest](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete#value) to autofill.
 
-- Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+- Type: `string \| undefined`
+- Default: `-`
 
 #### disabled
 
+Keep in mind that using disabled in its current form is an anti-pattern.
 
+There will always be users who don't understand why an element is disabled, or users who can't even see that it is disabled because of poor lighting conditions or other reasons.
+
+Please consider more informative alternatives before choosing to use disabled on an element.
 
 - Type: `boolean`
 - Default: `false`
 
-#### invalid
-
+#### formatter
 
+Function to format value when the input field.
 
-- Type: `boolean`
-- Default: `false`
+Only active when the input field does not have focus,
+similar to the accessible input [masking example from Filament Group](https://filamentgroup.github.io/politespace/demo/demo.html).
 
-#### id
+- Type: `(value: string) => string`
+- Default: `-`
 
+#### helpText
 
+Use in combination with `invalid` to show as a validation error message,
+or on its own to show a help text.
 
 - Type: `string`
 - Default: `-`
 
-#### label
+#### invalid
+
+Mark the form field as invalid. Make sure to also set a `help-text` to help users fix the validation problem.
+
+- Type: `boolean`
+- Default: `false`
 
+#### label
 
+Either a `label` or an `aria-label` must be provided.
 
 - Type: `string`
 - Default: `-`
 
-#### helpText
-
+#### max
 
+Use with `type="number"` to set the [maximum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength).
 
-- Type: `string`
+- Type: `number`
 - Default: `-`
 
-#### size
+#### maxLength
 
+**Deprecated**: Use the native `maxlength` attribute
 
 
-- Type: `string`
-- Default: `-`
 
-#### max
+- Type: `number`
+- Default: `-`
 
+#### maxlength
 
+For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the [maximum string length](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#maxlength) allowed.
 
 - Type: `number`
 - Default: `-`
 
 #### min
 
-
+Use with `type="number"` to set the [minimum allowed value](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength).
 
 - Type: `number`
 - Default: `-`
 
 #### minLength
 
+**Deprecated**: Use the native `minlength` attribute
+
 
 
 - Type: `number`
 - Default: `-`
 
-#### maxLength
-
+#### minlength
 
+For `text`, `search`, `url`, `tel`, `email` and `password` fields, sets the [minimum string length](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#minlength) required.
 
 - Type: `number`
 - Default: `-`
 
-#### pattern
+#### name
 
+The [name](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#name) of the input field when submitting the form.
 
+- Type: `string`
+- Default: `-`
+
+#### pattern
+
+Sets a [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) that the input's value must [match to pass validation](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#pattern)
 
 - Type: `string`
 - Default: `-`
 
 #### placeholder
 
+Set a text that is shown in the textfield when it doesn't have a value.
 
+Placeholder text should not be used as a substitute for labeling the element with a visible label.
 
 - Type: `string`
 - Default: `-`
 
 #### readOnly
 
+**Deprecated**: Use the native readonly attribute instead.
+
 
 
 - Type: `boolean`
@@ -145,72 +363,47 @@ A single line text input element.
 
 #### readonly
 
-
+Whether the input can be selected but not changed by the user.
 
 - Type: `boolean`
 - Default: `false`
 
 #### required
 
-
+Whether user input is required on the input before form submission.
 
 - Type: `boolean`
 - Default: `false`
 
-#### type
-
-
-
-- Type: `string`
-- Default: `-`
-
-#### value
-
-
-
-- Type: `string`
-- Default: `-`
-
-#### name
-
+#### size
 
+Sets the [size](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#size) (width) of the input field to fit the expected length of inputs.
 
 - Type: `string`
 - Default: `-`
 
 #### step
 
+When used with `number` this attribute forces inputs to be a whole number of `step`.
 
+For example with a `step="5"` only values that divide evenly on 5 are allowed.
+Using arrow up and down in the input field increments and decrements by 5.
 
 - Type: `number`
 - Default: `-`
 
-#### autocomplete
-
-
-
-- Type: `string | undefined`
-- Default: `-`
-
-#### formatter
-
-
-
-- Type: `(value: string) => string`
-- Default: `-`
-
-#### _hasPrefix
-
+#### type
 
+The [type of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#input_types).
 
-- Type: `unknown`
+- Type: `string`
 - Default: `-`
 
-#### _hasSuffix
-
+#### value
 
+Lets you set the current value.
 
-- Type: `unknown`
+- Type: `string`
 - Default: `-`
 
 ### Types

package/dist/docs/textfield/usage.md

@@ -1 +1,31 @@
 ## Usage
+
+<style-isolate>
+    <w-textfield label="Email" type="email"></w-textfield>
+</style-isolate>
+
+```html
+<w-textfield label="Email" type="email"></w-textfield>
+```
+
+### Validation
+
+Set the `invalid` attribute to display a textfield as invalid.
+
+`invalid` should be paired with `help-text` to provide feedback to the user about how to correct the error.
+
+<style-isolate>
+    <w-textfield 
+        label="Email"
+        invalid
+        help-text="An email should have an @ sign and a domain name, for example ola.nordmann@finn.no"
+    ></w-textfield>
+</style-isolate>
+
+```html
+<w-textfield 
+    label="Email"
+    invalid
+    help-text="An email should have an @ sign and a domain name, for example ola.nordmann@finn.no"
+></w-textfield>
+```