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

package/docs/dialog.md

@@ -0,0 +1,217 @@
+<!-- index: ./index.md -->
+# dialog
+
+`data-ui="dialog"` · Modal dialog and alert dialog.
+
+## Import
+
+```ts
+import { SlDialog, SlDialogBody, SlDialogClose, SlDialogDescription, SlDialogFooter, SlDialogHeader, SlDialogTitle, SlDialogTrigger, provideDialogDefaults } from '@slotted/angular/dialog';
+```
+
+Selector: `sl-dialog, [slDialogTrigger], [slDialogHeader], [slDialogTitle], [slDialogDescription], [slDialogBody], [slDialogFooter], [slDialogClose]` · exportAs: `slDialog, slDialogTrigger, slDialogHeader, slDialogTitle, slDialogClose`
+
+```ts
+import { SlAlertDialog, SlAlertDialogAction, SlAlertDialogCancel, SlAlertDialogIcon, SlDialogBody, SlDialogDescription, SlDialogFooter, SlDialogHeader, SlDialogTitle, SlDialogTrigger } from '@slotted/angular/dialog';
+```
+
+Selector: `sl-alert-dialog, [slDialogTrigger], [slAlertDialogIcon], [slAlertDialogCancel], [slAlertDialogAction]` · exportAs: `slAlertDialog, slAlertDialogCancel, slAlertDialogAction`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import {
+  SlDialog,
+  SlDialogBody,
+  SlDialogClose,
+  SlDialogDescription,
+  SlDialogFooter,
+  SlDialogHeader,
+  SlDialogTitle,
+  SlDialogTrigger,
+} from '@slotted/angular/dialog';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-dialog-basic',
+  imports: [
+    SlButton,
+    SlDialog,
+    SlDialogBody,
+    SlDialogClose,
+    SlDialogDescription,
+    SlDialogFooter,
+    SlDialogHeader,
+    SlDialogTitle,
+    SlDialogTrigger,
+    SlField,
+    SlFieldLabel,
+    SlInline,
+    SlText,
+    SlTextField,
+    SlTextFieldInput,
+  ],
+  template: `
+    <div slInline align="center" [gap]="3">
+      <span slText size="sm">{{ email() }}</span>
+      <button slButton size="sm" tone="secondary" variant="outline" [slDialogTrigger]="dialog">
+        Edit billing email
+      </button>
+      <sl-dialog #dialog="slDialog" [open]="open()" (openChange)="toggle($event)">
+        <header slDialogHeader>
+          <h2 slDialogTitle>Billing email</h2>
+          <p slDialogDescription>
+            Invoices and payment receipts for Northwind Traders go to this address.
+          </p>
+          <button slDialogClose></button>
+        </header>
+        <div slDialogBody>
+          <div slField>
+            <label slFieldLabel>Email</label>
+            <div slTextField>
+              <input
+                slTextFieldInput
+                type="email"
+                [value]="draft()"
+                (valueChange)="draft.set($event.value)"
+              />
+            </div>
+          </div>
+        </div>
+        <footer slDialogFooter>
+          <button slButton variant="ghost" tone="secondary" (click)="open.set(false)">
+            Cancel
+          </button>
+          <button slButton (click)="save()">Save</button>
+        </footer>
+      </sl-dialog>
+    </div>
+  `,
+})
+export class DialogBasic {
+  readonly open = signal(false);
+  readonly email = signal('ap@northwindtraders.com');
+  readonly draft = signal(this.email());
+
+  toggle(next: boolean): void {
+    if (next) this.draft.set(this.email());
+    this.open.set(next);
+  }
+
+  save(): void {
+    this.email.set(this.draft());
+    this.open.set(false);
+  }
+}
+```
+
+## Anatomy
+
+### dialog
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, in a portal; the sl-dialog host stays where it is written | yes |
+| `trigger` | your own element, with slDialogTrigger on it | no |
+| `backdrop` | div | yes |
+| `viewport` | div | yes |
+| `content` | div | yes |
+| `header` | your own header, with slDialogHeader on it | no |
+| `title` | your own heading, with slDialogTitle on it | no |
+| `description` | your own element, with slDialogDescription on it | no |
+| `body` | your own element, with slDialogBody on it | no |
+| `footer` | your own footer, with slDialogFooter on it | no |
+| `close` | your own button, with slDialogClose on it | no |
+| `fullscreen` | button | no |
+
+### alertDialog
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, in a portal; the sl-dialog host stays where it is written | yes |
+| `trigger` | your own element, with slDialogTrigger on it | no |
+| `backdrop` | div | yes |
+| `viewport` | div | yes |
+| `content` | div | yes |
+| `header` | your own header, with slDialogHeader on it | no |
+| `title` | your own heading, with slDialogTitle on it | no |
+| `description` | your own element, with slDialogDescription on it | yes |
+| `body` | your own element, with slDialogBody on it | no |
+| `footer` | your own footer, with slDialogFooter on it | no |
+| `icon` | your own element, with slAlertDialogIcon on it | no |
+| `cancel` | your own button, with slAlertDialogCancel on it | yes |
+| `action` | your own button, with slAlertDialogAction on it | yes |
+
+## Props
+
+See [dialog.props.md](./dialog.props.md).
+
+## Events
+
+### dialog
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(openChangeRequest)` | `DialogChangeRequest` | Before the dialog opens or closes, whatever caused it. The request carries the new value, the previous value, the reason (pointer, keyboard, dismiss, escape, outsidePress, back, submit or programmatic), the result of the close, the originating event, and cancel(), which keeps the dialog as it is. One handler therefore guards the ✕, Escape, a press outside, the way back and close() together. |
+| `(openChange)` | `boolean` | After the open state changed, so a template can bind [(open)]. It carries the new state only; the reason is on (openChangeRequest). |
+| `(fullscreenChangeRequest)` | `DialogFullscreenRequest` | Before the panel expands to the whole layer or is restored. The request carries the new value, the previous value, the reason (pointer, keyboard or programmatic), the originating event, and cancel(), which keeps the panel as it is. |
+| `(fullscreenChange)` | `boolean` | After the expanded state changed, so a template can bind [(fullscreen)]. |
+| `(closed)` | `string \| undefined` | Once the dialog has closed, with the result of the close: the value of the button that closed it, the argument of close(result), or undefined. |
+
+### alertDialog
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(openChangeRequest)` | `DialogChangeRequest` | Before the dialog opens or closes, whatever caused it. The request carries the new value, the previous value, the reason (pointer, keyboard, dismiss, escape, outsidePress, back, submit or programmatic), the result of the close, the originating event, and cancel(), which keeps the dialog as it is. One handler therefore guards the ✕, Escape, a press outside, the way back and close() together. |
+| `(openChange)` | `boolean` | After the open state changed, so a template can bind [(open)]. It carries the new state only; the reason is on (openChangeRequest). |
+| `(fullscreenChangeRequest)` | `DialogFullscreenRequest` | Before the panel expands to the whole layer or is restored. The request carries the new value, the previous value, the reason (pointer, keyboard or programmatic), the originating event, and cancel(), which keeps the panel as it is. |
+| `(fullscreenChange)` | `boolean` | After the expanded state changed, so a template can bind [(fullscreen)]. |
+| `(closed)` | `string \| undefined` | Once the dialog has closed, with the result of the close: the value of the button that closed it, the argument of close(result), or undefined. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg`, `xl`, `full` | `md`, `sm` |
+| `placement` | `center`, `top` | `center` |
+| `scroll` | `content`, `viewport` | `content` |
+| `surface` | `panel`, `plain` | `panel` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `fullScreen` | `never`, `narrow`, `always` | `narrow`, `never` |
+| `modal` | `true`, `false` | `true` |
+| `escape` | `close`, `none` | `close` |
+| `outsidePress` | `close`, `none` | `close`, `none` |
+| `back` | `close`, `none` | `close` |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `danger` |
+| `initialFocus` | `first`, `container`, `cancel` | `first`, `cancel` |
+
+## Rules
+
+- sl-dialog follows the WAI-ARIA dialog (modal) pattern. While a modal dialog is open, Tab and Shift+Tab move through the focusable elements inside it and wrap from the last to the first and back. Escape closes the topmost dialog only; a dialog that refuses the close keeps the Escape from reaching the dialog beneath it.
+- The panel carries role="dialog", aria-labelledby pointing at the title and aria-describedby pointing at the description, each only while that part is rendered. An aria-label of your own on sl-dialog moves to the panel and replaces aria-labelledby.
+- aria-modal="true" is written only while the dialog is modal. A modal dialog makes everything outside it inert, which removes the page from the accessibility tree and from the pointer, and locks the page scroll. [modal]="false" does none of this and writes no aria-modal.
+- When the dialog opens, focus moves to its first focusable element, to the element initialFocus names, or to the panel itself with initialFocus="container", for content that is read before it is used. When it closes, focus returns to the element that had it when the dialog opened, or to the element finalFocus names. If that element has left the document, focus goes to its nearest ancestor still in the document.
+- Containment, inertness and Escape are implemented in JavaScript rather than with the native dialog element, so every overlay of the library shares one stacking order: a select opened inside a dialog paints above it. Without JavaScript, there is no dialog.
+- The close button’s target is at least 24 by 24 pixels, and its mark is drawn from a glyph, not a character.
+- The panel has a border as well as a shadow, so its edge stays visible under forced colours, where shadows are removed and the scrim becomes opaque.
+- sl-alert-dialog follows the WAI-ARIA alert dialog pattern: the modal dialog pattern with role="alertdialog" and a required description. The keyboard is the same: Tab and Shift+Tab wrap inside the panel, and Escape closes it.
+- aria-describedby is required. sl-alert-dialog throws an error when no slDialogDescription is rendered while it is open, so a confirmation is never announced without the sentence that says what it does.
+- Focus starts on slAlertDialogCancel, the least destructive answer, as the pattern advises for a step that cannot be undone easily.
+- A press outside never closes an alert dialog, and it is always modal. Escape closes it, which answers with the cancel; set escape="none" when cancelling is not safe either.
+- There is no close part: the reader answers with the cancel or the action. slDialogClose inside sl-alert-dialog throws an error.
+- The tone is carried by the icon’s shape as well as by its colour, so it survives forced colours and readers who cannot tell the colours apart.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-icon-size-lg`, `--slotted-control-inner-size-lg`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-dialog-body-color`, `--slotted-dialog-border-color`, `--slotted-dialog-close-active-background`, `--slotted-dialog-close-color`, `--slotted-dialog-close-hover-background`, `--slotted-dialog-color`, `--slotted-dialog-description-color`, `--slotted-dialog-footer-surface`, `--slotted-dialog-measure`, `--slotted-dialog-radius`, `--slotted-dialog-rule-color`, `--slotted-dialog-scrim`, `--slotted-dialog-surface`, `--slotted-dialog-title-color`, `--slotted-dialog-title-font-family`, `--slotted-duration-long`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-xl`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-scrim`, `--slotted-shadow-lg`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-z-index-overlay`
+
+## Examples
+
+See [dialog.examples.md](./dialog.examples.md).

package/docs/dialog.props.md

@@ -0,0 +1,63 @@
+<!-- index: ./index.md -->
+# dialog
+
+`data-ui="dialog"` · Modal dialog and alert dialog.
+
+## Props
+
+### dialog
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | false | sl-dialog, sl-alert-dialog | Whether the dialog is open. A model: bind [(open)] to a signal, whose initial value is the starting state. (openChangeRequest) can refuse a change before it is written. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | md | sl-dialog, provideDialogDefaults | The maximum width of the panel: 24rem, 32rem, 42rem, 56rem, or the whole layer less its padding. For another width, set --slotted-dialog-measure. |
+| `placement` | `'center' \| 'top'` | center | sl-dialog, sl-alert-dialog, provideDialogDefaults | Where the panel sits in the layer. Use top for content that grows while the reader types, so the panel does not move with each new line. |
+| `scroll` | `'content' \| 'viewport'` | content | sl-dialog, sl-alert-dialog, provideDialogDefaults | What scrolls when the content is long. content keeps the panel inside the layer and scrolls the body, so the actions stay on screen; viewport lets the panel grow and scrolls the layer. With content, the layer still scrolls when the header and footer alone are taller than it. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | sl-dialog, sl-alert-dialog, provideDialogDefaults | When the layer is in the document. active renders it while open and removes it after the closing animation, lazy renders it on the first open and keeps it, eager renders it from the start and hides it with content-visibility and inert while closed. |
+| `escape` | `'close' \| 'none'` | close | sl-dialog, sl-alert-dialog, provideDialogDefaults | Whether Escape asks the dialog to close. Escape reaches the topmost dialog only. |
+| `loading` | `boolean` | false | sl-dialog, sl-alert-dialog | Marks the body with aria-busy and gives it a minimum height while the content is on its way. The header, the close button and Escape stay available. |
+| `messages` | `Partial<DialogMessages>` | — | sl-dialog, sl-alert-dialog | Replaces words of the language in force, key by key: the accessible names of the close and full-screen buttons (close, fullScreen). An aria-label on slDialogClose takes precedence. |
+| `initialFocus` | `'first' \| 'container' \| 'cancel' \| HTMLElement \| false` | first | sl-dialog | Where focus goes when the dialog opens: the first focusable element, the panel itself (container), the cancel part, an element such as a template reference to an input, or nowhere (false). Use container for content that is read before it is used, such as a list or a table. |
+| `finalFocus` | `HTMLElement \| false` | — | sl-dialog, sl-alert-dialog | Where focus goes when the dialog closes. Unset, focus returns to the element that had it when the dialog opened, usually the trigger. false leaves focus where it is. |
+| `value` | `string` | — | slDialogClose, slAlertDialogCancel, slAlertDialogAction | The result this button closes the dialog with, read from request.result in (openChangeRequest) and from (closed). slAlertDialogCancel defaults to "cancel" and slAlertDialogAction to "confirm". |
+| `modal` | `boolean` | true | sl-dialog, provideDialogDefaults | Whether the page behind is inert, its scroll locked and focus kept inside the panel. false does none of this, paints no scrim, lets the pointer reach the page and writes no aria-modal. |
+| `outsidePress` | `'close' \| 'none'` | close | sl-dialog, provideDialogDefaults | Whether a press outside the panel asks the dialog to close. sl-alert-dialog fixes it at none. |
+| `back` | `'close' \| 'none'` | close | sl-dialog, provideDialogDefaults | Whether the browser’s way back, a back button or a phone’s back gesture, closes a modal dialog instead of leaving the page. Each open modal dialog adds one history entry, and the close request carries the reason back. |
+| `surface` | `'panel' \| 'plain'` | panel | sl-dialog, provideDialogDefaults | Whether sl-dialog paints the panel. plain removes the background, border, radius, shadow, rows and padding, and keeps the portal, the scrim, focus handling and the dismissal policy, for a panel of your own such as a slCard or an image viewer. A plain panel does not keep its footer on screen for a long body. |
+| `fullScreen` | `'never' \| 'narrow' \| 'always'` | narrow | sl-dialog, provideDialogDefaults | When the panel fills the whole layer, without margins or radius. narrow does so while the layer is narrower than 480 pixels, measured with a container query on the layer. |
+| `fullscreenToggle` | `boolean` | false | sl-dialog | Adds a button to slDialogHeader that expands the panel to the whole layer and restores it, for content the reader wants more room for. |
+| `fullscreen` | `boolean` | false | sl-dialog | Whether the panel is expanded by the toggle. A model: bind [(fullscreen)] to a signal, whose initial value is the starting state. |
+| `directives on your own elements` | `attribute selector` | — | slDialogTrigger, slDialogHeader, slDialogTitle, slDialogDescription, slDialogBody, slDialogFooter, slDialogClose, slAlertDialogIcon, slAlertDialogCancel, slAlertDialogAction | Every part except the layer is a directive on an element you write, so the trigger, the cancel and the action can be a slButton. |
+| `exportAs` | `'slDialog' \| 'slAlertDialog'` | — | sl-dialog, sl-alert-dialog | A template reference variable reaches the instance. [slDialogTrigger]="dialog" links a trigger to it from anywhere in the same template. |
+| `openDialog(), close(result), focus()` | `() => void` | — | the instance | Open the dialog, close it with a result, or move focus into the panel, from the template or from code. There is no service that opens a component as a dialog: render sl-dialog in the template, under @if when it should exist only while open. |
+| `--slotted-dialog-measure` | `length` | from size | the root part | The maximum width of the panel, for a width the five sizes do not hold, such as a two-column form at 46rem. Set it with a style attribute on one dialog, with a rule for a region, or once in the theme. It takes precedence over size. |
+| `container` | `Element \| null` | — | sl-dialog, sl-alert-dialog | The element this dialog is rendered into, instead of the shared portal root. The layer takes the theme, scheme, density and direction of the place where sl-dialog is written, with or without a trigger. |
+| `provideDialogDefaults()` | `{ size, placement, scroll, surface, mount, fullScreen, modal, escape, outsidePress, back }` | — | an injector | Sets these ten values once for every dialog under the injector, through DIALOG_DEFAULTS. A value set on one dialog takes precedence. |
+
+### alertDialog
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | false | sl-dialog, sl-alert-dialog | Whether the dialog is open. A model: bind [(open)] to a signal, whose initial value is the starting state. (openChangeRequest) can refuse a change before it is written. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | sm | sl-alert-dialog | The maximum width of the panel. sl-alert-dialog defaults to sm, 24rem. |
+| `placement` | `'center' \| 'top'` | center | sl-dialog, sl-alert-dialog, provideDialogDefaults | Where the panel sits in the layer. Use top for content that grows while the reader types, so the panel does not move with each new line. |
+| `scroll` | `'content' \| 'viewport'` | content | sl-dialog, sl-alert-dialog, provideDialogDefaults | What scrolls when the content is long. content keeps the panel inside the layer and scrolls the body, so the actions stay on screen; viewport lets the panel grow and scrolls the layer. With content, the layer still scrolls when the header and footer alone are taller than it. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | sl-dialog, sl-alert-dialog, provideDialogDefaults | When the layer is in the document. active renders it while open and removes it after the closing animation, lazy renders it on the first open and keeps it, eager renders it from the start and hides it with content-visibility and inert while closed. |
+| `escape` | `'close' \| 'none'` | close | sl-dialog, sl-alert-dialog, provideDialogDefaults | Whether Escape asks the dialog to close. Escape reaches the topmost dialog only. |
+| `loading` | `boolean` | false | sl-dialog, sl-alert-dialog | Marks the body with aria-busy and gives it a minimum height while the content is on its way. The header, the close button and Escape stay available. |
+| `messages` | `Partial<DialogMessages>` | — | sl-dialog, sl-alert-dialog | Replaces words of the language in force, key by key: the accessible names of the close and full-screen buttons (close, fullScreen). An aria-label on slDialogClose takes precedence. |
+| `initialFocus` | `'first' \| 'container' \| 'cancel' \| HTMLElement \| false` | cancel | sl-alert-dialog | Where focus goes when the dialog opens. The default, cancel, is the least destructive answer. |
+| `finalFocus` | `HTMLElement \| false` | — | sl-dialog, sl-alert-dialog | Where focus goes when the dialog closes. Unset, focus returns to the element that had it when the dialog opened, usually the trigger. false leaves focus where it is. |
+| `value` | `string` | — | slDialogClose, slAlertDialogCancel, slAlertDialogAction | The result this button closes the dialog with, read from request.result in (openChangeRequest) and from (closed). slAlertDialogCancel defaults to "cancel" and slAlertDialogAction to "confirm". |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | danger | sl-alert-dialog | The kind of decision. It sets the mark slAlertDialogIcon draws and its colour. |
+| `modal` | `boolean` | true | sl-alert-dialog | Fixed: an alert dialog is always modal. |
+| `outsidePress` | `'close' \| 'none'` | none | sl-alert-dialog | Fixed: a press outside never closes an alert dialog. |
+| `back` | `'close' \| 'none'` | close | sl-alert-dialog | Whether the browser’s way back cancels the confirmation, as Escape does. The close request carries the reason back. |
+| `surface` | `'panel' \| 'plain'` | panel | sl-alert-dialog | Whether sl-alert-dialog paints the panel. plain removes the paint and keeps the behaviour. |
+| `fullScreen` | `'never' \| 'narrow' \| 'always'` | never | sl-alert-dialog | When the panel fills the whole layer. sl-alert-dialog keeps its margins at every width by default. |
+| `directives on your own elements` | `attribute selector` | — | slDialogTrigger, slDialogHeader, slDialogTitle, slDialogDescription, slDialogBody, slDialogFooter, slDialogClose, slAlertDialogIcon, slAlertDialogCancel, slAlertDialogAction | Every part except the layer is a directive on an element you write, so the trigger, the cancel and the action can be a slButton. |
+| `exportAs` | `'slDialog' \| 'slAlertDialog'` | — | sl-dialog, sl-alert-dialog | A template reference variable reaches the instance. [slDialogTrigger]="dialog" links a trigger to it from anywhere in the same template. |
+| `openDialog(), close(result), focus()` | `() => void` | — | the instance | Open the dialog, close it with a result, or move focus into the panel, from the template or from code. There is no service that opens a component as a dialog: render sl-dialog in the template, under @if when it should exist only while open. |
+| `--slotted-dialog-measure` | `length` | from size | the root part | The maximum width of the panel, for a width the five sizes do not hold, such as a two-column form at 46rem. Set it with a style attribute on one dialog, with a rule for a region, or once in the theme. It takes precedence over size. |
+| `container` | `Element \| null` | — | sl-dialog, sl-alert-dialog | The element this dialog is rendered into, instead of the shared portal root. The layer takes the theme, scheme, density and direction of the place where sl-dialog is written, with or without a trigger. |
+| `provideDialogDefaults()` | `{ size, placement, scroll, surface, mount, fullScreen, modal, escape, outsidePress, back }` | — | an injector | Sets these ten values once for every dialog under the injector, through DIALOG_DEFAULTS. A value set on one dialog takes precedence. |

package/docs/divider.json

@@ -0,0 +1,148 @@
+{
+  "family": "divider",
+  "ui": "divider",
+  "binding": "angular",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Line that separates content."
+  },
+  "axes": {
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "align": [
+      "start",
+      "center",
+      "end"
+    ]
+  },
+  "members": {
+    "divider": {
+      "nativeElement": "hr",
+      "defaults": {
+        "orientation": "horizontal",
+        "decorative": false,
+        "inset": false,
+        "align": "center"
+      },
+      "capabilities": [
+        "orientation",
+        "decorative"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "label"
+      ]
+    }
+  },
+  "docs": {
+    "divider": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "slDivider",
+          "description": "Direction the rule runs in"
+        },
+        {
+          "name": "decorative",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slDivider",
+          "description": "Removes the rule from the accessibility tree"
+        },
+        {
+          "name": "inset",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slDivider",
+          "description": "Stops the rule short of both ends of its container"
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slDivider",
+          "description": "Short string the rule is interrupted by, and its name"
+        },
+        {
+          "name": "align",
+          "type": "'start' | 'center' | 'end'",
+          "defaultValue": "center",
+          "appliesTo": "slDivider",
+          "description": "Where the label sits"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The selector is a bare attribute, so the element is the consumer’s. On an hr the separator role is already there and the component writes no role of its own.",
+        "On any other element — the li a menu separator has to be, or the div a label needs — the component writes role=\"separator\", because only the hr carries that meaning by itself.",
+        "A vertical rule receives aria-orientation, because a separator is horizontal unless it says otherwise.",
+        "decorative sets role=\"none\". Use it when the rule groups content visually and a screen reader user loses nothing by not hearing it.",
+        "A labelled rule takes its name from aria-label: the separator role makes its children presentational, so the visible label alone would leave the rule announced as empty. An hr takes no content, so put the label on a div.",
+        "A decorative rule carries no name, because role=\"none\" prohibits one. Its label is read in document order, like any other text.",
+        "A role or an aria-label already on the element is kept, so a rule that has to say something else keeps saying it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-padding-inline-md",
+    "--slotted-divider-color",
+    "--slotted-divider-gap",
+    "--slotted-divider-inset",
+    "--slotted-divider-label-color",
+    "--slotted-divider-min-length",
+    "--slotted-divider-thickness",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-line-height-xs",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-text-muted"
+  ],
+  "examples": [
+    {
+      "id": "divider-angular-sections",
+      "title": "Separating two regions",
+      "note": null,
+      "language": "html",
+      "source": "<section>\n  <h2>Billing</h2>\n  <hr slDivider />\n  <h2>Members</h2>\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "divider-angular-toolbar",
+      "title": "A vertical rule between groups of controls",
+      "note": null,
+      "language": "html",
+      "source": "<div class=\"toolbar\">\n  <button slButton>Bold</button>\n  <hr slDivider orientation=\"vertical\" />\n  <button slButton>Align left</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "divider-angular-label",
+      "title": "A rule interrupted by a label",
+      "note": null,
+      "language": "html",
+      "source": "<sl-sign-in-with-google />\n<div slDivider label=\"Or\"></div>\n<sl-email-and-password />\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "divider-angular-menu",
+      "title": "A separator between two groups of menu items",
+      "note": null,
+      "language": "html",
+      "source": "<ul role=\"menu\">\n  <li role=\"menuitem\">Rename</li>\n  <li slDivider inset></li>\n  <li role=\"menuitem\">Delete</li>\n</ul>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/divider.md

@@ -0,0 +1,83 @@
+<!-- index: ./index.md -->
+# divider
+
+`data-ui="divider"` · Line that separates content.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<section>
+  <h2>Billing</h2>
+  <hr slDivider />
+  <h2>Members</h2>
+</section>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slDivider | Direction the rule runs in |
+| `decorative` | `boolean` | false | slDivider | Removes the rule from the accessibility tree |
+| `inset` | `boolean` | false | slDivider | Stops the rule short of both ends of its container |
+| `label` | `string` | — | slDivider | Short string the rule is interrupted by, and its name |
+| `align` | `'start' \| 'center' \| 'end'` | center | slDivider | Where the label sits |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `align` | `start`, `center`, `end` | `center` |
+
+## Rules
+
+- The selector is a bare attribute, so the element is the consumer’s. On an hr the separator role is already there and the component writes no role of its own.
+- On any other element — the li a menu separator has to be, or the div a label needs — the component writes role="separator", because only the hr carries that meaning by itself.
+- A vertical rule receives aria-orientation, because a separator is horizontal unless it says otherwise.
+- decorative sets role="none". Use it when the rule groups content visually and a screen reader user loses nothing by not hearing it.
+- A labelled rule takes its name from aria-label: the separator role makes its children presentational, so the visible label alone would leave the rule announced as empty. An hr takes no content, so put the label on a div.
+- A decorative rule carries no name, because role="none" prohibits one. Its label is read in document order, like any other text.
+- A role or an aria-label already on the element is kept, so a rule that has to say something else keeps saying it.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-padding-inline-md`, `--slotted-divider-color`, `--slotted-divider-gap`, `--slotted-divider-inset`, `--slotted-divider-label-color`, `--slotted-divider-min-length`, `--slotted-divider-thickness`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-xs`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-text-muted`
+
+## Examples
+
+### A vertical rule between groups of controls
+
+Excerpt — not a complete module
+
+```html
+<div class="toolbar">
+  <button slButton>Bold</button>
+  <hr slDivider orientation="vertical" />
+  <button slButton>Align left</button>
+</div>
+```
+
+### A rule interrupted by a label
+
+Excerpt — not a complete module
+
+```html
+<sl-sign-in-with-google />
+<div slDivider label="Or"></div>
+<sl-email-and-password />
+```
+
+### A separator between two groups of menu items
+
+Excerpt — not a complete module
+
+```html
+<ul role="menu">
+  <li role="menuitem">Rename</li>
+  <li slDivider inset></li>
+  <li role="menuitem">Delete</li>
+</ul>
+```