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

package/dist/docs/badge/examples.md

@@ -2,26 +2,17 @@
 
 ### Basic
 
-<style-isolate>
-  <w-badge>New</w-badge>
-</style-isolate>
-
+<elements-example>
+  
 ```html
 <w-badge>New</w-badge>
 ```
 
+</elements-example>
+
 ### Status Variants
 
-<style-isolate>
-  <div style="display: flex; flex-wrap: wrap; gap: 8px; align-items: center;">
-    <w-badge variant="neutral">Neutral</w-badge>
-    <w-badge variant="info">Info</w-badge>
-    <w-badge variant="positive">Approved</w-badge>
-    <w-badge variant="warning">Pending</w-badge>
-    <w-badge variant="negative">Rejected</w-badge>
-    <w-badge variant="disabled">Unavailable</w-badge>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-badge variant="neutral">Neutral</w-badge>
@@ -32,52 +23,48 @@
 <w-badge variant="disabled">Unavailable</w-badge>
 ```
 
-### Price
+</elements-example>
 
-<style-isolate>
-  <w-badge variant="price">1 200 kr</w-badge>
-</style-isolate>
+### Price
 
+<elements-example>
+  
 ```html
 <w-badge variant="price">1 200 kr</w-badge>
 ```
 
-### Sponsored
+</elements-example>
 
-<style-isolate>
-  <w-badge variant="sponsored">Sponsored</w-badge>
-</style-isolate>
+### Sponsored
 
+<elements-example>
+  
 ```html
 <w-badge variant="sponsored">Sponsored</w-badge>
 ```
 
+</elements-example>
+
 ### Positioned
 
-<style-isolate>
-  <div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
-    <w-badge variant="price" position="top-right">1 200 kr</w-badge>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
-<div style="position: relative;">
-  <img src="listing.jpg" alt="Living room with large windows" />
+<div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
   <w-badge variant="price" position="top-right">1 200 kr</w-badge>
 </div>
 ```
 
+</elements-example>
+
 ### Positioned Sponsored Badge
 
-<style-isolate>
-  <div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
-    <w-badge variant="sponsored" position="bottom-left">Sponsored</w-badge>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
-<div style="position: relative;">
-  <img src="listing.jpg" alt="Living room with large windows" />
+<div style="position: relative; width: 220px; height: 124px; border-radius: 8px; overflow: hidden; background: #e5e7eb;">
   <w-badge variant="sponsored" position="bottom-left">Sponsored</w-badge>
 </div>
 ```
+
+</elements-example>

package/dist/docs/textarea/accessibility.md

@@ -1 +1,6 @@
 ## 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).

package/dist/docs/textarea/api.md

@@ -4,107 +4,99 @@
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| disabled | `boolean` | `false` | - |
-| helpText | `string` | `-` | - |
-| invalid | `boolean` | `false` | - |
-| label | `string` | `-` | - |
-| maxHeight | `unknown` | `-` | - |
-| maxRows | `number` | `-` | - |
-| minHeight | `unknown` | `-` | - |
-| minRows | `number` | `-` | - |
-| name | `string` | `-` | - |
-| optional | `boolean` | `false` | - |
-| placeholder | `string` | `-` | - |
-| readOnly | `boolean` | `false` | **Deprecated**: Use the native readonly attribute instead. Here for API consistency with `w-textfield`. |
-| readonly | `boolean` | `false` | - |
-| required | `boolean` | `false` | - |
-| shadowRootOptions | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
+| 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` | `-` | - |
+| value | `string` | `-` | Lets you set the current value |
 
 ### Property Details
 
 #### 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`
 
 #### 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: `-`
 
 #### 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: `-`
 
-#### maxHeight
-
-
-
-- Type: `unknown`
-- Default: `-`
-
 #### maxRows
 
-
+Sets the maximum number of text rows before the content starts scrolling.
 
 - Type: `number`
 - Default: `-`
 
-#### minHeight
-
-
-
-- Type: `unknown`
-- Default: `-`
-
 #### minRows
 
-
+Sets the minimum number of text rows the textarea should display
 
 - 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`
 
 #### 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: `string`
 - Default: `-`
 
 #### readOnly
 
-**Deprecated**: Use the native readonly attribute instead. Here for API consistency with `w-textfield`.
+**Deprecated**: Use the native `readonly` attribute instead
 
 
 
@@ -113,25 +105,18 @@
 
 #### 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`
 
-#### shadowRootOptions
-
-
-
-- Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
-
 #### validationMessage
 
 Returns the validation message if the textarea is invalid, otherwise an empty string
