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

package/dist/docs/tooltip.md

@@ -0,0 +1,138 @@
+<!-- index: ./index.md -->
+# tooltip
+
+`data-ui="tooltip"` · Short label shown on hover or focus.
+
+## Import
+
+```tsx
+import {
+  Tooltip,
+  TooltipArrow,
+  TooltipContent,
+  TooltipDefaultsProvider,
+  TooltipLayer,
+  TooltipTrigger,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import {
+  Tooltip,
+  TooltipArrow,
+  TooltipContent,
+  TooltipLayer,
+  TooltipTrigger,
+} from '@slotted/react/tooltip';
+
+export default function TooltipBasic() {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        render={(props) => (
+          <Button {...props} variant="outline">
+            Sync inventory
+          </Button>
+        )}
+      />
+      <TooltipLayer>
+        <TooltipContent>Pulls stock levels from Reno, Columbus and Savannah.</TooltipContent>
+        <TooltipArrow />
+      </TooltipLayer>
+    </Tooltip>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `content` | div | yes |
+| `arrow` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | Tooltip | The open state of a controlled tooltip. Update it from onOpenChange: the tooltip opens and closes only when the new value comes back. A tooltip that receives open stays controlled for as long as it is mounted. |
+| `defaultOpen` | `boolean` | false | Tooltip | The state an uncontrolled tooltip starts in. It is read once, on mount. |
+| `variant` | `'inverse' \| 'surface'` | inverse | Tooltip | 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 | Tooltip | 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 | Tooltip | 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 | Tooltip | 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 or the handle. |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | top | Tooltip | 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 | Tooltip | 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 | Tooltip | 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 | Tooltip | 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 | Tooltip | Whether the layer draws the arrow. |
+| `hoverable` | `boolean` | true | Tooltip | 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 | Tooltip | Whether pressing the trigger closes the tooltip, so it is not left over the dialog its button opened. |
+| `flip` | `boolean` | true | Tooltip | Whether the tooltip moves to the opposite edge when the preferred edge has no room. |
+| `shift` | `boolean` | true | Tooltip | Whether the tooltip slides along its edge to stay inside the boundary. |
+| `hideWhenDetached` | `boolean` | true | Tooltip | 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 | Tooltip | 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 | Tooltip | 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 | Tooltip | 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 | Tooltip | Milliseconds the pointer rests on the trigger before the tooltip opens. Keyboard focus opens it without waiting. |
+| `closeDelay` | `number` | 150 | Tooltip | 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 | TooltipDefaultsProvider | Milliseconds after one tooltip closes during which the next one under the same provider opens without openDelay, so a row of buttons pays the wait once. It is set on the provider, because every tooltip under it shares the window. |
+| `touchDelay` | `number` | 500 | Tooltip | 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 | Tooltip | 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 | Tooltip | Distance in pixels the tooltip moves along its edge from the aligned position. |
+| `collisionPadding` | `number` | 8 | Tooltip | The smallest distance in pixels between the tooltip and the edge of the boundary. |
+| `arrowPadding` | `number` | 8 | Tooltip | 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. |
+| `render` | `(props) => ReactNode` | — | TooltipTrigger, TooltipLayer, TooltipContent, TooltipArrow | Renders the part into an element of your own. TooltipTrigger nearly always uses it, because the trigger is a control the page already has, such as a Button or an IconButton. The tooltip writes only the ARIA reference and data-open on the trigger, and no data-part, so the control keeps its own styling. |
+| `ref` | `Ref<TooltipHandle>` | — | Tooltip | open(), close() and reposition(), for the three actions a prop cannot express. |
+| `TooltipDefaultsProvider` | `component` | — | application | Sets any axis and any delay once for every tooltip under it, and holds the group window. A value set on one tooltip wins. |
+| `container` | `Element \| null` | document.body | TooltipDefaultsProvider | The element every layer under the provider renders into, set through setPortalContainer. An application shell with its own stacking context names it once. |
+| `native props` | `ComponentPropsWithRef` | — | every part | Each part accepts the props of its element. An onPointerEnter, onFocus or onClick written on the trigger runs before the handler of the tooltip, and event.preventDefault() in it skips that handler. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `(open: boolean, request: TooltipChangeRequest)` | Called once per change, before the layer moves. The request carries value, previous, reason (pointer, keyboard, escape, blur or programmatic) and the originating event. request.cancel() refuses the change, and an uncontrolled tooltip then stays as it is. |
+
+## 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/dist/docs/top-navigation.examples.md

@@ -0,0 +1,327 @@
+<!-- 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
+
+```tsx
+<TopNavigation>
+  <TopNavigationBrand>
+    <TopNavigationHome href="/">
+      <TopNavigationMark>…</TopNavigationMark>
+      <TopNavigationName>name</TopNavigationName>
+    </TopNavigationHome>
+  </TopNavigationBrand>
+  <TopNavigationContext>…</TopNavigationContext>
+  <TopNavigationNav>
+    <TopNavigationList>
+      <TopNavigationItem value="link">
+        <TopNavigationLink href="/link">link</TopNavigationLink>
+      </TopNavigationItem>
+      <TopNavigationItem value="trigger">
+        <TopNavigationTrigger>trigger</TopNavigationTrigger>
+      </TopNavigationItem>
+    </TopNavigationList>
+  </TopNavigationNav>
+  <TopNavigationSearch>…</TopNavigationSearch>
+  <TopNavigationActions>
+    <TopNavigationHelp href="/help" />
+    <TopNavigationNotifications>
+      <TopNavigationCount>3</TopNavigationCount>
+    </TopNavigationNotifications>
+    <TopNavigationAccount>…</TopNavigationAccount>
+  </TopNavigationActions>
+</TopNavigation>;
+```
+
+### 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
+
+```tsx
+<TopNavigationList>
+  <TopNavigationItem priority="high" value="painel">
+    <TopNavigationLink href="/painel">Painel</TopNavigationLink>
+  </TopNavigationItem>
+  <TopNavigationItem value="rotas">
+    <TopNavigationLink href="/rotas">Rotas</TopNavigationLink>
+  </TopNavigationItem>
+  <TopNavigationItem priority="low" value="faturacao">
+    <TopNavigationLink href="/faturacao">Faturação</TopNavigationLink>
+  </TopNavigationItem>
+</TopNavigationList>;
+```
+
+### 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
+
+```tsx
+const [moreOpen, setMoreOpen] = useState(false);
+
+<TopNavigation moreOpen={moreOpen} onMoreOpenChange={(open) => setMoreOpen(open)}>
+  …
+</TopNavigation>;
+```
+
+### 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
+
+```tsx
+<TopNavigationSearch>
+  <TextField
+    aria-label="Procurar"
+    end={<Shortcut keys="mod+k" size="sm" variant="soft" />}
+    placeholder="Procurar cargas, clientes, rotas…"
+    start={<Search aria-hidden size={16} />}
+    type="search"
+    variant="subtle"
+  />
+</TopNavigationSearch>;
+```
+
+### 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
+
+```tsx
+<TopNavigationItem value="frota">
+  <TopNavigationTrigger>Frota</TopNavigationTrigger>
+  <NavigationMenuContent>
+    <NavigationMenuLinks>
+      <li>
+        <NavigationMenuLink href="/fleet/vehicles">Veículos</NavigationMenuLink>
+      </li>
+    </NavigationMenuLinks>
+  </NavigationMenuContent>
+</TopNavigationItem>;
+```
+
+### 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
+
+```tsx
+const [value, setValue] = useState<string | null>('cargas');
+
+<TopNavigation value={value} onValueChange={(next) => setValue(next)}>
+  …
+</TopNavigation>;
+```
+
+### 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
+
+```tsx
+<TopNavigationActions>
+  <TopNavigationHelp href="/ajuda" />
+  <Popover>
+    <PopoverTrigger
+      render={(props) => (
+        <TopNavigationAction {...props} aria-label={`Aprovações, ${pending} pendentes`}>
+          <ClipboardCheck />
+          <TopNavigationCount>{pending}</TopNavigationCount>
+        </TopNavigationAction>
+      )}
+    />
+    <PopoverContent>…</PopoverContent>
+  </Popover>
+  <Popover>
+    <PopoverTrigger
+      render={(props) => (
+        <TopNavigationNotifications {...props}>
+          <TopNavigationCount>12</TopNavigationCount>
+        </TopNavigationNotifications>
+      )}
+    />
+    <PopoverContent>…</PopoverContent>
+  </Popover>
+  <Menu>
+    <MenuTrigger
+      render={(props) => (
+        <TopNavigationAccount {...props}>
+          <Avatar size="xs">AB</Avatar>
+        </TopNavigationAccount>
+      )}
+    />
+    <MenuContent>…</MenuContent>
+  </Menu>
+</TopNavigationActions>;
+```
+
+### What the application is right now
+
+A workspace switcher and an environment badge after the brand. On a phone the whole region moves to the top of the panel — the same elements, so the switcher still opens its menu there.
+
+Excerpt — not a complete module
+
+```tsx
+<TopNavigationContext>
+  <Menu>
+    <MenuTrigger
+      render={(props) => (
+        <Button
+          {...props}
+          end={<ChevronsUpDown aria-hidden />}
+          size="sm"
+          tone="secondary"
+          variant="ghost"
+        >
+          Porto · Operações
+        </Button>
+      )}
+    />
+    <MenuContent>…</MenuContent>
+  </Menu>
+  <Badge size="sm" tone="warning" variant="soft">
+    Homologação
+  </Badge>
+</TopNavigationContext>;
+```
+
+### 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
+
+```tsx
+<TopNavigation size="sm">…</TopNavigation>;
+```
+
+### 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
+
+```tsx
+<TopNavigationItem disabled value="faturacao">
+  <TopNavigationLink href="/faturacao">Faturação</TopNavigationLink>
+</TopNavigationItem>;
+```
+
+### 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
+
+```tsx
+<TopNavigationAccount>
+  <Avatar size="xs">MB</Avatar>
+  <span>Maria Bartolomeu</span>
+</TopNavigationAccount>;
+```
+
+### 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
+
+```tsx
+<AppShell>
+  <AppShellBanner>
+    <TopNavigation defaultValue="painel">
+      <TopNavigationBrand>
+        <AppShellNavToggle />
+        <TopNavigationHome href="/">…</TopNavigationHome>
+      </TopNavigationBrand>
+      …
+    </TopNavigation>
+  </AppShellBanner>
+  <AppShellNav>…</AppShellNav>
+  <AppShellMain>…</AppShellMain>
+</AppShell>;
+```
+
+### 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
+
+```tsx
+<>
+  <TopNavigation skipTo="conteudo">…</TopNavigation>
+  <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
+
+```tsx
+<TopNavigationDefaultsProvider size="lg">
+  <TopNavigation>…</TopNavigation>
+</TopNavigationDefaultsProvider>;
+```
+
+### Composed with what sits beside it
+
+A router’s link as the destination through render, which is where aria-current comes from; a Badge in the context; a Kbd in the search; Menu on a section, on the account and on the workspace; Popover on the bell.
+
+Excerpt — not a complete module
+
+```tsx
+<TopNavigationItem value="cargas">
+  <TopNavigationLink render={(props) => <NavLink {...props} to="/cargas" />}>
+    Cargas
+  </TopNavigationLink>
+</TopNavigationItem>;
+```
+
+### 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
+
+```tsx
+<TopNavigation
+  onMoreOpenChange={(open, request) => log(request.reason)}
+  onSearchOpenChange={(open, request) => log(request.reason)}
+  onValueChange={(value, request) => log(request.reason)}
+>
+  …
+</TopNavigation>;
+```
+
+### What a reader hears
+
+A banner landmark holding a navigation landmark with a list of links, one of them current; a button named Mais 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
+
+```tsx
+<TopNavigation aria-label="Aurora">
+  <TopNavigationNav aria-label="Principal">…</TopNavigationNav>
+</TopNavigation>;
+```