@warp-ds/elements 2.10.0-next.2 → 2.10.0-next.21

package/dist/docs/slider-thumb/api.md

@@ -4,11 +4,13 @@
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| aria-description | `string` | `-` | Contextual information for assistive technology, should it be needed |
-| aria-label | `string` | ``label` from `w-slider`` | Label for the range input. |
-| name | `string` | `-` | The name of this input field in the form. The canonical source of the value is the text field. |
-| placeholder | `string` | `-` | Placeholder in empty text fields |
-| value | `string` | `-` | The initial value, if any |
+| aria-description | `string \| null` | `null` | Contextual information for assistive technology, should it be needed |
+| aria-label | `string \| null` | `null` | Label for the range input. |
+| name | `string \| undefined` | `-` | The name of this input field in the form. The canonical source of the value is the text field. |
+| placeholder | `string \| undefined` | `-` | Placeholder in empty text fields |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
+| updateFieldAfterValidation (JS only) | `updateFieldAfterValidation() => void` | `-` | - |
+| value | `string \| undefined` | `-` | The initial value, if any |
 
 #### Property Details
 
@@ -16,35 +18,49 @@
 
 Contextual information for assistive technology, should it be needed
 
-- Type: `string`
-- Default: `-`
+- Type: `string | null`
+- Default: `null`
 
 ##### aria-label
 
 Label for the range input.
 
-- Type: `string`
-- Default: ``label` from `w-slider``
+- Type: `string | null`
+- Default: `null`
 
 ##### name
 
 The name of this input field in the form. The canonical source of the value is the text field.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 ##### placeholder
 
 Placeholder in empty text fields
 
-- Type: `string`
+- Type: `string | undefined`
+- Default: `-`
+
+##### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
+##### updateFieldAfterValidation (JS only)
+
+
+
+- Type: `updateFieldAfterValidation() => void`
 - Default: `-`
 
 ##### value
 
 The initial value, if any
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### Events

package/dist/docs/slider-thumb/slider-thumb.md

@@ -10,17 +10,21 @@ Component to place inside a `<w-slider>`.
 
 ## Examples
 
+## Styling API
+
 ### `<w-slider-thumb>` API
 
 #### Properties
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| aria-description | `string` | `-` | Contextual information for assistive technology, should it be needed |
-| aria-label | `string` | ``label` from `w-slider`` | Label for the range input. |
-| name | `string` | `-` | The name of this input field in the form. The canonical source of the value is the text field. |
-| placeholder | `string` | `-` | Placeholder in empty text fields |
-| value | `string` | `-` | The initial value, if any |
+| aria-description | `string \| null` | `null` | Contextual information for assistive technology, should it be needed |
+| aria-label | `string \| null` | `null` | Label for the range input. |
+| name | `string \| undefined` | `-` | The name of this input field in the form. The canonical source of the value is the text field. |
+| placeholder | `string \| undefined` | `-` | Placeholder in empty text fields |
+| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
+| updateFieldAfterValidation (JS only) | `updateFieldAfterValidation() => void` | `-` | - |
+| value | `string \| undefined` | `-` | The initial value, if any |
 
 #### Property Details
 
@@ -28,35 +32,49 @@ Component to place inside a `<w-slider>`.
 
 Contextual information for assistive technology, should it be needed
 
-- Type: `string`
-- Default: `-`
+- Type: `string | null`
+- Default: `null`
 
 ##### aria-label
 
 Label for the range input.
 
-- Type: `string`
-- Default: ``label` from `w-slider``
+- Type: `string | null`
+- Default: `null`
 
 ##### name
 
 The name of this input field in the form. The canonical source of the value is the text field.
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 ##### placeholder
 
 Placeholder in empty text fields
 
-- Type: `string`
+- Type: `string | undefined`
+- Default: `-`
+
+##### resetFormControl (JS only)
+
+
+
+- Type: `resetFormControl() => void`
+- Default: `-`
+
+##### updateFieldAfterValidation (JS only)
+
+
+
+- Type: `updateFieldAfterValidation() => void`
 - Default: `-`
 
 ##### value
 
 The initial value, if any
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `-`
 
 #### Events

package/dist/docs/slider-thumb/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/snackbar/accessibility.md

@@ -0,0 +1,20 @@
+## Accessibility
+
+From an accessibility perspective the snackbar component is problematic.
+
+- Since the snackbar items disappear on their own users might not even see them, especially when zoomed in.
+- The snackbar items are in practice impossible to reach with keyboard since they appear in the DOM away from the element that triggered them.
+- Important elements on the page might get hidden behind the snackbar item.
+
+A snackbar must never be the backbone of your user experience, it should only ever include information and actions that are available elsewhere.
+
+- Keep messages and actions short since the snackbar item is available only for a short time.
+- Ensure any information and action in the snackbar, such as Undo, is possible to do elsewhere.
+
+`<w-snackbar>` creates an ARIA live region so messages you add to the snackbar get announced to assistive technologies.
+
+### Keyboard behavior
+
+`<w-snackbar>` is problematic from a keyboard user perspective. We do not override the default <kbd>Tab</kbd> behavior, with the result that the focusable buttons in a snackbar item probably come first or last in the focus order, depending on what end of `<body>` you put `<w-snackbar>`. We're investigating ways to provide keyboard shortcuts for moving focus to the snackbar item, but have yet to conclude on a design.
+
+`<w-snackbar>` sets up a keyboard event listener on `document`. Pressing <kbd>Escape</kbd> while a snackbar item is open will close it. If more than one item is open the oldest one will close.

