@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/button.md

@@ -0,0 +1,200 @@
+<!-- index: ./index.md -->
+# button
+
+`data-ui="button"` · Button, link button, icon button and toggle button.
+
+## Import
+
+```ts
+import {
+  provideButtonDefaults,
+  SlButton,
+  SlButtonEnd,
+  SlButtonLink,
+  SlButtonStart,
+  SlIconButton,
+  SlToggleButton,
+} from '@slotted/angular/button';
+```
+
+Selector: `button[slButton], [slButtonStart], [slButtonEnd]` · exportAs: `slButton`
+
+Selector: `a[slButtonLink]` · exportAs: `slButtonLink`
+
+Selector: `button[slIconButton]` · exportAs: `slIconButton`
+
+Selector: `button[slToggleButton]` · exportAs: `slToggleButton`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+
+@Component({
+  selector: 'app-button-basic',
+  imports: [SlButton],
+  template: `<button slButton type="button" (click)="save()">Save changes</button>`,
+})
+export class ButtonBasic {
+  save(): void {
+    console.log('saved');
+  }
+}
+```
+
+## Anatomy
+
+### button
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the button element you write | yes |
+| `start` | the element you mark with slButtonStart | no |
+| `label` | span | yes |
+| `end` | the element you mark with slButtonEnd | no |
+| `indicator` | span with role="progressbar" | no |
+
+### buttonLink
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the anchor element you write | yes |
+| `start` | the element you mark with slButtonStart | no |
+| `label` | span | yes |
+| `end` | the element you mark with slButtonEnd | no |
+
+### iconButton
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the button element you write | yes |
+| `icon` | span | yes |
+| `indicator` | span with role="progressbar" | no |
+
+### toggleButton
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the button element you write | yes |
+| `start` | the element you mark with slButtonStart | no |
+| `label` | span | yes |
+| `end` | the element you mark with slButtonEnd | no |
+| `indicator` | span with role="progressbar" | no |
+
+## Props
+
+### button
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `accent \| secondary \| success \| warning \| danger` | accent | SlButton | The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does. |
+| `variant` | `solid \| outline \| ghost` | solid | SlButton | How the tone is painted: solid, outline or ghost. |
+| `size` | `sm \| md \| lg` | md | SlButton | The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height. |
+| `start` | `[slButtonStart]` | — | SlButton | Content projected before the label, such as an icon, on the element you mark with slButtonStart. It mirrors in a right-to-left document. |
+| `end` | `[slButtonEnd]` | — | SlButton | Content projected after the label, on the element you mark with slButtonEnd. It mirrors in a right-to-left document. |
+| `fullWidth` | `boolean` | false | SlButton | Fills the inline size of the container. |
+| `disabled` | `boolean` | false | SlButton | Refuses the action and marks the control unavailable. On its own, it sets the native disabled property, which also removes the control from the tab sequence. |
+| `focusableWhenDisabled` | `boolean` | false | SlButton | Keeps a disabled control in the tab sequence: aria-disabled replaces the native property, and activation is still refused. |
+| `loading` | `boolean` | false | SlButton | Refuses activation, keeps focus, and shows a progress indicator named by messages.loading. |
+| `loadingDelay` | `number` | 0 | SlButton | Milliseconds before the indicator appears. Activation is refused from the start of the wait. |
+| `messages` | `Partial<ButtonMessages>` | — | SlButton | Overrides for the strings of the active locale, key by key. loading names the progress indicator. |
+| `type` | `button \| submit \| reset` | button | SlButton | The native button type. Set submit only for a button that submits its form. |
+| `provideButtonDefaults` | `(defaults: ButtonDefaults) => Provider` | — | SlButton | Sets the default size, tone and variant of every button under the injector, SlButtonLink, SlIconButton and SlToggleButton included. An explicit input wins, and an axis left unset keeps each member’s own default. |
+
+### buttonLink
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `href` | `string` | — | SlButtonLink | The destination. A disabled SlButtonLink does not render it. |
+| `tone` | `accent \| secondary \| success \| warning \| danger` | accent | SlButtonLink | The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does. |
+| `variant` | `solid \| outline \| ghost` | solid | SlButtonLink | How the tone is painted: solid, outline or ghost. |
+| `size` | `sm \| md \| lg` | md | SlButtonLink | The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height. |
+| `start` | `[slButtonStart]` | — | SlButtonLink | Content projected before the label, such as an icon, on the element you mark with slButtonStart. It mirrors in a right-to-left document. |
+| `end` | `[slButtonEnd]` | — | SlButtonLink | Content projected after the label, on the element you mark with slButtonEnd. It mirrors in a right-to-left document. |
+| `fullWidth` | `boolean` | false | SlButtonLink | Fills the inline size of the container. |
+| `disabled` | `boolean` | false | SlButtonLink | Removes the href and refuses activation. The link stays focusable with role="link" and aria-disabled. |
+
+### iconButton
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `aria-label \| aria-labelledby` | `string` | required | SlIconButton | The accessible name. Required, because an icon supplies no text. |
+| `tone` | `accent \| secondary \| success \| warning \| danger` | secondary | SlIconButton | The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does. |
+| `variant` | `solid \| outline \| ghost` | ghost | SlIconButton | How the tone is painted: solid, outline or ghost. |
+| `size` | `sm \| md \| lg` | md | SlIconButton | The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height. |
+| `shape` | `square \| circle` | square | SlIconButton | The corners of the control: square keeps the radius of the control scale, circle rounds it fully. Both are as wide as they are tall. |
+| `disabled` | `boolean` | false | SlIconButton | Refuses the action and marks the control unavailable. On its own, it sets the native disabled property, which also removes the control from the tab sequence. |
+| `focusableWhenDisabled` | `boolean` | false | SlIconButton | Keeps a disabled control in the tab sequence: aria-disabled replaces the native property, and activation is still refused. |
+| `loading` | `boolean` | false | SlIconButton | Refuses activation, keeps focus, and shows a progress indicator named by messages.loading. |
+| `loadingDelay` | `number` | 0 | SlIconButton | Milliseconds before the indicator appears. Activation is refused from the start of the wait. |
+| `messages` | `Partial<ButtonMessages>` | — | SlIconButton | Overrides for the strings of the active locale, key by key. loading names the progress indicator. |
+| `pressed` | `boolean` | — | SlIconButton | The pressed state, controlled. Binding it makes the button a toggle whose value you own. |
+| `defaultPressed` | `boolean` | — | SlIconButton | The initial pressed state when the button owns it. Binding it makes the button a toggle. |
+| `pressedChange` | `ChangeRequest<boolean>` | — | SlIconButton | Emits the request: value, previous value, reason (pointer or keyboard), event and cancel(). |
+| `type` | `button \| submit \| reset` | button | SlIconButton | The native button type. Set submit only for a button that submits its form. |
+
+### toggleButton
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `accent \| secondary \| success \| warning \| danger` | secondary | SlToggleButton | The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does. |
+| `variant` | `solid \| outline \| ghost` | outline | SlToggleButton | How the tone is painted: solid, outline or ghost. |
+| `size` | `sm \| md \| lg` | md | SlToggleButton | The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height. |
+| `start` | `[slButtonStart]` | — | SlToggleButton | Content projected before the label, such as an icon, on the element you mark with slButtonStart. It mirrors in a right-to-left document. |
+| `end` | `[slButtonEnd]` | — | SlToggleButton | Content projected after the label, on the element you mark with slButtonEnd. It mirrors in a right-to-left document. |
+| `fullWidth` | `boolean` | false | SlToggleButton | Fills the inline size of the container. |
+| `disabled` | `boolean` | false | SlToggleButton | Refuses the action and marks the control unavailable. On its own, it sets the native disabled property, which also removes the control from the tab sequence. |
+| `focusableWhenDisabled` | `boolean` | false | SlToggleButton | Keeps a disabled control in the tab sequence: aria-disabled replaces the native property, and activation is still refused. |
+| `loading` | `boolean` | false | SlToggleButton | Refuses activation, keeps focus, and shows a progress indicator named by messages.loading. |
+| `loadingDelay` | `number` | 0 | SlToggleButton | Milliseconds before the indicator appears. Activation is refused from the start of the wait. |
+| `messages` | `Partial<ButtonMessages>` | — | SlToggleButton | Overrides for the strings of the active locale, key by key. loading names the progress indicator. |
+| `pressed` | `boolean` | — | SlToggleButton | The pressed state, controlled. Binding it makes you the owner of the value. |
+| `defaultPressed` | `boolean` | false | SlToggleButton | The initial pressed state when the button owns it, read once. |
+| `pressedChange` | `ChangeRequest<boolean>` | — | SlToggleButton | Emits the request: value, previous value, reason (pointer or keyboard), event and cancel(). |
+| `type` | `button \| submit \| reset` | button | SlToggleButton | The native button type. Set submit only for a button that submits its form. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `accent`, `secondary` |
+| `variant` | `solid`, `outline`, `ghost` | `solid`, `ghost`, `outline` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `shape` | `square`, `circle` | `square` |
+
+## Rules
+
+- SlButton applies to the button element in your template, so Space, Enter, focus, form submission and the disabled state come from the platform. The visible label supplies the accessible name.
+- While loading, the indicator is a progress bar named by messages.loading, and the button announces aria-disabled while it keeps focus. React Aria’s pending button and Primer’s loading button use the same pattern. aria-busy is not set: screen readers do not announce it reliably on a button, and one mechanism already carries the state.
+- Where motion is allowed, the indicator is not drawn: once loadingDelay has passed, a band in the button’s own ink sweeps behind the label and the icon, which stay visible. With reduced motion or forced colours, the indicator is a ring drawn in the start or end icon’s box; a button with neither draws it over the label, which drops to zero opacity but stays in the accessibility tree and in the layout, so the accessible name survives the wait and the button keeps its size.
+- loading refuses activation on a capture-phase listener, before any click handler in your template, so a submit button cannot submit its form twice.
+- focusableWhenDisabled keeps a disabled button reachable. Use it when the button has a tooltip or an explanation a keyboard user needs, such as inside a toolbar. A reachable disabled button uses muted text on the subtle neutral background, at a contrast of 4.5:1 or more; a natively disabled button keeps the disabled grey.
+- SlButton has no render input: it applies to the element you write, so writing a different element replaces it.
+- A projected start or end icon repeats the label, so mark it aria-hidden. slGlyph sets aria-hidden itself.
+- SlButtonLink applies to an anchor, so it is announced as a link and activates on Enter. Space does not activate it, as it does not activate any link.
+- routerLink works on the same anchor and writes its href. Do not also set href.
+- A disabled SlButtonLink renders no href. An anchor that kept its destination and only blocked click would still navigate on a middle click or a modified click.
+- A disabled SlButtonLink stays in the tab sequence with role="link" and aria-disabled, so a keyboard user can discover that it is unavailable.
+- The accessible name is required: the development build throws when neither aria-label nor aria-labelledby is present, because a template cannot make an attribute mandatory.
+- aria-pressed is rendered only when pressed or defaultPressed is bound, so a plain icon button does not announce a toggle state it does not have.
+- Keep the name the same in both pressed states. The APG toggle button pattern announces the state beside an unchanging label.
+- A pressed icon button uses the selected colours of the theme — accent text on the accent selection background, inside the accent edge — whatever its tone and variant. On hover it uses the hover step of that background, not the neutral hover of an unpressed button.
+- The control is as wide as it is tall, at the control height, and never smaller than the WCAG 2.2 minimum target of 24 by 24 CSS pixels at any density.
+- Add a tooltip when the icon alone does not say what the action does. The accessible name does not replace a visible label.
+- SlToggleButton applies to a native button and sets aria-pressed, so it is announced as a toggle button and activates on Space and Enter.
+- Keep the label the same in both states: "Mute" stays "Mute" and the state is announced beside it. When the label has to change, use SlButton.
+- There is no [(pressed)]: a two-way binding carries only the value, and the change request also carries the reason and cancel(). One output, pressedChange, carries the whole request.
+- The reason is pointer when the click reports a click count and keyboard when it reports none, because a native button fires the same click for a pointer, Space and Enter.
+- Calling preventDefault on the click refuses the activation, and the pressed state does not change.
+- Use a checkbox, not SlToggleButton, for a value a form submits.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-font-weight`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-letter-spacing`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-loop`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-line-height-sm`, `--slotted-radius-full`, `--slotted-space-2`, `--slotted-target-min`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-text`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-solid-active`, `--slotted-tone-danger-solid-hover`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-solid-active`, `--slotted-tone-secondary-solid-hover`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-text`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-solid-active`, `--slotted-tone-success-solid-hover`, `--slotted-tone-success-text`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-solid-active`, `--slotted-tone-warning-solid-hover`, `--slotted-tone-warning-text`
+
+## Examples
+
+See [button.examples.md](./button.examples.md).