@@ -148,7 +133,7 @@ Returns the validity state of the textarea
 
 #### value
 
-
+Lets you set the current value
 
 - Type: `string`
 - Default: `-`

package/dist/docs/textarea/examples.md

@@ -1 +1,82 @@
 ## Examples
+
+<elements-example>
+
+```html
+<w-textarea label="Description"></w-textarea>
+```
+
+</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.
+
+<elements-example>
+
+```html
+<w-textarea
+    label="Description"
+    placeholder="Give as much detail as you can"
+></w-textarea>
+```
+
+</elements-example>
+
+### Height
+
+You can control the height of the input field by setting either `minimum-rows` or `maximum-rows`
+
+<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`.
+
+<elements-example>
+
+```html
+<w-textarea label="Description" maximum-rows="3" value="Line 1
+Line 2
+Line 3
+Line 4
+Line 5"></w-textarea>
+```
+
+</elements-example>
+
+### Disabled
+
+Consider using more informative alternatives before choosing to use disabled, as some users may not understand why an element is disabled.
+
+<elements-example>
+
+```html
+<w-textarea
+    label="Description" 
+    value="This form field is ignored"
+    disabled
+></w-textarea>
+```
+
+</elements-example>
+
+### Read only 
+
+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>
+```
+
+</elements-example>

package/dist/docs/textarea/textarea.md

@@ -2,123 +2,214 @@
 
 ## 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
 
+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).
+
 ## Examples
 
+<elements-example>
+
+```html
+<w-textarea label="Description"></w-textarea>
+```
+
+</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.
+
+<elements-example>
+
+```html
+<w-textarea
+    label="Description"
+    placeholder="Give as much detail as you can"
+></w-textarea>
+```
+
+</elements-example>
+
+### Height
+
+You can control the height of the input field by setting either `minimum-rows` or `maximum-rows`
+
+<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`.
+
+<elements-example>
+
+```html
+<w-textarea label="Description" maximum-rows="3" value="Line 1
+Line 2
+Line 3
+Line 4
+Line 5"></w-textarea>
+```
+
+</elements-example>
+
+### Disabled
+
+Consider using more informative alternatives before choosing to use disabled, as some users may not understand why an element is disabled.
+
+<elements-example>
+
+```html
+<w-textarea
+    label="Description" 
+    value="This form field is ignored"
+    disabled
+></w-textarea>
+```
+
+</elements-example>
+
+### Read only 
+
+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>
+```
+
+</elements-example>
+
 ## API Documentation
 
 ### Properties
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| disabled | `boolean` | `false` | - |
-| helpText | `string` | `-` | - |
-| invalid | `boolean` | `false` | - |
-| label | `string` | `-` | - |
-| maxHeight | `unknown` | `-` | - |
-| maxRows | `number` | `-` | - |
-| minHeight | `unknown` | `-` | - |
-| minRows | `number` | `-` | - |
-| name | `string` | `-` | - |
-| optional | `boolean` | `false` | - |
-| placeholder | `string` | `-` | - |
-| readOnly | `boolean` | `false` | **Deprecated**: Use the native readonly attribute instead. Here for API consistency with `w-textfield`. |
-| readonly | `boolean` | `false` | - |
-| required | `boolean` | `false` | - |
-| shadowRootOptions | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
+| 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` | `-` | - |
+| value | `string` | `-` | Lets you set the current value |
 
 ### Property Details
 
 #### 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`
 
 #### 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: `-`
 
 #### 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: `-`
 
-#### maxHeight
-
-
-
-- Type: `unknown`
-- Default: `-`
-
 #### maxRows
 
-
+Sets the maximum number of text rows before the content starts scrolling.
 
 - Type: `number`
 - Default: `-`
 
-#### minHeight
-
-
-
-- Type: `unknown`
-- Default: `-`
-
 #### minRows
 
-
+Sets the minimum number of text rows the textarea should display
 
 - 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`
 
 #### 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: `string`
 - Default: `-`
 
 #### readOnly
 
-**Deprecated**: Use the native readonly attribute instead. Here for API consistency with `w-textfield`.
+**Deprecated**: Use the native `readonly` attribute instead
 
 
 
@@ -127,25 +218,18 @@ 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`
 
-#### shadowRootOptions
-
-
-
-- Type: `object`
-- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
-
 #### validationMessage
 
 Returns the validation message if the textarea is invalid, otherwise an empty string
@@ -162,7 +246,7 @@ Returns the validity state of the textarea
 
 #### value
 
-
+Lets you set the current value
 
 - Type: `string`
 - Default: `-`

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