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

package/docs/tooltip.examples.md

@@ -0,0 +1,664 @@
+<!-- index: ./index.md -->
+# tooltip
+
+`data-ui="tooltip"` · Short label shown on hover or focus.
+
+## Examples
+
+### A hint on a control
+
+Hover the button, or Tab to it: focus opens the hint in the same task and the pointer waits out the delay first.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slTooltip>
+  <button slButton slTooltipTrigger type="button">Publish</button>
+  <ng-template slTooltipLayer>
+    <div slTooltipContent>Sends the draft to every subscriber</div>
+    <div slTooltipArrow></div>
+  </ng-template>
+</ng-container>
+```
+
+### Inverse, and surface
+
+The inverse hint separates itself from a light page with no edge at all; the surface one takes the raised surface and the hairline it needs on a dark ground.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slTooltip variant="surface">
+  <button slButton slTooltipTrigger type="button">On a dark page</button>
+  <ng-template slTooltipLayer>
+    <div slTooltipContent>Reads as a small panel rather than as a label</div>
+  </ng-template>
+</ng-container>
+```
+
+### Two type steps
+
+Small is the hint inside a dense table row; medium is everywhere else. Switch the density in the toolbar and both tighten without either changing meaning.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slTooltip size="sm">
+  <button slButton slTooltipTrigger type="button">Small</button>
+  <ng-template slTooltipLayer>
+    <div slTooltipContent>Twelve pixels, in a row that has no room</div>
+  </ng-template>
+</ng-container>
+```
+
+### Which edge it takes
+
+Four sides around one anchor. inline-start and inline-end mirror with the direction; left and right do not, which is why the arrow stays put when the toolbar switches to rtl.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+  type TooltipAlign,
+  type TooltipSide,
+} from '@slotted/angular/tooltip';
+
+const ACTIONS: { label: string; hint: string; side: TooltipSide; align: TooltipAlign }[] = [
+  {
+    label: 'Print label',
+    hint: 'Prints a 4 × 6 label at packing station 3.',
+    side: 'top',
+    align: 'center',
+  },
+  {
+    label: 'Weigh parcel',
+    hint: 'Reads the scale under station 3.',
+    side: 'bottom',
+    align: 'center',
+  },
+  {
+    label: 'Previous order',
+    hint: 'SO-10484 · Northgate Labs',
+    side: 'inline-start',
+    align: 'center',
+  },
+  { label: 'Next order', hint: 'SO-10486 · Quill & Co.', side: 'inline-end', align: 'start' },
+];
+
+@Component({
+  selector: 'app-tooltip-placement',
+  imports: [
+    SlButton,
+    SlInline,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slInline [gap]="3" align="center">
+      @for (action of actions; track action.label) {
+        <ng-container slTooltip [side]="action.side" [align]="action.align">
+          <button slButton slTooltipTrigger variant="outline">{{ action.label }}</button>
+          <ng-template slTooltipLayer>
+            <div slTooltipContent>{{ action.hint }}</div>
+            <div slTooltipArrow></div>
+          </ng-template>
+        </ng-container>
+      }
+    </div>
+  `,
+})
+export class TooltipPlacement {
+  protected readonly actions = ACTIONS;
+}
+```
+
+### The warmup, and the group window
+
+Cross the row of buttons quickly and nothing opens. Rest on one, wait, and it opens; move to its neighbour inside the group window and that one opens in the same task.
+
+Excerpt — not a complete module
+
+```ts
+@Component({
+  providers: [provideTooltipDefaults({ groupDelay: 400, openDelay: 600 })],
+})
+export class RowActions {}
+```
+
+### Description, or name
+
+The left button is labelled and the hint describes it. The right one has no words of its own, so the hint is its accessible name and the layer is in the document before anyone opens it.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slTooltip describes="label">
+  <button slButton slTooltipTrigger type="button">+</button>
+  <ng-template slTooltipLayer>
+    <div slTooltipContent>Add a row</div>
+  </ng-template>
+</ng-container>
+```
+
+### Reaching the hint with the pointer
+
+Open the left one and move the pointer onto it: it stays, because the gap is the layer own padding. The right one is [hoverable]="false" and lets the pointer straight through.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slTooltip [hoverable]="false">
+  <button slButton slTooltipTrigger type="button">Passes through</button>
+  <ng-template slTooltipLayer>
+    <div slTooltipContent>The pointer never lands on this one</div>
+  </ng-template>
+</ng-container>
+```
+
+### Content the family did not choose
+
+A sentence long enough to meet the measure, a single unbroken token, and a string in another script. The cap is a token rather than an axis, because measure belongs to Container.
+
+Excerpt — not a complete module
+
+```html
+<div slTooltipContent>
+  Publishing sends the draft to every subscriber on the list and cannot be undone from here.
+</div>
+```
+
+### A hint on a control that is out of action
+
+A native disabled button fires no pointer events, so its explanation is unreachable. Use aria-disabled on a control that stays focusable, or put the trigger on a wrapper.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slTooltip>
+  <button aria-disabled="true" slButton slTooltipTrigger type="button">Publish</button>
+  <ng-template slTooltipLayer>
+    <div slTooltipContent>Publish once the invoice has a customer</div>
+  </ng-template>
+</ng-container>
+```
+
+### In a row of icon buttons
+
+Where a tooltip actually lives. Every trigger is the consumer own button, and one provider sets the hint and the delays for the whole row.
+
+Excerpt — not a complete module
+
+```ts
+@Component({
+  providers: [provideTooltipDefaults({ describes: 'label', size: 'sm' })],
+})
+export class Toolbar {}
+```
+
+### What the keyboard does
+
+Tab in and the hint opens with no delay; press Escape and it goes without the focus moving; press Enter and the button acts and the hint clears itself away.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import type { ChangeRequest } from '@slotted/core/state';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-tooltip-keyboard',
+  imports: [
+    SlButton,
+    SlInline,
+    SlStack,
+    SlText,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slStack [gap]="3">
+      <div slInline [gap]="3" align="center">
+        <ng-container slTooltip (openChangeRequest)="report($event)">
+          <button slButton slTooltipTrigger variant="outline">Approve return</button>
+          <ng-template slTooltipLayer>
+            <div slTooltipContent>Refunds $86.00 to Verde Kitchen and restocks 2 units.</div>
+            <div slTooltipArrow></div>
+          </ng-template>
+        </ng-container>
+        <ng-container slTooltip (openChangeRequest)="report($event)">
+          <button slButton slTooltipTrigger variant="outline">Reject return</button>
+          <ng-template slTooltipLayer>
+            <div slTooltipContent>Ships the parcel back to the customer at their cost.</div>
+            <div slTooltipArrow></div>
+          </ng-template>
+        </ng-container>
+      </div>
+      <span slText size="sm" tone="muted">{{ last() }}</span>
+    </div>
+  `,
+})
+export class TooltipKeyboard {
+  protected readonly last = signal('Tab to a button, then press Escape or Enter.');
+
+  protected report(request: ChangeRequest<boolean>) {
+    this.last.set(`${request.value ? 'Opened' : 'Closed'} by ${request.reason}.`);
+  }
+}
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-tooltip-controlled',
+  imports: [
+    SlButton,
+    SlInline,
+    SlStack,
+    SlText,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slStack [gap]="3">
+      <div slInline [gap]="3" align="center">
+        <ng-container slTooltip [(open)]="open">
+          <button slButton slTooltipTrigger variant="outline">Same-day dispatch</button>
+          <ng-template slTooltipLayer>
+            <div slTooltipContent>
+              Orders placed before 2:00 PM Pacific leave Reno the same day.
+            </div>
+            <div slTooltipArrow></div>
+          </ng-template>
+        </ng-container>
+        <button slButton variant="ghost" (click)="open.set(true)">Show the cutoff</button>
+      </div>
+      <span slText size="sm" tone="muted">
+        {{ open() ? 'The cutoff hint is open.' : 'The cutoff hint is closed.' }}
+      </span>
+    </div>
+  `,
+})
+export class TooltipControlled {
+  protected readonly open = signal(false);
+}
+```
+
+### delays.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+
+@Component({
+  selector: 'app-tooltip-delays',
+  imports: [
+    SlButton,
+    SlInline,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slInline [gap]="3" align="center">
+      <ng-container slTooltip>
+        <button slButton slTooltipTrigger variant="outline">Release hold</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>Returns SO-10483 to the pick queue in Reno.</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+      <ng-container slTooltip [openDelay]="1200" [closeDelay]="400">
+        <button slButton slTooltipTrigger variant="outline" tone="danger">Cancel order</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>Refunds $318.50 to Brightline Studio and restocks 3 lines.</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+      <ng-container slTooltip [openDelay]="200">
+        <button slButton slTooltipTrigger variant="outline">Track parcel</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>UPS · out for delivery in Portland, OR.</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+    </div>
+  `,
+})
+export class TooltipDelays {}
+```
+
+### disabled-trigger.ts
+
+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-disabled-trigger',
+  imports: [
+    SlButton,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <ng-container slTooltip>
+      <button slButton slTooltipTrigger disabled focusableWhenDisabled>Ship order</button>
+      <ng-template slTooltipLayer>
+        <div slTooltipContent>2 of 6 lines are still waiting to be picked in Savannah.</div>
+        <div slTooltipArrow></div>
+      </ng-template>
+    </ng-container>
+  `,
+})
+export class TooltipDisabledTrigger {}
+```
+
+### icon-button.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlIconButton } from '@slotted/angular/button';
+import { SlGlyph } from '@slotted/angular/icon';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-tooltip-icon-button',
+  imports: [
+    SlGlyph,
+    SlIconButton,
+    SlInline,
+    SlText,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slInline [gap]="2" align="center">
+      <span slText numeric="tabular">UPS 1Z999AA10123456784</span>
+      <ng-container slTooltip describes="label">
+        <button slIconButton slTooltipTrigger variant="ghost">
+          <svg slGlyph name="copy"></svg>
+        </button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>Copy tracking number</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+      <ng-container slTooltip describes="label">
+        <button slIconButton slTooltipTrigger variant="ghost">
+          <svg slGlyph name="external"></svg>
+        </button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>Open on the UPS site</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+    </div>
+  `,
+})
+export class TooltipIconButton {}
+```
+
+### long-content.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+
+@Component({
+  selector: 'app-tooltip-long-content',
+  imports: [
+    SlButton,
+    SlInline,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slInline [gap]="3" align="center">
+      <ng-container slTooltip>
+        <button slButton slTooltipTrigger variant="outline">Carrier exception</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>
+            UPS reported an address exception at the Memphis hub on September 29. The parcel is held
+            until Atlas Freight confirms a delivery window.
+          </div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+      <ng-container slTooltip>
+        <button slButton slTooltipTrigger variant="outline">Return label</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>RMA-2291-SO10485-1Z999AA10123456784-ATLASFREIGHT-MEMPHIS</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+    </div>
+  `,
+})
+export class TooltipLongContent {}
+```
+
+### toolbar.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlIconButton } from '@slotted/angular/button';
+import { SlGlyph, type GlyphName } from '@slotted/angular/icon';
+import { SlToolbar, SlToolbarSeparator } from '@slotted/angular/toolbar';
+import {
+  provideTooltipDefaults,
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+
+interface Action {
+  icon: GlyphName;
+  label: string;
+}
+
+const DOCUMENTS: Action[] = [
+  { icon: 'copy', label: 'Copy order number' },
+  { icon: 'file-text', label: 'Print packing slip' },
+  { icon: 'paperclip', label: 'Attach invoice' },
+];
+
+const TRACKING: Action[] = [
+  { icon: 'bell', label: 'Notify me on delivery' },
+  { icon: 'pin', label: 'Pin to overview' },
+  { icon: 'external', label: 'Open on the UPS site' },
+];
+
+@Component({
+  selector: 'app-tooltip-toolbar',
+  imports: [
+    SlGlyph,
+    SlIconButton,
+    SlToolbar,
+    SlToolbarSeparator,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  providers: [provideTooltipDefaults({ describes: 'label', size: 'sm' })],
+  template: `
+    <div slToolbar aria-label="Order SO-10485">
+      @for (action of documents; track action.label) {
+        <ng-container slTooltip>
+          <button slIconButton slTooltipTrigger size="sm" variant="ghost">
+            <svg slGlyph [name]="action.icon"></svg>
+          </button>
+          <ng-template slTooltipLayer>
+            <div slTooltipContent>{{ action.label }}</div>
+            <div slTooltipArrow></div>
+          </ng-template>
+        </ng-container>
+      }
+      <div slToolbarSeparator></div>
+      @for (action of tracking; track action.label) {
+        <ng-container slTooltip>
+          <button slIconButton slTooltipTrigger size="sm" variant="ghost">
+            <svg slGlyph [name]="action.icon"></svg>
+          </button>
+          <ng-template slTooltipLayer>
+            <div slTooltipContent>{{ action.label }}</div>
+            <div slTooltipArrow></div>
+          </ng-template>
+        </ng-container>
+      }
+    </div>
+  `,
+})
+export class TooltipToolbar {
+  protected readonly documents = DOCUMENTS;
+  protected readonly tracking = TRACKING;
+}
+```
+
+### variants.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import {
+  SlTooltip,
+  SlTooltipArrow,
+  SlTooltipContent,
+  SlTooltipLayer,
+  SlTooltipTrigger,
+} from '@slotted/angular/tooltip';
+
+@Component({
+  selector: 'app-tooltip-variants',
+  imports: [
+    SlButton,
+    SlInline,
+    SlTooltip,
+    SlTooltipArrow,
+    SlTooltipContent,
+    SlTooltipLayer,
+    SlTooltipTrigger,
+  ],
+  template: `
+    <div slInline [gap]="3" align="center">
+      <ng-container slTooltip>
+        <button slButton slTooltipTrigger variant="outline">Reserve 40 units</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>Holds 40 units of NW-4471 in Reno for 48 hours.</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+      <ng-container slTooltip variant="surface">
+        <button slButton slTooltipTrigger variant="outline">Transfer stock</button>
+        <ng-template slTooltipLayer>
+          <div slTooltipContent>Moves the units from Columbus to Savannah on the next truck.</div>
+          <div slTooltipArrow></div>
+        </ng-template>
+      </ng-container>
+    </div>
+  `,
+})
+export class TooltipVariants {}
+```