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

package/docs/popover.md

@@ -0,0 +1,199 @@
+<!-- index: ./index.md -->
+# popover
+
+`data-ui="popover"` · Floating panel anchored to a trigger.
+
+## Import
+
+```ts
+import {
+  providePopoverDefaults,
+  SlPopover,
+  SlPopoverAnchor,
+  SlPopoverArrow,
+  SlPopoverBody,
+  SlPopoverClose,
+  SlPopoverContent,
+  SlPopoverDescription,
+  SlPopoverFooter,
+  SlPopoverHeader,
+  SlPopoverLayer,
+  SlPopoverTitle,
+  SlPopoverTrigger,
+} from '@slotted/angular/popover';
+```
+
+Selector: `[slPopover] on an ng-container, [slPopoverTrigger] on the control, ng-template[slPopoverLayer], [slPopoverContent], and one directive per part inside it` · exportAs: `slPopover`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import {
+  SlDescriptionList,
+  SlDescriptionListDescription,
+  SlDescriptionListItem,
+  SlDescriptionListTerm,
+} from '@slotted/angular/description-list';
+import {
+  SlPopover,
+  SlPopoverArrow,
+  SlPopoverBody,
+  SlPopoverClose,
+  SlPopoverContent,
+  SlPopoverDescription,
+  SlPopoverHeader,
+  SlPopoverLayer,
+  SlPopoverTitle,
+  SlPopoverTrigger,
+} from '@slotted/angular/popover';
+
+@Component({
+  selector: 'app-popover-basic',
+  imports: [
+    SlButton,
+    SlDescriptionList,
+    SlDescriptionListDescription,
+    SlDescriptionListItem,
+    SlDescriptionListTerm,
+    SlPopover,
+    SlPopoverArrow,
+    SlPopoverBody,
+    SlPopoverClose,
+    SlPopoverContent,
+    SlPopoverDescription,
+    SlPopoverHeader,
+    SlPopoverLayer,
+    SlPopoverTitle,
+    SlPopoverTrigger,
+  ],
+  template: `
+    <ng-container slPopover>
+      <button slButton tone="secondary" variant="outline" slPopoverTrigger>Chai stock</button>
+      <ng-template slPopoverLayer>
+        <div slPopoverContent>
+          <div slPopoverHeader>
+            <div slPopoverTitle>Chai</div>
+            <p slPopoverDescription>SKU NW-1001, Seattle warehouse</p>
+            <button slPopoverClose></button>
+          </div>
+          <div slPopoverBody>
+            <div slDescriptionList>
+              @for (row of stock; track row.term) {
+                <div slDescriptionListItem>
+                  <dt slDescriptionListTerm>{{ row.term }}</dt>
+                  <dd slDescriptionListDescription>{{ row.value }}</dd>
+                </div>
+              }
+            </div>
+          </div>
+        </div>
+        <div slPopoverArrow></div>
+      </ng-template>
+    </ng-container>
+  `,
+})
+export class PopoverBasic {
+  readonly stock = [
+    { term: 'On hand', value: '39 units' },
+    { term: 'Reserved', value: '12 units' },
+    { term: 'Reorder point', value: '25 units' },
+    { term: 'Next delivery', value: 'Oct 14, Exotic Liquids' },
+  ];
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, built by ng-template[slPopoverLayer] | yes |
+| `content` | the element carrying slPopoverContent | yes |
+| `header` | the element carrying slPopoverHeader | no |
+| `title` | the element carrying slPopoverTitle | no |
+| `description` | the element carrying slPopoverDescription | no |
+| `body` | the element carrying slPopoverBody | no |
+| `footer` | the element carrying slPopoverFooter | no |
+| `close` | button | no |
+| `arrow` | the element carrying slPopoverArrow | no |
+| `focus-guard` | span (two of them) | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | false | slPopover | Whether the panel is open. Bind [(open)] to a signal to control it. |
+| `defaultOpen` | `boolean` | false | slPopover | The open state an uncontrolled popover starts with. It is read once, on init. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slPopover | The maximum width of the layer, which holds the panel and the gap around it: 16rem, 20rem or 24rem, with the inset and the title size to match. |
+| `width` | `'auto' \| 'anchor'` | auto | slPopover | auto sizes the panel to its content, up to the width size sets. anchor makes it exactly as wide as the anchor. |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | slPopover | The edge of the anchor the panel opens against. inline-start and inline-end follow the writing direction of the layer. |
+| `align` | `'start' \| 'center' \| 'end'` | center | slPopover | Where the panel sits along the side it opened on. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | slPopover | When the layer exists. active builds it on open and removes it after the exit animation. lazy builds it on the first open and keeps it, for a panel whose content is expensive to build. eager builds it from the start. |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | slPopover | The CSS position of the layer. Use fixed for a layer inside an overflow: hidden container, and absolute for one inside a transformed container. |
+| `arrow` | `boolean` | true | slPopover | Whether the slPopoverArrow element is drawn. |
+| `autoFocus` | `boolean` | true | slPopover | Whether focus moves into the popover on open. Focus goes to the panel itself rather than to its first control, so a screen reader announces the panel’s name first and a destructive first control is not focused by default. |
+| `closeOnEscape` | `boolean` | true | slPopover | Whether Escape closes the popover. Escape reaches only the topmost layer. |
+| `closeOnOutsidePress` | `boolean` | true | slPopover | Whether a press outside the panel closes the popover. |
+| `flip` | `boolean` | true | slPopover | Whether the panel moves to the opposite side when it does not fit. |
+| `shift` | `boolean` | true | slPopover | Whether the panel slides along its side to stay inside the boundary. |
+| `hideWhenDetached` | `boolean` | false | slPopover | Whether the panel hides when its anchor scrolls out of view. It is off, unlike slTooltip’s, so a task the reader is halfway through does not disappear when the row behind it scrolls. |
+| `portal` | `boolean` | true | slPopover | Whether the layer is rendered into the shared portal root at the end of the document. The portalled layer keeps the theme, colour scheme, density and direction of the region it was opened from. |
+| `disabled` | `boolean` | false | slPopover | Whether the popover never opens. It does not disable the trigger; set disabled on the trigger element for that. |
+| `messages` | `Partial<PopoverMessages>` | — | slPopover | Text that replaces the language’s messages for this popover, key by key. close is the close button’s accessible name; an aria-label written on slPopoverClose takes precedence. |
+| `sideOffset` | `number` | 0 | slPopover | Extra distance from the anchor in pixels, added to the standard gap. |
+| `alignOffset` | `number` | 0 | slPopover | Distance in pixels along the alignment axis. |
+| `collisionPadding` | `number` | 8 | slPopover | The minimum distance in pixels between the panel and the edge of the boundary. |
+| `arrowPadding` | `number` | 12 | slPopover | The minimum distance in pixels between the arrow and the panel’s corners, so the arrow stays off the rounded corner. |
+| `initialFocus` | `Element \| string` | — | slPopover | What takes focus on open instead of the panel, such as a search field. A string is a selector read inside the panel. |
+| `finalFocus` | `Element \| string` | — | slPopover | What takes focus on close instead of the trigger, for a popover whose trigger is gone by then, such as one that deleted its own row. |
+| `the directive` | `attribute` | — | every part | Every part is a directive on your own element, so the title can be a heading and the trigger can be any slButton. There is no render input. |
+| `exportAs` | `slPopover` | — | [slPopover] | A template reference to the popover, with show(), hide() and toggle(next, reason), for code that has to open or close it outside a binding. |
+| `exportAs` | `slPopoverLayer` | — | ng-template[slPopoverLayer] | A template reference to the layer, with reposition(), which measures and places the layer again. |
+| `slPopoverAnchor` | `directive` | — | composition | The element the panel is positioned against, when it is not the trigger, such as a table row. It writes no attributes. A press on it counts as a press inside the popover. |
+| `providePopoverDefaults` | `Provider` | — | application or component | Sets any option for every popover under the injector. An option set on a popover takes precedence, and an aria-label written on slPopoverClose takes precedence over both. |
+| `native attributes` | `host` | — | every part | A part writes only the attributes it owns. A (click) listener on the trigger runs beside the popover’s own, and event.preventDefault() does not stop the popover’s. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChange` | `boolean` | After the open state changes. It is the change half of [(open)]. |
+| `openChangeRequest` | `PopoverChangeRequest` | Before the panel opens or closes, once per change. reason is pointer, keyboard, escape, outsidePress, dismiss or programmatic. cancel() refuses the change, and openChange is not emitted. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `width` | `auto`, `anchor` | `auto` |
+| `side` | `top`, `bottom`, `inline-start`, `inline-end`, `left`, `right` | `bottom` |
+| `align` | `start`, `center`, `end` | `center` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `strategy` | `absolute`, `fixed` | `absolute` |
+| `arrow` | `true`, `false` | `true` |
+| `autoFocus` | `true`, `false` | `true` |
+| `closeOnEscape` | `true`, `false` | `true` |
+| `closeOnOutsidePress` | `true`, `false` | `true` |
+| `flip` | `true`, `false` | `true` |
+| `shift` | `true`, `false` | `true` |
+| `hideWhenDetached` | `true`, `false` | `false` |
+| `portal` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- The panel is a non-modal dialog: aria-modal is not written, nothing behind it becomes inert, and the page keeps scrolling. Use slDialog for content that has to block the page.
+- The trigger carries aria-expanded, aria-haspopup="dialog", and aria-controls while the panel is in the document. The panel is named by its title through aria-labelledby and described by its description through aria-describedby. A popover without a title has no accessible name until you write aria-label on the slPopoverContent element.
+- Focus moves to the panel on open, so a screen reader announces its name before its contents, and returns to the trigger on close. If the reader has moved focus elsewhere on the page, focus stays there. initialFocus and finalFocus name other targets.
+- Tab past the last control in the panel, or Shift+Tab before the first, closes the popover and returns focus to the trigger; the next Tab continues down the page. Focus is never trapped in the panel.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-gap-md`, `--slotted-control-height-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--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-sm`, `--slotted-font-size-xl`, `--slotted-font-weight-semibold`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-popover-arrow-size`, `--slotted-popover-arrow-tip-radius`, `--slotted-popover-border-color`, `--slotted-popover-gap`, `--slotted-popover-measure`, `--slotted-popover-measure-lg`, `--slotted-popover-measure-sm`, `--slotted-popover-padding-block`, `--slotted-popover-padding-block-lg`, `--slotted-popover-padding-block-sm`, `--slotted-popover-padding-inline`, `--slotted-popover-padding-inline-lg`, `--slotted-popover-padding-inline-sm`, `--slotted-popover-radius`, `--slotted-popover-shadow`, `--slotted-popover-surface`, `--slotted-popover-text`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-shadow-md`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+See [popover.examples.md](./popover.examples.md).