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

package/dist/docs/tab/tab.md

@@ -6,6 +6,12 @@ Individual tab component used within w-tabs container.
 
 [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/tabs--docs)
 
+## Usage
+
+## Accessibility
+
+## Examples
+
 ## API Documentation
 
 ### Properties
@@ -20,6 +26,8 @@ Individual tab component used within w-tabs container.
 | ariaSelected | `'true' | 'false'` | `-` | - |
 | active | `boolean` | `false` | - |
 | over | `boolean` | `false` | - |
+| _parentTabIndex | `unknown` | `-` | - |
+| _parentAriaSelected | `unknown` | `-` | - |
 
 ### Property Details
 
@@ -79,6 +87,20 @@ Computed aria-selected: prefers parent-managed, falls back to own property
 - Type: `boolean`
 - Default: `false`
 
+#### _parentTabIndex
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### _parentAriaSelected
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 ### Types
 
 No types documented.

package/dist/docs/tab/usage.md

@@ -0,0 +1 @@
+## Usage

package/dist/docs/tab-panel/accessibility.md

@@ -0,0 +1 @@
+## Accessibility

package/dist/docs/tab-panel/api.md

@@ -5,6 +5,8 @@
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | active | `boolean` | `-` | - |
+| _parentActive | `unknown` | `-` | - |
+| _parentAriaLabelledBy | `unknown` | `-` | - |
 
 ### Property Details
 
@@ -16,6 +18,20 @@ Set by parent w-tabs via the _parentActive property.
 - Type: `boolean`
 - Default: `-`
 
+#### _parentActive
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### _parentAriaLabelledBy
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 ### Types
 
 No types documented.

package/dist/docs/tab-panel/examples.md

@@ -0,0 +1 @@
+## Examples

package/dist/docs/tab-panel/tab-panel.md

@@ -7,6 +7,12 @@ Each tab panel should have a name that matches a corresponding tab.
 
 [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/tabs--docs)
 
+## Usage
+
+## Accessibility
+
+## Examples
+
 ## API Documentation
 
 ### Properties
@@ -14,6 +20,8 @@ Each tab panel should have a name that matches a corresponding tab.
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | active | `boolean` | `-` | - |
+| _parentActive | `unknown` | `-` | - |
+| _parentAriaLabelledBy | `unknown` | `-` | - |
 
 ### Property Details
 
@@ -25,6 +33,20 @@ Set by parent w-tabs via the _parentActive property.
 - Type: `boolean`
 - Default: `-`
 
+#### _parentActive
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### _parentAriaLabelledBy
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 ### Types
 
 No types documented.

package/dist/docs/tab-panel/usage.md

@@ -0,0 +1 @@
+## Usage

package/dist/docs/tabs/accessibility.md

@@ -0,0 +1 @@
+## Accessibility

package/dist/docs/tabs/examples.md

@@ -0,0 +1 @@
+## Examples

package/dist/docs/tabs/tabs.md

@@ -6,6 +6,12 @@ Tabs are used to organize content by grouping similar information on the same pa
 
 [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/tabs--docs)
 
+## Usage
+
+## Accessibility
+
+## Examples
+
 ## API Documentation
 
 ### Properties

package/dist/docs/tabs/usage.md

@@ -0,0 +1 @@
+## Usage

package/dist/docs/textarea/accessibility.md

@@ -0,0 +1 @@
+## Accessibility

package/dist/docs/textarea/examples.md

@@ -0,0 +1 @@
+## Examples

package/dist/docs/textarea/textarea.md

@@ -6,6 +6,12 @@ A single line text input element.
 
 [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-textfield--docs)
 
+## Usage
+
+## Accessibility
+
+## Examples
+
 ## API Documentation
 
 ### Properties

package/dist/docs/textarea/usage.md

@@ -0,0 +1 @@
+## Usage

package/dist/docs/textfield/accessibility.md

@@ -0,0 +1 @@
+## Accessibility

package/dist/docs/textfield/api.md

