@warp-ds/elements 2.9.0-next.5 → 2.9.0

package/dist/docs/textarea/textarea.md

@@ -2,154 +2,233 @@
 
 ## Description
 
-A single line text input element.
+A multi-line text input with built-in form validation, auto-resizing, and styling support.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-textfield--docs)
+The component automatically handles:
+ - Form integration
+ - Auto-resizing based on content and row constraints
+ - Built-in validation with customizable error messages
+ - Accessibility attributes and labeling
 
 ## Usage
 
+A multi-line text input with built-in form validation, auto-resizing, and styling support.
+
+The component automatically handles:
+
+- Form integration
+- Auto-resizing based on content and row constraints
+- Built-in validation with customizable error messages
+- Accessibility attributes and labeling
+
 ## Accessibility
 
-## Examples
+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.
 
-## API Documentation
+- Always provide a visible label (do not rely on `placeholder` alone).
+- Do not rely on color alone for interaction feedback (e.g. error states).
 
-### Properties
+## Examples
 
-| Name | Type | Default | Summary |
-|-|-|-|-|
-| shadowRootOptions | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
-| disabled | `boolean` | `false` | - |
-| invalid | `boolean` | `false` | - |
-| label | `string` | `-` | - |
-| helpText | `string` | `-` | - |
-| maxRows | `number` | `-` | - |
-| minRows | `number` | `-` | - |
-| name | `string` | `-` | - |
-| placeholder | `string` | `-` | - |
-| readOnly | `boolean` | `false` | - |
-| readonly | `boolean` | `false` | - |
-| required | `boolean` | `false` | - |
-| value | `string` | `-` | - |
-| optional | `boolean` | `false` | - |
-| minHeight | `unknown` | `-` | - |
-| maxHeight | `unknown` | `-` | - |
-| validationMessage | `string` | `-` | - |
-| validity | `ValidityState` | `-` | - |
+<elements-example>
 
-### Property Details
+```html
+<w-textarea label="Description"></w-textarea>
+```
 
-#### shadowRootOptions
+</elements-example>
 
+### Placeholder
 
+Text hint that appears when the textarea is empty. Placeholder text should not be used as a substitute for a visible label.
 
-- Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+<elements-example>
 
-#### disabled
+```html
+<w-textarea
+    label="Description"
+    placeholder="Give as much detail as you can"
+></w-textarea>
+```
 
+</elements-example>
 
+### Height
 
-- Type: `boolean`
-- Default: `false`
+You can control the height of the input field by setting either `minimum-rows` or `maximum-rows`
 
-#### invalid
+<elements-example>
+    
+```html
+<w-textarea label="Description" minimum-rows="3"></w-textarea>
+```
 
+</elements-example>
 
+With `maximum-rows` the content will start scrolling when it passes the limit. Note that the field stops being resizable. Setting `minimum-rows` is redundant when you set `maximum-rows`.
 
-- Type: `boolean`
-- Default: `false`
+<elements-example>
 
-#### label
+```html
+<w-textarea label="Description" maximum-rows="3" value="Line 1
+Line 2
+Line 3
+Line 4
+Line 5"></w-textarea>
+```
 
+</elements-example>
 
+### Disabled
 
-- Type: `string`
-- Default: `-`
+Consider using more informative alternatives before choosing to use disabled, as some users may not understand why an element is disabled.
 
-#### helpText
+<elements-example>
 
+```html
+<w-textarea
+    label="Description" 
+    value="This form field is ignored"
+    disabled
+></w-textarea>
+```
 
+</elements-example>
 
-- Type: `string`
-- Default: `-`
+### Read only 
 
-#### maxRows
+Makes the textarea content immutable while remaining focusable. The contents can still be copied.
 
+<elements-example>
 
+```html
+<w-textarea
+    label="Description"
+    value="This content is read only"
+    readonly
+></w-textarea>
+```
 
-- Type: `number`
-- Default: `-`
+</elements-example>
 
-#### minRows
+## API Documentation
 
+### Properties
 
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| disabled | `boolean` | `false` | Makes the element not focusable and hides it from form submits |
+| 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. |
+| maxRows | `number` | `-` | Sets the maximum number of text rows before the content starts scrolling. |
+| minRows | `number` | `-` | Sets the minimum number of text rows the textarea should display |
+| 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 |
+| optional | `boolean` | `false` | Show an icon behind the label indicating the field is optional |
+| placeholder | `string` | `-` | Shown in the textarea 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 |
+| validationMessage | `string` | `-` | Returns the validation message if the textarea is invalid, otherwise an empty string |
+| validity | `ValidityState` | `-` | Returns the validity state of the textarea |
+| value | `string` | `-` | Lets you set the current value |
 
-- Type: `number`
-- Default: `-`
+### Property Details
 
-#### name
+#### 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.
 
-- Type: `string`
-- Default: `-`
+Please consider more informative alternatives before choosing to use disabled on an element.
 
-#### placeholder
+- Type: `boolean`
+- Default: `false`
 
+#### 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: `-`
 
-#### readOnly
+#### 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`
 
-#### readonly
+#### label
 
+Either a `label` or an `aria-label` must be provided.
 
+- Type: `string`
+- Default: `-`
 
-- Type: `boolean`
-- Default: `false`
+#### maxRows
 
-#### required
+Sets the maximum number of text rows before the content starts scrolling.
 
+- Type: `number`
+- Default: `-`
 
+#### minRows
 
-- Type: `boolean`
-- Default: `false`
+Sets the minimum number of text rows the textarea should display
 
-#### value
+- Type: `number`
+- Default: `-`
 
+#### 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: `-`
 
 #### optional
 
-
+Show an icon behind the label indicating the field is optional
 
 - Type: `boolean`
 - Default: `false`
 
-#### minHeight
+#### placeholder
 
+Set a text that is shown in the textarea 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: `unknown`
+- Type: `string`
 - Default: `-`
 
-#### maxHeight
+#### readOnly
 
+**Deprecated**: Use the native `readonly` attribute instead
 
 
-- Type: `unknown`
-- Default: `-`
+
+- Type: `boolean`
+- Default: `false`
+
+#### 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`
 
 #### validationMessage
 
@@ -165,6 +244,13 @@ Returns the validity state of the textarea
 - Type: `ValidityState`
 - Default: `-`
 
+#### value
+
+Lets you set the current value
+
+- Type: `string`
+- Default: `-`
+
 ### Types
 
 No types documented.

package/dist/docs/textarea/usage.md

@@ -1 +1,10 @@
 ## Usage
+
+A multi-line text input with built-in form validation, auto-resizing, and styling support.
+
+The component automatically handles:
+
+- Form integration
+- Auto-resizing based on content and row constraints
+- Built-in validation with customizable error messages
+- Accessibility attributes and labeling

package/dist/docs/textfield/accessibility.md

@@ -1 +1,16 @@
 ## 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>
+```

package/dist/docs/textfield/api.md

@@ -4,126 +4,154 @@
 
 | 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`
@@ -131,72 +159,47 @@
 
 #### 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