@warp-ds/elements 2.9.2-next.1 → 2.10.0-next.2

package/dist/docs/button/accessibility.md

@@ -1 +1,43 @@
 ## Accessibility
+
+Buttons must have a clear accessible name and should describe the action they perform.
+
+### Use Descriptive Text
+
+Prefer visible text that names the action.
+
+```html
+<w-button>Save changes</w-button>
+```
+
+Avoid vague labels when the action is not obvious from context.
+
+```html
+<!-- Avoid -->
+<w-button>OK</w-button>
+```
+
+### Icon-Only Buttons
+
+If a button does not have visible text, include text for assistive technologies in the slotted content.
+
+```html
+<w-button variant="pill">
+  <w-icon name="Close"></w-icon>
+  <span class="sr-only">Close</span>
+</w-button>
+```
+
+The accessible text should describe the action, not the icon shape.
+
+### Disabled Buttons
+
+Avoid disabled buttons. A disabled control can prevent keyboard users from reaching it and often does not explain what must happen before the action becomes available.
+
+Prefer keeping the button available and showing validation or explanatory feedback when the user tries to continue.
+
+### Button Or Link
+
+Use a w-button for actions on the current page. Use a w-link for navigation.
+
+For backwards compatibility, if `href` is set, `w-button` renders a link with button styling. The accessible behavior is link behavior, even though the component looks like a button. This is deprecated behaviour and you should instead use the w-link component if you need to render a link that looks like a button.

package/dist/docs/button/api.md

@@ -6,36 +6,31 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| ariaValueTextLoading (JS only) | `unknown` | `-` | - |
-| autofocus | `boolean` | `false` | - |
-| button-class | `string` | `-` | **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button. |
-| disabled | `boolean` | `false` | - |
-| full-width | `boolean` | `false` | - |
-| href | `string` | `-` | - |
-| icon-only | `boolean` | `false` | - |
-| loading | `boolean` | `false` | - |
-| name | `string` | `-` | - |
-| quiet | `boolean` | `false` | **Deprecated**: Use `variant="quiet"` instead |
-| rel | `string` | `-` | - |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
-| small | `boolean` | `false` | - |
-| target | `string` | `-` | - |
-| type | [`ButtonType`](#buttontype) | `-` | - |
-| value | `string` | `-` | - |
-| variant | [`ButtonVariant`](#buttonvariant) | `-` | - |
+| autofocus | `boolean` | `false` | Focuses the button when it is first rendered. |
+| button-class | `string` | `-` | Deprecated class applied to the internal control. **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button. |
+| command | `string` | `-` | The [command HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands. |
+| commandfor | `string` | `-` | The [commandfor HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands. |
+| disabled | `boolean` | `false` | Visually disables the button. |
+| full-width | `boolean` | `false` | Makes the button fill its parent width. |
+| href | `string` | `-` | URL for rendering the button as a link. |
+| icon-only | `boolean` | `false` | Marks the button as icon-only. |
+| loading | `boolean` | `false` | Shows the loading state. |
+| name | `string` | `-` | Form control name. |
+| quiet | `boolean` | `false` | Deprecated quiet visual treatment flag. **Deprecated**: Use `variant="quiet"` instead |
+| rel | `string` | `-` | Link relationship. |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | Shadow root configuration. |
+| small | `boolean` | `false` | Renders the compact button size. |
+| target | `string` | `-` | Link browsing context. |
+| type | [`ButtonType`](#buttontype) | `-` | Native button type. |
+| value | `string` | `-` | Form control value. |
+| variant | [`ButtonVariant`](#buttonvariant) | `-` | Visual style of the button. |
 
 ### Property Details
 
-#### ariaValueTextLoading (JS only)
-
-
-
-- Type: `unknown`
-- Default: `-`
-
 #### autofocus
 
-
+Focuses the button when it is first rendered.
+Applies only when the component renders a native button. Link buttons with `href` do not autofocus through this component.
 
 - Type: `boolean`
 - Default: `false`
@@ -44,49 +39,70 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button.
 
+Deprecated class applied to the internal control
+This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the button appearance.
 
+- Type: `string`
+- Default: `-`
+
+#### command
+
+The [command HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands.
 
 - Type: `string`
 - Default: `-`
 
-#### disabled
+#### commandfor
 
+The [commandfor HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands.
 
+- Type: `string`
+- Default: `-`
+
+#### disabled
+
+Visually disables the button.
+Disabled buttons are discouraged because they can hide the reason an action is unavailable.
 
 - Type: `boolean`
 - Default: `false`
 
 #### full-width
 
-
+Makes the button fill its parent width.
+Useful in narrow layouts where the button should span the available inline space.
 
 - Type: `boolean`
 - Default: `false`
 
 #### href
 
-
+URL for rendering the button as a link.
+When set, the component renders `w-link` instead of a native `button`.
 
 - Type: `string`
 - Default: `-`
 
 #### icon-only
 
-
+Marks the button as icon-only.
+Use this when the button has no visible text. Include accessible text in the slotted content so the internal button has a name.
 
 - Type: `boolean`
 - Default: `false`
 
 #### loading
 
-
+Shows the loading state.
+Use after the user has triggered an action and the action is in progress.
 
 - Type: `boolean`
 - Default: `false`
 
 #### name
 
-
+Form control name.
+Used when the button participates in form handling.
 
 - Type: `string`
 - Default: `-`
@@ -95,56 +111,64 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 **Deprecated**: Use `variant="quiet"` instead
 
-
+Deprecated quiet visual treatment flag
+Use `variant="quiet"` instead.
 
 - Type: `boolean`
 - Default: `false`
 
 #### rel
 
-
+Link relationship.
+Passed to the rendered link when `href` is set. If `target="_blank"` is set and `rel` is omitted, `noopener` is used.
 
 - Type: `string`
 - Default: `-`
 
 #### shadowRootOptions (JS only)
 
-
+Shadow root configuration.
+Delegates focus from the host to the internal control.
 
 - Type: `object`
 - Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
 
 #### small
 
-
+Renders the compact button size.
+Use this in dense layouts where the default button size is too large.
 
 - Type: `boolean`
 - Default: `false`
 
 #### target
 
-
+Link browsing context.
+Passed to the rendered link when `href` is set.
 
 - Type: `string`
 - Default: `-`
 
 #### type
 
-
+Native button type.
+Controls whether the internal button behaves as a regular button, submits a form, or resets a form. Defaults to `button`.
 
 - Type: [`ButtonType`](#buttontype)
 - Default: `-`
 
 #### value
 
-
+Form control value.
+Used with `name` when the button participates in form handling. Resets to its initial value when the form is reset.
 
 - Type: `string`
 - Default: `-`
 
 #### variant
 
-
+Visual style of the button.
+Defaults to `secondary`. Use the variant that matches the action priority, risk, and placement.
 
 - Type: [`ButtonVariant`](#buttonvariant)
 - Default: `-`