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

package/docs/page-header.md

@@ -0,0 +1,338 @@
+<!-- index: ./index.md -->
+# page-header
+
+`data-ui="page-header"` · Page title, description and actions.
+
+## Import
+
+```ts
+import { SlPageHeader, SlPageHeaderTitleArea, SlPageHeaderNav, SlPageHeaderBack, SlPageHeaderBreadcrumbs, SlPageHeaderTitleRow, SlPageHeaderVisual, SlPageHeaderTitle, SlPageHeaderHeading, SlPageHeaderMarks, SlPageHeaderSubheading, SlPageHeaderActions, SlPageHeaderNavigation, SlPageHeaderArea, SlPageHeaderFigure, SlPageHeaderContent, SlPageHeaderDescription, SlPageHeaderControls, SlPageHeaderToggle, SlPageHeaderPin, SlPageHeaderProgress, SlPageHeaderTabs, providePageHeaderDefaults } from '@slotted/angular/page-header';
+```
+
+Selector: `[slPageHeader], [slPageHeaderTitleArea], [slPageHeaderNav], [slPageHeaderBack], [slPageHeaderBreadcrumbs], [slPageHeaderTitleRow], [slPageHeaderVisual], [slPageHeaderTitle], [slPageHeaderHeading], [slPageHeaderMarks], [slPageHeaderSubheading], [slPageHeaderActions], [slPageHeaderNavigation], [slPageHeaderArea], [slPageHeaderFigure], [slPageHeaderContent], [slPageHeaderDescription], [slPageHeaderControls], button[slPageHeaderToggle], button[slPageHeaderPin], [slPageHeaderProgress], [slPageHeaderTabs]` · exportAs: `slPageHeader, slPageHeaderHeading, slPageHeaderArea, slPageHeaderToggle, slPageHeaderPin, slPageHeaderProgress`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<main slPage>
+  <header slPageHeader [(expanded)]="expanded" [(pinned)]="pinned">
+    <div slPageHeaderTitleArea>…</div>
+    <div slPageHeaderArea>…</div>
+    <div slPageHeaderControls>
+      <button slPageHeaderToggle></button>
+      <button slPageHeaderPin></button>
+    </div>
+  </header>
+  <div slPageBody>…</div>
+  <footer slPageFooter>…</footer>
+</main>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the header carrying slPageHeader | yes |
+| `title-area` | the element carrying slPageHeaderTitleArea | yes |
+| `nav` | the element carrying slPageHeaderNav | no |
+| `back` | the a or button carrying slPageHeaderBack | no |
+| `breadcrumbs` | the element carrying slPageHeaderBreadcrumbs | no |
+| `title-row` | the element carrying slPageHeaderTitleRow | yes |
+| `visual` | the element carrying slPageHeaderVisual | no |
+| `title` | the element carrying slPageHeaderTitle | yes |
+| `heading` | the h1 to h3 carrying slPageHeaderHeading, or any element, which then gets role="heading" | yes |
+| `marks` | the element carrying slPageHeaderMarks | no |
+| `subheading` | the p carrying slPageHeaderSubheading | no |
+| `actions` | the element carrying slPageHeaderActions | no |
+| `navigation` | the element carrying slPageHeaderNavigation | no |
+| `header-area` | the element carrying slPageHeaderArea, role="region" | no |
+| `figure` | the element carrying slPageHeaderFigure | no |
+| `content` | the element carrying slPageHeaderContent | no |
+| `description` | the p carrying slPageHeaderDescription | no |
+| `controls` | the element carrying slPageHeaderControls | no |
+| `toggle` | the button carrying slPageHeaderToggle | no |
+| `pin` | the button carrying slPageHeaderPin | no |
+| `tabs` | the element carrying slPageHeaderTabs | no |
+| `progress` | the consumer’s element carrying slPageHeaderProgress, holding one [slProgressBar] at placement="edge-end" | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `expanded` | `model<boolean>` | true | slPageHeader | Whether the header area is open. Two-way, so [(expanded)] follows it; true at rest, pinned or revealed, false while scrolled past or collapsed by the control |
+| `pinned` | `model<boolean>` | false | slPageHeader | Whether the pin holds the area open. Two-way. Pinned, the whole header stays while the page scrolls |
+| `variant` | `'band' \| 'plain' \| 'floating'` | band | slPageHeader, providePageHeaderDefaults | band is a strip of the surface with a hairline under it, the page’s own header; plain paints no ground at rest and takes the surface back once content passes under the chrome (data-stuck), for a header inside a region with a ground of its own; floating is a box with the hairline all round and rounded corners that, once stuck, slides to an inset below the scroller’s edge and lifts by a shadow, for a header that stands inside padding |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slPageHeader, providePageHeaderDefaults | The step the title sits at, on the type scale. The snapped title takes the step below |
+| `level` | `'1' \| '2' \| '3'` | 1 | slPageHeader, providePageHeaderDefaults | The rank of the heading. A native heading element written by the consumer is left alone; any other element carrying slPageHeaderHeading gets role="heading" and this level |
+| `collapse` | `'scroll' \| 'manual'` | scroll | slPageHeader, providePageHeaderDefaults | scroll collapses the area when it leaves the scrollport and re-opens it when it returns; manual leaves it to the toggle, the pin and the application, and the whole header stays while the page scrolls |
+| `loading` | `boolean` | false | slPageHeader | The heading, the subheading and the description render slSkeletonText in place of their words; the actions stay operable; the root carries aria-busy |
+| `messages` | `Partial<PageHeaderMessages>` | — | slPageHeader | Words laid over the language in force, key by key — expand, collapse, pin, unpin, headerArea and progress: the names the two controls, the region and the refresh bar carry. An aria-label written on the control itself still wins |
+| `slPageHeaderProgress` | `loading, value, min, max, buffer, valueText, label, tone, size, delay, minDuration; (withdraw)` | loading true, delay 200, minDuration 400, size sm | slPageHeaderProgress | A refresh of the data already on screen. Each input reaches the bar, (withdraw) reports the moment it goes, and provideProgressIndicatorDefaults() wins over the header’s timing |
+| `data-when` | `'expanded' \| 'snapped'` | — | any part of the title area | Shows the part in one state only. A snapped heading is the heading written twice, once with each value; the stylesheet shows one |
+| `slPageHeaderHeading on any element` | `directive` | — | the consumer’s own element | A native heading gets nothing added; an input, a link or a div gets role="heading" and the level, so an editable title keeps its rank |
+| `exportAs slPageHeader` | `SlPageHeader` | — | a template reference | expand(), collapseArea(), pin() and unpin(), each carrying programmatic; expanded, pinned, scrolled and revealed as signals |
+| `providePageHeaderDefaults()` | `{ size, level, collapse }` | — | an injector | The three decisions an application takes once. A header that states any of them itself still wins |
+| `slPage around it` | `SlPage` | — | the page | The measure the header aligns its rows to, injected. Outside a page the rows take the content width |
+| `native attributes` | `on every part` | — | every part | Every directive sits on the consumer’s own element, so id, class, routerLink and every listener stay where they were written |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `expandedRequest` | `ChangeRequest<boolean>` | Before the header area moves. The request carries the new value, the value it replaces, the reason — pointer, keyboard, scroll or programmatic — the originating event, and cancel(), which refuses the move before anything commits. A cancelled scroll leaves the area where the scroll left it. |
+| `expandedChange` | `boolean` | After the area moved, from the model. Bind [(expanded)] to follow it, or [expanded] and (expandedRequest) to own it. |
+| `pinnedRequest` | `ChangeRequest<boolean>` | Before the pin moves, with the reason pointer, keyboard or programmatic. Pinning a collapsed header also asks the area to open, with the reason programmatic; collapsing by the toggle while pinned asks the pin to let go first. |
+| `pinnedChange` | `boolean` | After the pin moved, from the model. |
+| `(click), (focus), (keydown) on the toggle and the pin` | `the element’s own events` | Whenever the button fires them. The consumer’s handler runs as well, and preventDefault() in (click) refuses the move. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `variant` | `band`, `plain`, `floating` | `band` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `level` | `1`, `2`, `3` | `1` |
+| `collapse` | `scroll`, `manual` | `scroll` |
+
+## Rules
+
+- The practice is the WAI-ARIA APG’s Landmark Regions (w3.org/WAI/ARIA/apg/practices/landmark-regions/), the toggle answers the Disclosure pattern and the pin the Button pattern’s toggle form. The root is a header element inside the page’s main, which is a plain header and not a banner: the banner is the application shell’s.
+- The whole keyboard is the platform’s. The toggle and the pin are the consumer’s own buttons, so Enter and Space move them without the family binding a key; Tab walks the title area in document order and then the header area while it is visible. The title area is deliberately not a button, because it holds links and buttons of its own and a button may not contain a control.
+- The toggle carries aria-expanded and aria-controls naming the header area; the header area is a region named by the headerArea message; the pin carries aria-pressed. Their names say which way they move, and an aria-label written on the element wins over them — read with HostAttributeToken before anything is written.
+- Collapsed by the control, the area is inert and aria-hidden, because a 0fr row leaves its controls in the DOM and out of sight. Scrolled past, it is neither: a control inside it that receives focus is scrolled back into view by the browser, and the header re-opens with the reason scroll.
+- The heading is the consumer’s element: h1 to h3 written by hand keep their native semantics, and anything else carrying the directive gets role="heading" and aria-level from the level input, so an editable title stays a heading. A snapped heading written with data-when is display: none in the other state, so the heading list never shows the title twice.
+- The reason on every request is what lets a product tell the reader’s own move from the scroll’s: pointer and keyboard are the reader, programmatic is the application, and scroll is the page. The React binding emits the same request on onExpandedChange and onPinnedChange.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-radius`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--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-2xl`, `--slotted-font-size-3xl`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xl`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-2xl`, `--slotted-line-height-3xl`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xl`, `--slotted-page-header-background`, `--slotted-page-header-border`, `--slotted-page-header-control-size`, `--slotted-page-header-description-measure`, `--slotted-page-header-gap`, `--slotted-page-header-heading-size-lg`, `--slotted-page-header-heading-size-md`, `--slotted-page-header-heading-size-sm`, `--slotted-page-header-inset`, `--slotted-page-header-padding-block`, `--slotted-page-header-radius`, `--slotted-page-header-shadow`, `--slotted-page-header-snapped-heading-size-lg`, `--slotted-page-header-snapped-heading-size-md`, `--slotted-page-header-snapped-heading-size-sm`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-shadow-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-toolbar-inset`, `--slotted-z-index-sticky`
+
+## Examples
+
+### Every part, written out
+
+The way back and the breadcrumbs above; the visual, the heading with its mark and subheading, the actions and the record navigation on the title row; the description and the facts in the area that collapses; the pill on the edge; the tabs under it.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader>
+  <div slPageHeaderTitleArea>
+    <div slPageHeaderNav>
+      <a slPageHeaderBack routerLink="/pedidos">Pedidos de compra</a>
+      <div slPageHeaderBreadcrumbs><nav slBreadcrumb>…</nav></div>
+    </div>
+    <div slPageHeaderTitleRow>
+      <span slPageHeaderVisual
+        ><span slAvatar name="Aurora Logística" shape="square" size="lg" [src]="logo"></span
+      ></span>
+      <div slPageHeaderTitle>
+        <h1 slPageHeaderHeading>Pedido de compra PC-2026-004521</h1>
+        <span slPageHeaderMarks
+          ><span slTag tone="warning"><span slTagBody>Em análise</span></span></span
+        >
+        <p slPageHeaderSubheading>Aurora Logística Ltda</p>
+      </div>
+      <div slPageHeaderActions>
+        <div slToolbar aria-label="Ações do pedido" overflow="menu">…</div>
+      </div>
+      <div slPageHeaderNavigation>…</div>
+    </div>
+  </div>
+  <div slPageHeaderArea>
+    <div slPageHeaderFigure>…</div>
+    <div slPageHeaderContent><p slPageHeaderDescription>…</p></div>
+  </div>
+  <div slPageHeaderControls>
+    <button slPageHeaderToggle></button>
+    <button slPageHeaderPin></button>
+  </div>
+  <div slPageHeaderTabs><div slTabs>…</div></div>
+</header>
+```
+
+### What a scroll does, and what the control does
+
+Scroll the first screen: the area leaves with the reason scroll and the toggle offers to bring it back in place. Press the toggle at rest: the area folds as a grid track. The last screen is collapse="manual": the whole header stays while the page scrolls. In an slPage with fill nothing scrolls outside the body: a scroller inside it snaps the area shut once it is past 16 pixels down, and opens it again back at its top. A header with no header area stays expanded: collapsed, it would hide nothing and only step the title down.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader (expandedRequest)="remember($event)">…</header>
+```
+
+### The pin
+
+Pressed, the whole header stays while the page scrolls and the area counts into the chrome. Let go while stuck and the area stays revealed until the next scroll; collapse by the toggle and the pin lets go first. Narrow the stage below 600 pixels, or shorten the window until the header would take most of it: the pin goes, and a held header is let go.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader [(pinned)]="pinned" (pinnedRequest)="onPin($event)">…</header>
+```
+
+### A title for the bar, and a title for the header
+
+The long title is written for expanded and the short one for snapped; the stylesheet shows one, so the accessibility tree has one heading at a time. Scroll to watch them swap.
+
+Excerpt — not a complete module
+
+```html
+<div slPageHeaderTitle>
+  <h1 slPageHeaderHeading data-when="expanded">
+    Relatório de conformidade fiscal do terceiro trimestre
+  </h1>
+  <h1 slPageHeaderHeading data-when="snapped">Conformidade fiscal · T3</h1>
+  <p slPageHeaderSubheading data-when="expanded">Consolidado das 14 filiais</p>
+</div>
+```
+
+### The step the title sits at
+
+sm for a header inside a pane, md for a screen, lg for the landing screen of a module. The snapped title always takes the step below, and level is a separate decision: an h2 may be lg.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader level="2" size="lg">…</header>
+```
+
+### Previous and next record
+
+The two arrows at the far end of the title row move between orders without leaving the screen; the heading, the mark and the subheading follow. Below 600 pixels the pair wraps under the title with the actions.
+
+Excerpt — not a complete module
+
+```html
+<div slPageHeaderNavigation>
+  <button slIconButton aria-label="Pedido anterior" variant="ghost" (click)="previous()">…</button>
+  <button slIconButton aria-label="Pedido seguinte" variant="ghost" (click)="next()">…</button>
+</div>
+```
+
+### Actions that fold
+
+Six actions in an slToolbar with overflow="menu". Drag the stage narrower: what does not fit folds into the toolbar’s menu, in priority order, and the header itself decides nothing about it.
+
+Excerpt — not a complete module
+
+```html
+<div slPageHeaderActions>
+  <div slToolbar aria-label="Ações do pedido" overflow="menu">
+    <div slToolbarItem [slToolbarItemCounterpart]="reprovar">
+      <button slButton variant="outline">Reprovar</button>
+    </div>
+    <div slToolbarItem><button slButton tone="accent">Aprovar</button></div>
+    <sl-toolbar-overflow />
+  </div>
+</div>
+<ng-template #reprovar><button slMenuItem>Reprovar</button></ng-template>
+```
+
+### Tabs under the header
+
+The tabs are the last thing in the root, so once the area has scrolled past they sit under the title with nothing between; the body switches with them. Scroll, then switch tabs: the header does not move.
+
+Excerpt — not a complete module
+
+```html
+<div slPageHeaderTabs>
+  <div slTabs [(value)]="tab">
+    <div slTabList aria-label="Secções do pedido">
+      <div slTab value="itens">Itens</div>
+      <div slTab value="historico">Histórico</div>
+    </div>
+  </div>
+</div>
+```
+
+### While the record arrives
+
+Press Carregar: the heading, the subheading and the description stand as slSkeletonText of their own width, the root says aria-busy, and the actions stay operable. Nothing moves when the words arrive.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader [loading]="order() === undefined">…</header>
+```
+
+### A refresh of what is on screen
+
+slPageHeaderProgress draws an indeterminate bar over the line where the chrome ends, after 200 ms and for at least 400 ms. With tabs that line is the one the pill straddles, never the tab strip’s edge; without them it is the root’s hairline. The header writes no aria-busy: the region that waits — the page body — is the consumer’s to mark.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader>
+  <div slPageHeaderTitleArea>…</div>
+  <div slPageHeaderControls>…</div>
+  <div slPageHeaderProgress [loading]="refreshing()"></div>
+  <div slPageHeaderTabs>…</div>
+</header>
+```
+
+### Content the family did not choose
+
+A nine-word title clamps at two lines; five marks wrap; a subheading of fifteen words wraps expanded and truncates snapped; a translated description keeps its measure. Scroll to see the bar hold one line.
+
+Excerpt — not a complete module
+
+```html
+<h1 slPageHeaderHeading>
+  Renovação do contrato de fornecimento continuado de pneus, câmaras e serviços de recapagem para a
+  frota pesada da regional Sudeste
+</h1>
+```
+
+### Below 600 pixels
+
+The family answers its own inline size: the header is not sticky and scrolls away with the page, nothing collapses it on scroll and the toggle still folds the area in place; the breadcrumbs go and the way back stays, the title steps down, the subheading takes one line, and the figure takes a row above the content. Actions written as slToolbar overflow="menu", each item with its counterpart, stay on the title row and fold what does not fit into the menu, where every action is still reachable; loose actions and the navigation take the row under the title.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader>…</header>
+```
+
+### A page, a table, and the chrome they share
+
+Inside an slPage the rows align to its measure, the sections’ sticky headers and the table’s sticky column header stop under the page chrome — pinned, they stop lower — and the footer stays at the bottom. Scroll the whole screen.
+
+Excerpt — not a complete module
+
+```html
+<main slPage>
+  <header slPageHeader>…</header>
+  <div slPageBody>
+    <section slSection sticky>
+      <div slSectionHeader>…</div>
+      <div slSectionBody><div slTable stickyHeader stickyTo="page">…</div></div>
+    </section>
+  </div>
+  <footer slPageFooter>…</footer>
+</main>
+```
+
+### Setting it once, and reaching past it
+
+providePageHeaderDefaults carries size, level and collapse for every header under it; the heading directive sits on the consumer’s own input while the family keeps the rank; the instance moves the area with the reason programmatic.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [providePageHeaderDefaults({ collapse: 'manual', size: 'sm' })],
+});
+```
+
+### The keyboard, the reasons, and what a reader hears
+
+Tab walks the way back, the breadcrumbs, the actions, the navigation, the toggle and the pin, then the filters inside the area. Enter and Space on the toggle report keyboard; a click reports pointer; a scroll reports scroll. Tab into the collapsed area and watch it come back.
+
+Excerpt — not a complete module
+
+```html
+<header slPageHeader (expandedRequest)="reasons.unshift($event.reason)">…</header>
+```