package/dist/docs/snackbar/api.md

@@ -0,0 +1,30 @@
+## `<w-snackbar>` API
+
+Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
+
+### Properties
+
+| Name | Type | Default | Summary |
+|-|-|-|-|
+| create (JS only) | `create(message: string, options: CreateSnackbarOptions = {}) => void` | `-` | Creates a snackbar item and immediately adds it to the snackbar. |
+
+### Property Details
+
+#### create (JS only)
+
+Creates a snackbar item and immediately adds it to the snackbar.
+
+By default the snackbar item automatically closes after 4 seconds (`SnackbarDuration.Short`).
+
+If you include an `action` in the options the default `duration` is
+set to 10 seconds (`SnackbarDuration.Long`) and can not be made shorter.
+
+A `duration` of 10 seconds or longer forces the close button to be visible.
+
+The default `variant` is `neutral` which does not have an icon.
+
+Set `duration` to `SnackbarDuration.Infinite` if you want a persistent message.
+
+- Type: `create(message: string, options: CreateSnackbarOptions = {}) => void`
+- Default: `-`
+

package/dist/docs/snackbar/examples.md

@@ -0,0 +1,191 @@
+## Examples
+
+### Default
+
+Snackbar uses the `neutral` variant with a short duration by default.
+
+<elements-example>
+
+```html
+<w-button data-testid="neutral-noaction">Neutral variant</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="neutral-noaction"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message");
+};
+</script>
+```
+
+</elements-example>
+
+#### With action
+
+You can include an action in the snackbar by providing a label and an onclick handler. By default the action button and close button are inline with the text.
+
+Clicking an action button automatically closes the snackbar item. If you want to prevent this call `event.preventDefault()`.
+
+You can use an action with any `variant`.
+
+<elements-example>
+
+```html
+<w-button data-testid="neutral-action">Neutral variant with action</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="neutral-action"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message", {
+        action: {
+            label: "Undo",
+            onclick(e) {
+                console.log(e);
+            }
+        }
+    });
+};
+</script>
+```
+
+</elements-example>
+
+#### With long action label
+
+By default a long label will result in the action and close buttons on a separate row. A label gets treated as long if it contains whitespace.
+
+Clicking an action button automatically closes the snackbar item. If you want to prevent this call `event.preventDefault()`.
+
+You can use an action with any `variant`.
+
+<elements-example>
+
+```html
+<w-button data-testid="neutral-longlabel">Neutral variant, long label</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="neutral-longlabel"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message", {
+        action: {
+            label: "Undo this thing",
+            onclick(e) {
+                console.log(e);
+            }
+        }
+    });
+};
+</script>
+```
+
+</elements-example>
+
+### Positive
+
+<elements-example>
+
+```html
+<w-button data-testid="positive-noaction">Positive variant</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="positive-noaction"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message", {
+        variant: "positive",
+    });
+};
+</script>
+```
+
+</elements-example>
+
+### Warning
+
+<elements-example>
+
+```html
+<w-button data-testid="warning-noaction">Warning variant</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="warning-noaction"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message", {
+        variant: "warning",
+    });
+};
+</script>
+```
+
+</elements-example>
+
+### Negative
+
+<elements-example>
+
+```html
+<w-button data-testid="negative-noaction">Negative variant</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="negative-noaction"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message", {
+        variant: "negative",
+    });
+};
+</script>
+```
+
+</elements-example>
+
+### Info
+
+<elements-example>
+
+```html
+<w-button data-testid="info-noaction">Info variant</w-button>
+
+<script>
+document.querySelector('w-button[data-testid="info-noaction"]').onclick = () => {
+    const snackbar = document.querySelector("w-snackbar");
+    snackbar.create("Snackbar message", {
+        variant: "info",
+    });
+};
+</script>
+```
+
+</elements-example>
+
+### Neutral with custom icon
+
+If you have cases not covered by the `create` API you can change the item returned by `create`.
+
+For example, here is how you can add a custom icon to the neutral variant.
+
+```ts
+const snackbar = document.querySelector<WarpSnackbar>('w-snackbar');
+
+// the default neutral variant is without an icon
+const snackbarItem = snackbar!.create('The message should be short'); 
+
+const customIcon = document.createElement('w-icon');
+customIcon.name = 'Rocket';
+customIcon.slot = 'icon';
+snackbarItem.prepend(customIcon);
+```
+
+### Create `<w-snackbar-item>` manually
+
+Alternatively you can create a `w-snackbar-item` manually and call [prepend](https://developer.mozilla.org/en-US/docs/Web/API/Element/prepend) on `<w-snackbar>`. The snackbar item handles its entire lifecycle on its own.
+
+Note that by not using `snackbar.create()` you have to create and wire up event handlers any close- and action button.
+
+```ts
+const snackbar = document.querySelector("w-snackbar");
+const item = document.createElement("w-snackbar-item");
+item.variant = "info";
+item.innerHTML = /* html */ `
+    <w-icon slot="icon" name="Rocket"></w-icon>
+    Warp speed engaged!
+`;
+snackbar.prepend(item);
+```