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

package/dist/docs/textarea/textarea.md

@@ -0,0 +1,170 @@
+# Textarea (w-textarea)
+
+## Description
+
+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
+
+| 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` | `-` | - |
+
+### Property Details
+
+#### shadowRootOptions
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+
+#### disabled
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### invalid
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### label
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### helpText
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### maxRows
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### minRows
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### name
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### placeholder
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### readOnly
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### readonly
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### required
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### value
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### optional
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### minHeight
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### maxHeight
+
+
+
+- Type: `unknown`
+- Default: `-`
+
+#### validationMessage
+
+Returns the validation message if the textarea is invalid, otherwise an empty string
+
+- Type: `string`
+- Default: `-`
+
+#### validity
+
+Returns the validity state of the textarea
+
+- Type: `ValidityState`
+- Default: `-`
+
+### Types
+
+No types documented.

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

@@ -0,0 +1,204 @@
+## 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` | `-` | - |
+
+### Property Details
+
+#### shadowRootOptions
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+
+#### disabled
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### invalid
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### id
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### label
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### helpText
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### size
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### max
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### min
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### minLength
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### maxLength
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### pattern
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### placeholder
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### readOnly
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### readonly
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### required
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### type
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### value
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### name
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### step
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### autocomplete
+
+
+
+- Type: `string | undefined`
+- Default: `-`
+
+#### formatter
+
+
+
+- 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

@@ -0,0 +1,218 @@
+# TextField (w-textfield)
+
+## Description
+
+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
+
+| 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` | `-` | - |
+
+### Property Details
+
+#### shadowRootOptions
+
+
+
+- Type: `object`
+- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
+
+#### disabled
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### invalid
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### id
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### label
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### helpText
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### size
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### max
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### min
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### minLength
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### maxLength
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### pattern
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### placeholder
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### readOnly
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### readonly
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### required
+
+
+
+- Type: `boolean`
+- Default: `false`
+
+#### type
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### value
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### name
+
+
+
+- Type: `string`
+- Default: `-`
+
+#### step
+
+
+
+- Type: `number`
+- Default: `-`
+
+#### autocomplete
+
+
+
+- Type: `string | undefined`
+- Default: `-`
+
+#### formatter
+
+
+
+- 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>