@@ -26,6 +26,8 @@
 | step | `number` | `-` | - |
 | autocomplete | `string | undefined` | `-` | - |
 | formatter | `(value: string) => string` | `-` | - |
+| _hasPrefix | `unknown` | `-` | - |
+| _hasSuffix | `unknown` | `-` | - |
 
 ### Property Details
 
@@ -178,17 +180,25 @@
 
 #### formatter
 
-Function to format value when the input field.
 
-Only active when the input field does not have focus,
-similar to the accessible input masking example from Filament Group
-
-https://css-tricks.com/input-masking/
-https://filamentgroup.github.io/politespace/demo/demo.html
 
 - Type: `(value: string) => string`
 - Default: `-`
 
+#### _hasPrefix
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### _hasSuffix
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 ### Types
 
 No types documented.

package/dist/docs/textfield/examples.md

@@ -0,0 +1 @@
+## Examples

package/dist/docs/textfield/textfield.md

@@ -6,6 +6,12 @@ A single line text input element.
 
 [See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-textfield--docs)
 
+## Usage
+
+## Accessibility
+
+## Examples
+
 ## API Documentation
 
 ### Properties
@@ -34,6 +40,8 @@ A single line text input element.
 | step | `number` | `-` | - |
 | autocomplete | `string | undefined` | `-` | - |
 | formatter | `(value: string) => string` | `-` | - |
+| _hasPrefix | `unknown` | `-` | - |
+| _hasSuffix | `unknown` | `-` | - |
 
 ### Property Details
 
@@ -186,17 +194,25 @@ A single line text input element.
 
 #### formatter
 
-Function to format value when the input field.
-
-Only active when the input field does not have focus,
-similar to the accessible input masking example from Filament Group
 
-https://css-tricks.com/input-masking/
-https://filamentgroup.github.io/politespace/demo/demo.html
 
 - Type: `(value: string) => string`
 - Default: `-`
 
+#### _hasPrefix
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### _hasSuffix
+
+
+
+- Type: `unknown`
+- Default: `-`
+
 ### Types
 
 No types documented.

package/dist/docs/textfield/usage.md

@@ -0,0 +1 @@
+## Usage

package/dist/docs/toast/accessibility.md

@@ -0,0 +1,9 @@
+## Accessibility
+
+From an accessibility perspective, toasts should never contain interactive elements, as these should always appear in the same location as the action that triggered them.
+
+Auto-clearing toasts based on a timeout violate WCAG 2 success criteria 2.2.1, unless the information they contain is either redundant (i.e. also available elsewhere in a persistent manner) or insignificant to all people.
+
+You are also advised to avoid putting information in a toast that cannot be re-accessed in any other way due to the impermanent nature of the current toast implementation.
+
+Because of these points we consider the use of toasts to be somewhat of an anti-pattern, and recommend exploring alternative approaches wherever possible. That said, you may still use toasts, as long as you avoid interactive elements like links or close buttons.

package/dist/docs/toast/api.md

