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

package/docs/tooltip.md

@@ -0,0 +1,146 @@
+<!-- index: ./index.md -->
+# tooltip
+
+`data-ui="tooltip"` · Short label shown on hover or focus.
+
+## Import
+
+```ts
+import {
+  provideTooltipDefaults,
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+```
+
+Selector: `[slTooltip] on an ng-container, [slTooltipTrigger] on the control, ng-template[slTooltipLayer], [slTooltipContent], [slTooltipArrow]` · exportAs: `slTooltip`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+
+@Component({
+  selector: 'app-tooltip-basic',
+  imports: [
+    SlButton,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <ng-container slTooltip>
+      <button slButton slTooltipTrigger variant="outline">Sync inventory</button>
+      <ng-template slTooltipLayer>
+        <div slTooltipContent>Pulls stock levels from Reno, Columbus and Savannah.</div>
+        <div slTooltipArrow></div>
+      </ng-template>
+    </ng-container>
+  `,
+})
+export class TooltipBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `content` | div | yes |
+| `arrow` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | false | slTooltip | Whether the tooltip is open. It is two-way: bind [(open)] to a signal to read and set the state, or leave it unbound and the tooltip keeps its own. |
+| `defaultOpen` | `boolean` | false | slTooltip | The state an uncontrolled tooltip starts in, read once in ngOnInit. |
+| `variant` | `'inverse' \| 'surface'` | inverse | slTooltip | inverse paints the tooltip in the colour opposite to the page, which needs no edge on a light page. surface paints the raised panel colour with a hairline border, for a page that is already dark. |
+| `size` | `'sm' \| 'md'` | md | slTooltip | The type step: sm for dense rows such as toolbars and table cells, md elsewhere. Both steps follow the density of the region, because both read the control scale. |
+| `describes` | `'description' \| 'label' \| 'none'` | description | slTooltip | How the trigger refers to the tooltip. description writes aria-describedby while the tooltip is open. label writes aria-labelledby, so the tooltip is the accessible name of an icon-only button, and it forces mount="eager" so the name exists before the first open. none writes no reference and hides the content from assistive technology, for a tooltip that repeats words the trigger already carries. |
+| `openOn` | `'hover' \| 'focus' \| 'manual'` | hover | slTooltip | What opens the tooltip. hover opens it on pointer hover and on keyboard focus, and focus opens it without a delay. focus opens it on keyboard focus only. manual binds neither: the tooltip opens only through open, show() or hide(). |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | top | slTooltip | The edge of the trigger the tooltip prefers. inline-start and inline-end follow the writing direction of the layer, resolved at every measurement; left and right do not. |
+| `align` | `'start' \| 'center' \| 'end'` | center | slTooltip | Where the tooltip sits along the edge it took: at the start of the trigger, at its centre or at its end. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | slTooltip | When the layer is in the document. active adds it on open and removes it after the exit animation, lazy keeps it after the first open, and eager renders it from the start. |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | slTooltip | The CSS position of the layer. Use fixed for a trigger inside an overflow: hidden ancestor, and absolute for one inside a transformed ancestor. |
+| `arrow` | `boolean` | true | slTooltip | Whether the layer draws the arrow. |
+| `hoverable` | `boolean` | true | slTooltip | Whether the pointer can move from the trigger onto the tooltip without it closing. WCAG 2.2 SC 1.4.13 (Content on Hover or Focus) requires it, so turn it off only for content that meets the criterion another way. |
+| `closeOnPress` | `boolean` | true | slTooltip | Whether pressing the trigger closes the tooltip, so it is not left over the dialog its button opened. |
+| `flip` | `boolean` | true | slTooltip | Whether the tooltip moves to the opposite edge when the preferred edge has no room. |
+| `shift` | `boolean` | true | slTooltip | Whether the tooltip slides along its edge to stay inside the boundary. |
+| `hideWhenDetached` | `boolean` | true | slTooltip | Whether the layer hides while its trigger is outside the clipping ancestor. The tooltip hides without closing and shows again when the trigger comes back; the pointer leaving is what closes it. |
+| `portal` | `boolean` | true | slTooltip | Whether the layer renders into the shared portal root at the end of the document. The portal root keeps the theme, colour scheme, density and direction of the region the tooltip opened from. |
+| `disabled` | `boolean` | false | slTooltip | Turns the tooltip off: it never opens and renders no layer. The disabled state of the trigger is set on the trigger itself. |
+| `whenClipped` | `boolean` | false | slTooltip | Opens the tooltip only while the text of the trigger is cut off by its box, such as a column header truncated to “Op…”. The trigger is measured at the moment the tooltip would open, so a column dragged wider stops opening it. |
+| `openDelay` | `number` | 600 | slTooltip | Milliseconds the pointer rests on the trigger before the tooltip opens. Keyboard focus opens it without waiting. |
+| `closeDelay` | `number` | 150 | slTooltip | Milliseconds the tooltip stays after the pointer leaves, which is the time the pointer has to reach a hoverable tooltip. At 0 the pointer cannot reach it. |
+| `groupDelay` | `number` | 400 | provideTooltipDefaults | Milliseconds after one tooltip closes during which the next one in the same injector opens without openDelay, so a row of buttons pays the wait once. It is set through the provider, because every tooltip in that injector shares the window. |
+| `touchDelay` | `number` | 500 | slTooltip | Milliseconds a touch is held on the trigger before the tooltip opens. A tap does not open it, because a tap is the action of the control. |
+| `sideOffset` | `number` | 0 | slTooltip | Distance in pixels between the trigger and the tooltip beyond the standard gap. The standard gap is the padding of the layer, not empty page. |
+| `alignOffset` | `number` | 0 | slTooltip | Distance in pixels the tooltip moves along its edge from the aligned position. |
+| `collisionPadding` | `number` | 8 | slTooltip | The smallest distance in pixels between the tooltip and the edge of the boundary. |
+| `arrowPadding` | `number` | 8 | slTooltip | The smallest distance in pixels between the arrow and the rounded corners of the surface, where the surface would stop covering the base of the arrow. |
+| `slTooltipTrigger` | `directive` | — | the control | Goes on a control the page already has, such as a slButton or a slIconButton. The tooltip writes only the ARIA reference and data-open on it, and no data-part, so the control keeps its own styling. |
+| `ng-template[slTooltipLayer]` | `directive` | — | slTooltip | Holds the layer content in a template, because the layer is built when the tooltip mounts and removed when it unmounts. Its exportAs, slTooltipLayer, reaches reposition(). |
+| `exportAs` | `slTooltip` | — | slTooltip | A template reference such as #hint="slTooltip" reaches show() and hide(), which open and close the tooltip without a delay. |
+| `provideTooltipDefaults` | `(defaults: Partial<TooltipDefaults>) => Provider[]` | — | providers | Sets any axis and any delay once for every tooltip in the injector it is provided in, and holds the group window. A value set on one tooltip wins. |
+| `provideSlottedPortalContainer` | `(container: () => Element \| null) => Provider` | document.body | providers | Names the element every layer renders into, set through setPortalContainer. An application shell with its own stacking context provides it once. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChange` | `boolean` | Emitted after the tooltip changes its own value, which is what makes [(open)] two-way. Bind it alone when the template only reads the state. |
+| `openChangeRequest` | `TooltipChangeRequest` | Emitted once per change, before the layer moves. The request carries value, previous, reason (pointer, keyboard, escape, blur or programmatic) and the originating event. cancel() refuses the change: nothing moves and openChange is not emitted. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `variant` | `inverse`, `surface` | `inverse` |
+| `size` | `sm`, `md` | `md` |
+| `describes` | `description`, `label`, `none` | `description` |
+| `openOn` | `hover`, `focus`, `manual` | `hover` |
+| `side` | `top`, `bottom`, `inline-start`, `inline-end`, `left`, `right` | `top` |
+| `align` | `start`, `center`, `end` | `center` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `strategy` | `absolute`, `fixed` | `absolute` |
+| `arrow` | `true`, `false` | `true` |
+| `hoverable` | `true`, `false` | `true` |
+| `closeOnPress` | `true`, `false` | `true` |
+| `flip` | `true`, `false` | `true` |
+| `shift` | `true`, `false` | `true` |
+| `hideWhenDetached` | `true`, `false` | `true` |
+| `portal` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+| `whenClipped` | `true`, `false` | `false` |
+
+## Rules
+
+- The content has role="tooltip" and the trigger refers to it: with aria-describedby by default, and with aria-labelledby under describes="label". An icon-only button that its tooltip only describes has no name, and a screen reader announces it as “button”.
+- Escape closes the tooltip and leaves focus on the trigger. It reaches the topmost layer only, so a tooltip open over a popover closes first. Escape is the whole keyboard table of the WAI-ARIA tooltip pattern, and it meets WCAG 2.2 SC 1.4.13 Dismissible. The tooltip never takes focus and holds nothing focusable: content with a link or a button belongs in a Popover.
+- The pointer can move onto the tooltip without it closing, because the gap between the trigger and the surface is the padding of the layer, not empty page (SC 1.4.13 Hoverable). Nothing closes the tooltip on a timer (Persistent).
+- A coarse pointer has no hover, so a long press opens the tooltip and a tap does not. A tooltip is supplementary: a fact reachable only by hover or long press is a fact many readers never reach, so a tooltip may never be the only place a fact is written.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-font-family-sans`, `--slotted-font-weight-regular`, `--slotted-line-height-sm`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-shadow-xs`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-surface-inverse`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-tooltip-arrow-size`, `--slotted-tooltip-arrow-tip-radius`, `--slotted-tooltip-border-color`, `--slotted-tooltip-gap`, `--slotted-tooltip-measure`, `--slotted-tooltip-measure-sm`, `--slotted-tooltip-radius`, `--slotted-tooltip-shadow`, `--slotted-tooltip-surface`, `--slotted-tooltip-surface-raised`, `--slotted-tooltip-text`, `--slotted-tooltip-text-raised`, `--slotted-z-index-popover`
+
+## Examples
+
+See [tooltip.examples.md](./tooltip.examples.md).

package/docs/top-navigation.examples.md

@@ -0,0 +1,287 @@
+<!-- index: ./index.md -->
+# top-navigation
+
+`data-ui="top-navigation"` · Application header with brand, search and account.
+
+## Examples
+
+### Every part, named
+
+The bar with each part labelled by its data-part: the brand, the context, the destinations with a section trigger, the search, and the four global controls. The panel and its list stand in the DOM after the nav, closed.
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation>
+  <div slTopNavigationBrand>
+    <a slTopNavigationHome href="/">
+      <span slTopNavigationMark>…</span>
+      <span slTopNavigationName>name</span>
+    </a>
+  </div>
+  <div slTopNavigationContext>…</div>
+  <nav slTopNavigationNav>
+    <ul slTopNavigationList>
+      <li slTopNavigationItem value="link"><a slTopNavigationLink href="/link">link</a></li>
+      <li slTopNavigationItem value="trigger">
+        <button slTopNavigationTrigger>trigger</button>
+        <div slNavigationMenuContent>…</div>
+      </li>
+    </ul>
+  </nav>
+  <div slTopNavigationSearch>…</div>
+  <div slTopNavigationActions>
+    <a slTopNavigationHelp href="/help"></a>
+    <button slTopNavigationNotifications><span slTopNavigationCount>3</span></button>
+    <button slTopNavigationAccount>…</button>
+  </div>
+</header>
+```
+
+### Three steps of the width
+
+The same bar in four rooms of a stated width. On a desktop everything shows; on a laptop (under 1024) the low items have folded into more; a tablet at 640 folds the same low items and keeps the rest; on a phone the medium ones fold under 600, where the search becomes a magnifier and the context moves to the panel, and the high ones and the help fold under 480, where the name leaves the eye.
+
+Excerpt — not a complete module
+
+```html
+<ul slTopNavigationList>
+  <li slTopNavigationItem value="painel" priority="high">
+    <a slTopNavigationLink href="/painel">Painel</a>
+  </li>
+  <li slTopNavigationItem value="rotas"><a slTopNavigationLink href="/rotas">Rotas</a></li>
+  <li slTopNavigationItem value="faturacao" priority="low">
+    <a slTopNavigationLink href="/faturacao">Faturação</a>
+  </li>
+</ul>
+```
+
+### What folded, under the bar
+
+Press more: on a phone the panel takes the bar’s whole width, on a tablet it stands under the bar’s end. The folded destinations are rows, the workspace at the top and help at the bottom. A press on a row closes it with the reason select; Escape returns focus to more; a press outside closes it too.
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation [(moreOpen)]="moreOpen" (moreOpenChangeRequest)="log($event.reason)">
+  …
+</header>
+```
+
+### The search gives way to a magnifier
+
+On a laptop the field stands at the start of the middle of the bar, after the brand and the destinations. On a phone it is a magnifier in the actions; pressing it opens the field over the whole bar with focus inside, and Escape, the cross or focus leaving it hand the bar back.
+
+Excerpt — not a complete module
+
+```html
+<div slTopNavigationSearch>
+  <div slTextField variant="subtle">
+    <span slTextFieldStart><ng-icon name="lucideSearch" size="16" /></span>
+    <input slTextFieldInput type="search" aria-label="Procurar" placeholder="Procurar cargas…" />
+    <span slTextFieldEnd><kbd slShortcut keys="mod+k" size="sm" variant="soft"></kbd></span>
+  </div>
+</div>
+```
+
+### A section that opens a panel of destinations
+
+Frota is a section of the navigation menu the nav part already is: its panel opens on the shared surface under the bar, a resting pointer opens it after a delay, and a second section switches without one. Folded into the panel, the section opens its links in line.
+
+Excerpt — not a complete module
+
+```html
+<li slTopNavigationItem value="frota">
+  <button slTopNavigationTrigger>Frota</button>
+  <div slNavigationMenuContent>
+    <ul slNavigationMenuLinks>
+      <li><a slNavigationMenuLink routerLink="/fleet/vehicles">Veículos</a></li>
+    </ul>
+  </div>
+</li>
+```
+
+### Where the reader is
+
+value on the root names the destination and a press asks it to move with the device’s reason; a link that states current itself wins. Where the current destination has folded, more carries the mark in its place.
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation [(value)]="value" (valueChangeRequest)="log($event.reason)">…</header>
+```
+
+### The global controls
+
+Help as a link to a help centre or as the trigger of a popover; the bell with a count over its corner that grows to a pill away from it; the account as a menu’s trigger; a control of the product’s own — approvals — in the same square, with its own glyph and the same count. Each carries its name for a reader and repeats it in a tooltip.
+
+Excerpt — not a complete module
+
+```html
+<div slTopNavigationActions>
+  <a slTopNavigationHelp href="/ajuda"></a>
+  <ng-container slPopover>
+    <button
+      slTopNavigationAction
+      slPopoverTrigger
+      [label]="'Aprovações, ' + pending() + ' pendentes'"
+    >
+      <ng-icon name="lucideClipboardCheck" />
+      <span slTopNavigationCount>{{ pending() }}</span>
+    </button>
+    <ng-template slPopoverLayer><div slPopoverContent>…</div></ng-template>
+  </ng-container>
+  <ng-container slPopover>
+    <button slTopNavigationNotifications slPopoverTrigger>
+      <span slTopNavigationCount>12</span>
+    </button>
+    <ng-template slPopoverLayer><div slPopoverContent>…</div></ng-template>
+  </ng-container>
+  <button slTopNavigationAccount [slMenuTriggerFor]="account">
+    <span slAvatar size="xs"><span slAvatarFallback>AB</span></span>
+  </button>
+  <sl-menu #account>…</sl-menu>
+</div>
+```
+
+### What the application is right now
+
+A workspace switcher and an environment badge after the brand. On a phone the whole region is moved to the top of the panel — the same element, so the switcher still opens its menu there.
+
+Excerpt — not a complete module
+
+```html
+<div slTopNavigationContext>
+  <button slButton size="sm" tone="secondary" variant="ghost" [slMenuTriggerFor]="workspaces">
+    Porto · Operações
+    <span slButtonEnd><ng-icon name="lucideChevronsUpDown" /></span>
+  </button>
+  <sl-menu #workspaces>…</sl-menu>
+  <span slBadge size="sm" tone="warning" variant="soft">Homologação</span>
+</div>
+```
+
+### Three control heights
+
+sm, md and lg move every control in the bar together — the mark, the destinations, the four global controls — and the bar’s own height with them. All three move again with density.
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation size="sm">…</header>
+```
+
+### The states a destination can be in
+
+Current, a section open, disabled — a disabled destination keeps its href and its name and refuses the press — and the hover, press and focus every control answers. Help and the account with their layers open hold the pointer’s ground.
+
+Excerpt — not a complete module
+
+```html
+<li slTopNavigationItem value="faturacao" disabled>
+  <a slTopNavigationLink href="/faturacao">Faturação</a>
+</li>
+```
+
+### Content the family did not choose
+
+A product name of nine words, cut with an ellipsis and, when the room runs out, given up before any control; destinations of four words each; a count of three characters; the account with a name beside the avatar; and the same bar in a right-to-left document.
+
+Excerpt — not a complete module
+
+```html
+<button slTopNavigationAccount>
+  <span slAvatar size="xs"><span slAvatarFallback>MB</span></span>
+  <span>Maria Bartolomeu</span>
+</button>
+```
+
+### Inside the shell
+
+The bar as the only child of app-shell’s banner: a div rather than a second banner, no ground of its own, the shell’s nav-toggle in the brand and the mark over the column’s marks. Press the toggle and the bar keeps its place.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell>
+  <header slAppShellBanner>
+    <div slTopNavigation value="painel">
+      <div slTopNavigationBrand>
+        <button slAppShellNavToggle></button>
+        <a slTopNavigationHome href="/">…</a>
+      </div>
+      …
+    </div>
+  </header>
+  <nav slAppShellNav>…</nav>
+  <main slAppShellMain>…</main>
+</div>
+```
+
+### On its own, above a page
+
+A header with its own ground, rule and inset, a skip link that appears on the first Tab, and a page under it. Nothing here is sticky: an application that wants the bar pinned writes position: sticky on it.
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation skipTo="conteudo">…</header>
+<main id="conteudo" tabindex="-1">…</main>
+```
+
+### Decided once for an application
+
+The provider carries the size and the frame for every bar under it — an application at the large step — and a bar that states one itself still wins. The words on the icon-only controls come from the language in force.
+
+Excerpt — not a complete module
+
+```ts
+@Component({
+  providers: [provideTopNavigationDefaults({ size: 'lg' })],
+  template: '<header slTopNavigation>…</header>',
+})
+export class Shell {}
+```
+
+### Composed with what sits beside it
+
+routerLink and routerLinkActive on the destination, which is where aria-current comes from; a badge in the context; a kbd in the search; a navigation-menu panel on a section, a menu on the account and on the workspace; a popover on the bell.
+
+Excerpt — not a complete module
+
+```html
+<li slTopNavigationItem value="cargas">
+  <a slTopNavigationLink routerLink="/cargas" routerLinkActive ariaCurrentWhenActive="page">
+    Cargas
+  </a>
+</li>
+```
+
+### The keyboard
+
+Tab reaches every control, in the order they stand: the skip link, the mark, each destination, more, the panel when it is open, the search, help, the bell, the account. Escape closes the panel or the open search and lands on the control that opened it. The reason each request carries is shown.
+
+Excerpt — not a complete module
+
+```html
+<header
+  slTopNavigation
+  (moreOpenChangeRequest)="log($event.reason)"
+  (searchOpenChangeRequest)="log($event.reason)"
+  (valueChangeRequest)="log($event.reason)"
+>
+  …
+</header>
+```
+
+### What a reader hears
+
+A banner landmark holding a navigation landmark with a list of links, one of them current; a button named More that expands a panel; a search; and three buttons named for what they open. Nothing is a menubar and nothing writes tabindex.
+
+Excerpt — not a complete module
+
+```html
+<header slTopNavigation aria-label="Aurora">
+  <nav slTopNavigationNav aria-label="Principal">…</nav>
+</header>
+```