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

package/docs/drawer.md

@@ -0,0 +1,199 @@
+<!-- index: ./index.md -->
+# drawer
+
+`data-ui="drawer"` · Panel that slides in from an edge.
+
+## Import
+
+```ts
+import { SlDrawer, SlDrawerBody, SlDrawerClose, SlDrawerDescription, SlDrawerFooter, SlDrawerHeader, SlDrawerResizer, SlDrawerTitle, SlDrawerTrigger, provideDrawerDefaults } from '@slotted/angular/drawer';
+```
+
+Selector: `<sl-drawer>, exportAs slDrawer`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlBadge } from '@slotted/angular/badge';
+import { SlButton } from '@slotted/angular/button';
+import {
+  SlDescriptionList,
+  SlDescriptionListDescription,
+  SlDescriptionListItem,
+  SlDescriptionListTerm,
+} from '@slotted/angular/description-list';
+import {
+  SlDrawer,
+  SlDrawerBody,
+  SlDrawerClose,
+  SlDrawerDescription,
+  SlDrawerFooter,
+  SlDrawerHeader,
+  SlDrawerTitle,
+  SlDrawerTrigger,
+} from '@slotted/angular/drawer';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+
+const DETAILS = [
+  { term: 'Ship to', value: '1200 Harbor Ave, Seattle, WA' },
+  { term: 'Payment', value: 'Captured, card ending 4242' },
+  { term: 'Items', value: '14 cases, 3 products' },
+  { term: 'Warehouse', value: 'Reno, NV' },
+  { term: 'Total', value: '$1,240.00' },
+];
+
+@Component({
+  selector: 'app-drawer-basic',
+  imports: [
+    SlBadge,
+    SlButton,
+    SlDescriptionList,
+    SlDescriptionListDescription,
+    SlDescriptionListItem,
+    SlDescriptionListTerm,
+    SlDrawer,
+    SlDrawerBody,
+    SlDrawerClose,
+    SlDrawerDescription,
+    SlDrawerFooter,
+    SlDrawerHeader,
+    SlDrawerTitle,
+    SlDrawerTrigger,
+    SlInline,
+    SlStack,
+  ],
+  template: `
+    <button slButton tone="secondary" variant="outline" [slDrawerTrigger]="drawer">
+      View order SO-1182
+    </button>
+    <sl-drawer #drawer="slDrawer" [(open)]="open">
+      <header slDrawerHeader>
+        <h2 slDrawerTitle>Order SO-1182</h2>
+        <p slDrawerDescription>Contoso Foods, placed on 2 October 2026.</p>
+        <button slDrawerClose></button>
+      </header>
+      <div slDrawerBody>
+        <div slStack [gap]="4">
+          <div slInline>
+            <span slBadge tone="accent">Ready to ship</span>
+          </div>
+          <div slDescriptionList>
+            @for (detail of details; track detail.term) {
+              <div slDescriptionListItem>
+                <dt slDescriptionListTerm>{{ detail.term }}</dt>
+                <dd slDescriptionListDescription>{{ detail.value }}</dd>
+              </div>
+            }
+          </div>
+        </div>
+      </div>
+      <footer slDrawerFooter>
+        <button slButton variant="ghost" tone="secondary" (click)="open.set(false)">Close</button>
+        <button slButton (click)="open.set(false)">Create shipment</button>
+      </footer>
+    </sl-drawer>
+  `,
+})
+export class DrawerBasic {
+  readonly open = signal(false);
+  readonly details = DETAILS;
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div inside <sl-drawer>, moved into a portal under mode="overlay" | yes |
+| `trigger` | your own element, with slDrawerTrigger on it | no |
+| `backdrop` | div | no |
+| `panel` | div, holding the projected content | yes |
+| `resizer` | your own element, with slDrawerResizer on it | no |
+| `line` | span | yes |
+| `grip` | span[aria-hidden] | yes |
+| `header` | your own element, with slDrawerHeader on it | no |
+| `title` | your own heading, with slDrawerTitle on it | no |
+| `description` | your own element, with slDrawerDescription on it | no |
+| `body` | your own element, with slDrawerBody on it | no |
+| `footer` | your own element, with slDrawerFooter on it | no |
+| `close` | your own button, with slDrawerClose on it | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `model<boolean>` | false | <sl-drawer> | Whether the drawer is open. A model, so [(open)] binds both halves and there is no defaultOpen. |
+| `extent` | `model<number \| undefined>` | — | <sl-drawer> | The panel’s measure: a fraction from 0 to 1 of the screen, or of your layout under mode="inline". undefined means the size step decides. A model, so [(extent)] binds both halves. |
+| `minExtent` | `number` | 0.2 | <sl-drawer> | The smallest measure the reader can set, and the separator’s aria-valuemin. A drag released below it asks to close the drawer, with the reason pointer. |
+| `maxExtent` | `number` | 1 | <sl-drawer> | The largest measure the reader can set, and the separator’s aria-valuemax. With snap points, both limits default to the first and the last stop. |
+| `snapPoints` | `readonly number[]` | — | <sl-drawer> | The stops the measure moves between, as fractions. With them an arrow key moves to the next stop, Home and End go to the first and the last, and a drag is released onto the nearest. |
+| `mode` | `'overlay' \| 'inline'` | overlay | <sl-drawer>, provideDrawerDefaults | overlay puts the drawer over the page, in a portal; inline puts it in your own layout. The value can change while the drawer is open, and the panel’s content and the state of its fields are kept across the change. |
+| `side` | `'start' \| 'end' \| 'top' \| 'bottom'` | end | <sl-drawer>, provideDrawerDefaults | The edge the panel comes from. start and end follow the writing direction, so the drawer changes sides in a right-to-left document. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' \| 'content'` | md | <sl-drawer>, provideDrawerDefaults | The panel’s measure at rest: one of the steps sm (18rem), md (24rem), lg (30rem), xl (40rem) and full, or content, which fits what the panel holds, up to 4rem short of the screen. When unset, content on top and bottom and md on start and end. A step wider than the screen is held to it. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | <sl-drawer>, provideDrawerDefaults | When an overlay layer is in the document: active only while it is open or closing, lazy from the first open on, and eager from the start, inert while closed. An inline drawer is always in the document. |
+| `modal` | `boolean` | true | <sl-drawer>, provideDrawerDefaults | Whether the page behind is inert, its scroll is locked and focus is contained in the panel, and whether the panel carries aria-modal. The scrim is painted either way. Always false under mode="inline". |
+| `escape` | `'close' \| 'none'` | close | <sl-drawer>, provideDrawerDefaults | Whether Escape asks to close the drawer. Escape reaches only the topmost layer, and a layer that refuses it does not pass it to the one below. |
+| `outsidePress` | `'close' \| 'none'` | close | <sl-drawer>, provideDrawerDefaults | Whether a press outside the layer, the scrim included, asks to close the drawer. It has no effect under mode="inline". |
+| `back` | `'close' \| 'none'` | close | <sl-drawer>, provideDrawerDefaults | Whether the browser’s back button or a phone’s back gesture closes a modal drawer instead of leaving the page. The drawer holds one history entry while it is open. It has no effect under mode="inline". |
+| `drag` | `'panel' \| 'resizer'` | panel | <sl-drawer>, provideDrawerDefaults | What a touch moves a bottom sheet by: panel, anywhere on the panel, or resizer, the separator only. With panel, a drag that starts in a list scrolled away from its top scrolls the list. A mouse or a pen always drags the separator. |
+| `scrimFrom` | `number` | 0 | <sl-drawer> | While the measure is below this fraction, the scrim is not painted, a press reaches the page, and the root carries data-undimmed. Use it with [modal]="false" and outsidePress="none". |
+| `loading` | `boolean` | false | <sl-drawer> | Marks the body as busy with aria-busy and gives it a minimum height, so the panel does not jump when the content arrives. The header, the ✕, Escape and the separator stay available. |
+| `messages` | `Partial<DrawerMessages>` | — | <sl-drawer> | Words laid over the current language, key by key: close, the name of the ✕. An aria-label on slDrawerClose takes precedence. |
+| `initialFocus` | `'first' \| 'container' \| HTMLElement \| false` | first | <sl-drawer> | Where focus goes when an overlay drawer opens: first, the first focusable element; container, the panel itself, for content that is read before it is used; an element; or false, nowhere. An inline drawer moves no focus. |
+| `finalFocus` | `HTMLElement \| false` | — | <sl-drawer> | Where focus goes when the drawer closes, as an element, or false for nowhere. When unset, it returns to the element that had focus when the drawer opened, usually the trigger. |
+| `inset` | `'none'` | — | slDrawerBody | none removes the body’s padding, for content that brings its own inset, such as a page or a list that runs to the panel’s edges. |
+| `step` | `number` | 16 | slDrawerResizer | How far one arrow key moves the separator, in pixels, when there are no snap points. |
+| `largeStep` | `number` | 64 | slDrawerResizer | How far Shift and an arrow key move the separator, in pixels, when there are no snap points. |
+| `value` | `string` | — | slDrawerClose | The result of a close from this button, carried on the close request as result. |
+| `exportAs` | `'slDrawer'` | — | <sl-drawer> | A template reference variable, #drawer="slDrawer", reaches the drawer, which is how a trigger anywhere in the same template opens it. |
+| `ng-content` | `—` | — | <sl-drawer> | The drawer’s content is your own elements with the part directives on them, projected into the panel. Under mount="active" the layer is built only while the drawer is open. |
+| `openDrawer(), close(result), focus()` | `() => void` | — | <sl-drawer> | Open the drawer, close it with a result, and move focus into the panel, from code. Each opens or closes with the reason programmatic. |
+| `container` | `Element \| null` | — | <sl-drawer> | An element to portal this layer into instead of the shared portal root, for an application shell with its own stacking context. setPortalContainer from @slotted/core/portal sets one for the whole document. |
+| `provideDrawerDefaults()` | `{ mode, side, size, mount, modal, escape, outsidePress, back, drag }` | — | an injector | Sets these nine axes for every drawer in the injector, through DRAWER_DEFAULTS. A value set on one drawer still wins. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChange` | `boolean` | The two-way half of open, which [(open)] binds. It fires once the drawer has opened or closed. |
+| `openChangeRequest` | `DrawerChangeRequest` | Before the drawer opens or closes, for every way it can: the trigger, the ✕, Escape, a press outside, the back gesture and a call from code. The request carries value, previous, reason (pointer, keyboard, dismiss, escape, outsidePress, back or programmatic), result, the source event and cancel(), which keeps the drawer as it is. |
+| `extentChange` | `number \| undefined` | The two-way half of extent, which [(extent)] binds. It fires once the measure has changed. |
+| `extentChangeRequest` | `DrawerExtentRequest` | Before the panel’s measure changes, with the reason pointer for a drag or a tap on the grip, keyboard for an arrow key, Home, End or Enter, and programmatic for a change from code. A drag of the separator fires on every pointer move and can report a value below minExtent; a drag of a sheet’s body fires once, on release, with the stop it landed on. undefined means the panel is back on its size step, or on the height of its content under size="content". |
+| `closed` | `string \| undefined` | Once the drawer has closed, with the result of the close, or undefined for a close that carried none. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `mode` | `overlay`, `inline` | `overlay` |
+| `side` | `start`, `end`, `top`, `bottom` | `end` |
+| `size` | `sm`, `md`, `lg`, `xl`, `full`, `content` | `md` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `modal` | `true`, `false` | `true` |
+| `escape` | `close`, `none` | `close` |
+| `outsidePress` | `close`, `none` | `close` |
+| `back` | `close`, `none` | `close` |
+| `drag` | `panel`, `resizer` | `panel` |
+
+## Rules
+
+- Under mode="overlay" the drawer follows the WAI-ARIA dialog (modal) pattern. While it is modal, Tab and Shift+Tab move through the panel and wrap at its ends. Escape closes it, and reaches only the topmost layer, so one press never closes two drawers.
+- Under mode="inline" the panel has no role, because a navigation drawer is a navigation landmark and a filter panel is complementary; write the landmark yourself, such as <nav slDrawerBody>. The trigger has no aria-haspopup there, because an inline drawer is a disclosure, not a popup.
+- aria-modal="true" is written only while the drawer is modal, which is the only state in which the page behind is inert. modal is always false under mode="inline". An aria-label written on <sl-drawer> is moved to the panel, which is the element the role is on.
+- The separator follows the WAI-ARIA window splitter pattern. The arrow keys move it in the direction they point, Home and End go to the limits, and Enter collapses the panel to its minimum and then restores it. Enter never closes the drawer; Escape does. The values are percentages, and there is no aria-valuetext, so a screen reader announces 40 rather than 40 per cent.
+- A bottom sheet moves under a touch on its body as well as on its separator, and every stop a finger reaches, the height of the content among them, is also reachable with the arrow keys on the separator. A touch drag never starts on a field, on selected text, or on an element whose touch-action already takes vertical movement.
+- A closed panel is inert in both modes, so its controls are in neither the tab order nor the accessibility tree.
+- Focus moves into an overlay panel when it opens, to the first focusable element unless initialFocus names another, and returns on close to the element that had it before; if that element has left the document, focus goes to its nearest ancestor still in it. An inline drawer moves no focus when it opens, and on close restores focus only when focus is inside the panel or on the page body.
+- The ✕ button and the separator are each at least --slotted-target-min across, so both meet the WCAG 2.2 minimum target size of 24 by 24 pixels.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-icon-size-md`, `--slotted-control-inner-size-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-drawer-body-color`, `--slotted-drawer-border-color`, `--slotted-drawer-close-active-background`, `--slotted-drawer-close-color`, `--slotted-drawer-close-hover-background`, `--slotted-drawer-color`, `--slotted-drawer-description-color`, `--slotted-drawer-extent`, `--slotted-drawer-extent-lg`, `--slotted-drawer-extent-md`, `--slotted-drawer-extent-sm`, `--slotted-drawer-extent-xl`, `--slotted-drawer-footer-surface`, `--slotted-drawer-radius`, `--slotted-drawer-resizer-line-active-color`, `--slotted-drawer-resizer-line-color`, `--slotted-drawer-rule-color`, `--slotted-drawer-scrim`, `--slotted-drawer-sheet-inline-size`, `--slotted-drawer-surface`, `--slotted-drawer-title-color`, `--slotted-drawer-title-font-family`, `--slotted-duration-instant`, `--slotted-duration-long`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--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-lg`, `--slotted-line-height-md`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-scrim`, `--slotted-shadow-lg`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-overlay`
+
+## Examples
+
+See [drawer.examples.md](./drawer.examples.md).