@@ -0,0 +1,71 @@
+## API Documentation
+
+### toast
+
+```js
+import { toast } from '@warp-ds/elements/toast';
+
+const theToast = toast('Toasts are somewhat of an anti-pattern');
+```
+
+Returns [ToastOptions](#toastoptions), which includes the ID you need for [updateToast](#updatetoast) and [removeToast](#removetoast).
+
+If you can't pass the result from `toast` to where you call `updateToast` or `removeToast` you can set a known ID manually.
+
+```js
+toast('Toasts are somewhat of an anti-pattern', {
+    id: 'something-unique-but-stable',
+});
+```
+
+| Parameter | Type |  Summary |
+| --- | --- | --- |
+| message | `string` | The text content |
+| options | [ToastOptions](#toastoptions) (optional) | |
+
+
+### updateToast
+
+```js
+import { toast, updateToast } from '@warp-ds/elements/toast';
+
+const theToast = toast('The toast function returns an ID');
+
+updateToast(theToast.id, 'Use it to update the text');
+```
+
+Returns [ToastOptions](#toastoptions).
+
+| Parameter | Type |  Summary |
+| --- | --- | --- |
+| id |  `string` | The ID of the toast you want to update |
+| message | `string` | The new text content |
+| options | [ToastOptions](#toastoptions) (optional) | |
+
+### removeToast
+
+Toasts disappear after a set time, but if you need to remove one before that happens you can do so.
+
+```js
+import { toast, removeToast } from '@warp-ds/elements/toast';
+
+const theToast = toast('The toast function returns an ID');
+
+removeToast(theToast.id);
+```
+
+### Types
+
+#### ToastOptions
+
+| Name | Type | Default | Summary |
+| --- | --- | --- | --- |
+| id | `string` | Random | Random generated unique ID for the toast element |
+| type | [`ToastVariants`](#toastvariants) | `'success'` | Visual style of the toast |
+| text | `string` | `-` | The given toast message |
+| duration | `number` | `5000` | Duration of toast in milliseconds |
+| canclose | `boolean` | `false` | See [Dismissable toast](#dismissable-toast) |
+
+#### ToastVariants
+
+`'success' | 'warning' | 'error'`

package/dist/docs/toast/examples.md

@@ -0,0 +1,29 @@
+## Examples
+
+### Success / positive
+
+This is the default.
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern')">Show a success toast</w-button>
+</style-isolate>
+
+### Warning
+
+If the user should be warned about something, a toast is probably not the right way to do so. Consider an [Alert](/docs/components/alert/overview) instead.
+
+A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for warnings).
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern', { type: 'warning' })">Show a warning toast</w-button>
+</style-isolate>
+
+### Error / negative
+
+If the user should be told about an error, a toast is probably not the right way to do so. Consider an [Alert](/docs/components/alert/overview) instead.
+
+A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for errors).
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern', { type: 'error' })">Show an error toast</w-button>
+</style-isolate>

package/dist/docs/toast/toast.md

@@ -0,0 +1,150 @@
+# Toast
+
+## Description
+
+Toasts are brief user feedback messages that overlay content.
+
+## Usage
+
+You should not use the toast components directly. Instead use the JavaScript API exported from Warp Elements to create, update and remove toasts
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern')">Show toast</w-button>
+</style-isolate>
+
+
+```js
+import { toast } from '@warp-ds/elements/toast';
+
+const showBtn = document.getElementById("toast-btn");
+showBtn.onclick = () => {
+    toast("Toasts are somewhat of an anti-pattern");
+};
+```
+
+### Dismissable toast
+
+The toast automatically closes by default, so you don't need to have a close button.
+
+From an accessibility perspective, toasts should never contain interactive elements such as close buttons, as interactive elements should always appear in the same location as the action that triggered them.
+
+It might be tempting to use this option and a high duration if you have a warning or error toast to "solve" the WCAG 2 success criteria 2.2.1, but please consider showing warnings and errors as a persistent [Alert](/docs/components/alert/overview) instead.
+
+If the toast absolutely must be dismissible by the user, set the `canclose` property to `true`.
+
+```js
+toast('message goes here', { type: 'success', canclose: true });
+```
+
+## Accessibility
+
+From an accessibility perspective, toasts should never contain interactive elements, as these should always appear in the same location as the action that triggered them.
+
+Auto-clearing toasts based on a timeout violate WCAG 2 success criteria 2.2.1, unless the information they contain is either redundant (i.e. also available elsewhere in a persistent manner) or insignificant to all people.
+
+You are also advised to avoid putting information in a toast that cannot be re-accessed in any other way due to the impermanent nature of the current toast implementation.
+
+Because of these points we consider the use of toasts to be somewhat of an anti-pattern, and recommend exploring alternative approaches wherever possible. That said, you may still use toasts, as long as you avoid interactive elements like links or close buttons.
+
+## Examples
+
+### Success / positive
+
+This is the default.
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern')">Show a success toast</w-button>
+</style-isolate>
+
+### Warning
+
+If the user should be warned about something, a toast is probably not the right way to do so. Consider an [Alert](/docs/components/alert/overview) instead.
+
+A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for warnings).
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern', { type: 'warning' })">Show a warning toast</w-button>
+</style-isolate>
+
+### Error / negative
+
+If the user should be told about an error, a toast is probably not the right way to do so. Consider an [Alert](/docs/components/alert/overview) instead.
+
+A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for errors).
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern', { type: 'error' })">Show an error toast</w-button>
+</style-isolate>
+
+## API Documentation
+
+### toast
+
+```js
+import { toast } from '@warp-ds/elements/toast';
+
+const theToast = toast('Toasts are somewhat of an anti-pattern');
+```
+
+Returns [ToastOptions](#toastoptions), which includes the ID you need for [updateToast](#updatetoast) and [removeToast](#removetoast).
+
+If you can't pass the result from `toast` to where you call `updateToast` or `removeToast` you can set a known ID manually.
+
+```js
+toast('Toasts are somewhat of an anti-pattern', {
+    id: 'something-unique-but-stable',
+});
+```
+
+| Parameter | Type |  Summary |
+| --- | --- | --- |
+| message | `string` | The text content |
+| options | [ToastOptions](#toastoptions) (optional) | |
+
+
+### updateToast
+
+```js
+import { toast, updateToast } from '@warp-ds/elements/toast';
+
+const theToast = toast('The toast function returns an ID');
+
+updateToast(theToast.id, 'Use it to update the text');
+```
+
+Returns [ToastOptions](#toastoptions).
+
+| Parameter | Type |  Summary |
+| --- | --- | --- |
+| id |  `string` | The ID of the toast you want to update |
+| message | `string` | The new text content |
+| options | [ToastOptions](#toastoptions) (optional) | |
+
+### removeToast
+
+Toasts disappear after a set time, but if you need to remove one before that happens you can do so.
+
+```js
+import { toast, removeToast } from '@warp-ds/elements/toast';
+
+const theToast = toast('The toast function returns an ID');
+
+removeToast(theToast.id);
+```
+
+### Types
+
+#### ToastOptions
+
+| Name | Type | Default | Summary |
+| --- | --- | --- | --- |
+| id | `string` | Random | Random generated unique ID for the toast element |
+| type | [`ToastVariants`](#toastvariants) | `'success'` | Visual style of the toast |
+| text | `string` | `-` | The given toast message |
+| duration | `number` | `5000` | Duration of toast in milliseconds |
+| canclose | `boolean` | `false` | See [Dismissable toast](#dismissable-toast) |
+
+#### ToastVariants
+
+`'success' | 'warning' | 'error'`
+

package/dist/docs/toast/usage.md

@@ -0,0 +1,31 @@
+## Usage
+
+You should not use the toast components directly. Instead use the JavaScript API exported from Warp Elements to create, update and remove toasts
+
+<style-isolate id="toast-usage">
+    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern')">Show toast</w-button>
+</style-isolate>
+
+
+```js
+import { toast } from '@warp-ds/elements/toast';
+
+const showBtn = document.getElementById("toast-btn");
+showBtn.onclick = () => {
+    toast("Toasts are somewhat of an anti-pattern");
+};
+```
+
+### Dismissable toast
+
+The toast automatically closes by default, so you don't need to have a close button.
+
+From an accessibility perspective, toasts should never contain interactive elements such as close buttons, as interactive elements should always appear in the same location as the action that triggered them.
+
+It might be tempting to use this option and a high duration if you have a warning or error toast to "solve" the WCAG 2 success criteria 2.2.1, but please consider showing warnings and errors as a persistent [Alert](/docs/components/alert/overview) instead.
+
+If the toast absolutely must be dismissible by the user, set the `canclose` property to `true`.
+
+```js
+toast('message goes here', { type: 'success', canclose: true });
+```