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

package/docs/detail-panel.md

@@ -0,0 +1,361 @@
+<!-- index: ./index.md -->
+# detail-panel
+
+`data-ui="detail-panel"` · Record summary, metadata, sections and actions.
+
+## Import
+
+```ts
+import { SlDetailPanel, SlDetailPanelBody, SlDetailPanelSection, SlDetailPanelTabs, SlDetailPanelAside, SlDetailPanelBanner, SlDetailPanelMessage, SlDetailPanelFooter, provideDetailPanelDefaults } from '@slotted/angular/detail-panel';
+```
+
+Selector: `[slDetailPanel], [slDetailPanelBody], ng-template[slDetailPanelSection], [slDetailPanelTabs], aside[slDetailPanelAside], [slDetailPanelBanner], [slDetailPanelMessage], footer[slDetailPanelFooter]` · exportAs: `slDetailPanel, slDetailPanelBody, slDetailPanelSection, slDetailPanelTabs, slDetailPanelAside, slDetailPanelFooter`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel [recordKey]="order.id">
+  <header slPageHeader>…</header>
+  <div slDetailPanelBody>
+    <ng-template slDetailPanelSection name="linhas" label="Linhas" [count]="4">
+      <sl-order-lines />
+    </ng-template>
+    <ng-template slDetailPanelSection name="historico" label="Histórico">
+      <sl-order-history />
+    </ng-template>
+    <aside slDetailPanelAside><sl-order-fields /></aside>
+  </div>
+</article>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the article carrying slDetailPanel | yes |
+| `body` | the element carrying slDetailPanelBody | yes |
+| `banner` | div | no |
+| `columns` | div | no |
+| `main` | div | no |
+| `section` | div, rendered by the body from ng-template[slDetailPanelSection] | no |
+| `section-actions` | div | no |
+| `aside` | the aside carrying slDetailPanelAside | no |
+| `message` | div | no |
+| `footer` | the footer carrying slDetailPanelFooter | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `section` | `model<string \| undefined>` | — | slDetailPanel | The current section. Two-way, so [(section)] follows it; under tabs the selected tab, under stacked the section marked data-current and scrolled under the chrome. Unbound, a tabbed panel starts on its first section and a stacked one marks none |
+| `layout` | `'stacked' \| 'tabs'` | stacked | slDetailPanel, provideDetailPanelDefaults | Every section in the flow with a heading each, or a strip in the header’s tabs slot with one section shown. The section value is the same under both |
+| `aside` | `'end' \| 'start' \| 'none'` | end | slDetailPanel, provideDetailPanelDefaults | Which column the aside takes above 600 pixels. none says the consumer renders no aside and the body is one column at every width |
+| `level` | `'1' \| '2' \| '3'` | 2 | slDetailPanel, provideDetailPanelDefaults | The heading rank the page-header defaults to, through PAGE_HEADER_DEFAULTS provided for the subtree; stacked sections take the rank below. 1 in a page of its own, 2 in a drawer or a pane |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slDetailPanel, provideDetailPanelDefaults | The page-header’s size default, the sections’ size, the gap between the columns and the aside’s track: 14, 16 or 18 rem |
+| `scroll` | `'ancestor' \| 'self'` | ancestor | slDetailPanel, provideDetailPanelDefaults | Who scrolls. ancestor for a page or a drawer, whose body scrolls; self for a pane, where the root is the scroll container and the header sticks inside it |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | slDetailPanel, provideDetailPanelDefaults | Under tabs, when a section’s template is instantiated: only while current, once it has been current, or always. Inert under stacked |
+| `status` | `'ready' \| 'not-found' \| 'error'` | ready | slDetailPanel | Whether the record is there. Under either failure the columns give way to the message and the header and footer stay |
+| `loading` | `boolean` | false | slDetailPanel | The record has not arrived: aria-busy on the root, skeleton lines in place of every section’s content and of the aside’s. The header’s own loading is bound on the header |
+| `recordKey` | `string \| number` | — | slDetailPanel | The identity of the record on screen, written as data-key. When it changes while focus is inside the root, the heading takes focus and the scroller returns to its start |
+| `messages` | `PartialMessages<DetailPanelMessages>` | — | slDetailPanel | Words laid over the language in force, key by key: the aside’s accessible name (aside), and the root’s while loading and the heading has no words yet (loading) |
+| `name` | `string` | — | slDetailPanelSection | Required. The value the section is named by in section and the URL; written as data-name |
+| `label` | `string` | — | slDetailPanelSection | Required. The tab’s words under tabs, the heading under stacked |
+| `count` | `number` | — | slDetailPanelSection | Drawn as a badge in the tab, or after the stacked heading |
+| `actions` | `TemplateRef` | — | slDetailPanelSection | The section’s own controls: in the stacked heading’s actions column, or in a row above a tabbed section |
+| `disabled` | `boolean` | false | slDetailPanelSection | Takes the tab out of the strip’s sequence. Inert under stacked |
+| `label` | `string` | — | slDetailPanelTabs | Required. The tab list’s accessible name |
+| `aria-label` | `string` | the aside message | aside[slDetailPanelAside] | A written name wins over the messages; read with HostAttributeToken before the family writes its own |
+| `[slPageHeader]` | `from @slotted/angular/page-header` | — | the root’s first child | The whole top: back, visual, heading, marks, subheading, actions, previous and next, the header area that snaps, the tabs slot. The panel provides PAGE_HEADER_DEFAULTS for its subtree from its own level and size through getters over signals; a header that states its own wins |
+| `[slDetailPanelTabs]` | `{ label }` | — | on the element in the header’s tabs slot | The strip, rendered from the sections: an [slTabs] list. slPageHeaderTabs is a host directive, so the element is the slot; a [slTabActions] child is projected beside the list. Renders nothing under stacked |
+| `ng-template[slDetailPanelSection]` | `TemplateRef` | — | inside [slDetailPanelBody] | A section is a template the body renders in either shape, which is what lets mount and loading decide whether the consumer’s view exists. Declaration order is the strip’s order |
+| `select(name, reason, source?)` | `method` | — | slDetailPanel | Asks to move the current section with a reason; the request reaches (sectionRequest) first |
+| `scrollToSection(name) / focus()` | `methods` | — | slDetailPanel, through exportAs | The move a template cannot express: the section with the reason programmatic, and focus on the page-header’s heading |
+| `provideDetailPanelDefaults` | `{ layout, aside, level, size, scroll, mount }` | — | a providers array | The six decisions an application takes once. A panel that states any of them itself still wins |
+| `native attributes` | `on every element` | — | every part | aria-*, data-*, class, style and (events) stay on the consumer’s own element; a written aria-label or aria-labelledby on the article replaces the heading wiring |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `sectionRequest` | `ChangeRequest<string \| undefined>` | Before the current section moves. The request carries the new value, the value it replaces, the reason — pointer or keyboard from the strip, programmatic from scrollToSection() or select() — the originating event, and cancel(), which refuses the move before anything commits. Under stacked the value arrives only as programmatic. |
+| `sectionChange` | `string \| undefined` | After the section moved, from the model. Bind [(section)] to follow it, or [section] and (sectionRequest) to own it. |
+| `(click), (focus), (keydown) on any part` | `the element’s own events` | Whenever the element fires them. The family handles nothing on its own parts; the strip’s keys are the tabs family’s and the header’s are the page-header’s. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `layout` | `stacked`, `tabs` | `stacked` |
+| `aside` | `end`, `start`, `none` | `end` |
+| `level` | `1`, `2`, `3` | `2` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `scroll` | `ancestor`, `self` | `ancestor` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `status` | `ready`, `not-found`, `error` | `ready` |
+
+## Rules
+
+- There is no detail or record pattern in the WAI-ARIA Authoring Practices; the governing sources are the landmark practices (w3.org/WAI/ARIA/apg/practices/landmark-regions/) for the article and the aside, and the Tabs pattern (w3.org/WAI/ARIA/apg/patterns/tabs/) for the strip, which the tabs family holds. The root is an article — one self-contained record — named by aria-labelledby the page-header’s heading once it is in the DOM, so the record is announced by its identifier and its customer; a consumer’s own aria-label wins.
+- Under layout="tabs" each section is the tabpanel of its tab: role="tabpanel", tabindex="0", aria-labelledby the tab, hidden when not current, and the tab’s aria-controls names it. The ids are the strip’s tabs family’s, handed to the panel on mount, so Tab from the selected tab lands on the shown section with the outward focus ring and then on its content. ArrowLeft, ArrowRight, Home and End on the strip are the tabs family’s, and under automatic activation each asks the panel to move section with the reason keyboard.
+- The aside is an aside element — a complementary landmark — named by the aside message, Details in English, so a reader can jump to the fields from the landmark list and hears what they are. It is never hidden below a width: content a desktop has and a phone does not is content a phone reader cannot reach, so the aside follows the sections in the flow instead.
+- Focus follows the record. When recordKey changes while document.activeElement is inside the root — the previous or next control was just pressed — the panel writes tabindex="-1" on the page-header’s heading, focuses it, and scrolls the container to its start, so a screen reader announces the new record rather than staying on a control whose record changed under it. When focus is elsewhere nothing moves.
+- While loading the root carries aria-busy="true", every placeholder is the skeleton family’s and hidden from assistive technology, the tab labels stay because they are known before the record is, and the root is named by the loading message, Loading the record in English, until the heading has words. Under status="not-found" or "error" the message replaces the columns and the header, the back control and the footer stay, so a drawer opened on a deleted record still closes.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-gap-md`, `--slotted-detail-panel-aside-size-lg`, `--slotted-detail-panel-aside-size-md`, `--slotted-detail-panel-aside-size-sm`, `--slotted-detail-panel-border`, `--slotted-detail-panel-gap-lg`, `--slotted-detail-panel-gap-md`, `--slotted-detail-panel-gap-sm`, `--slotted-detail-panel-inset-block-lg`, `--slotted-detail-panel-inset-block-md`, `--slotted-detail-panel-inset-block-sm`, `--slotted-detail-panel-rhythm`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-page-ground`, `--slotted-space-12`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`, `--slotted-surface`, `--slotted-text`, `--slotted-text-muted`, `--slotted-z-index-sticky`
+
+## Examples
+
+### Every part, written out
+
+The page-header on top with its facts and its pill; the banner about a change on the server; the columns — three stacked sections at h3 with their counts and actions, the aside of fields with a rule beside it; and the footer stuck at the bottom with two actions. Scroll the box: the header snaps, the footer stays.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel [recordKey]="order.id">
+  <header slPageHeader>…</header>
+  <div slDetailPanelBody>
+    <div slDetailPanelBanner><section slAlert tone="warning">…</section></div>
+    <ng-template slDetailPanelSection name="linhas" label="Linhas">…</ng-template>
+    <aside slDetailPanelAside>…</aside>
+  </div>
+  <footer slDetailPanelFooter><div slActionBar>…</div></footer>
+</article>
+```
+
+### layout: stacked, or tabs
+
+The same three sections and the same section value. Stacked, each has a heading with its count and its actions in the heading row; tabbed, the strip sits in the header’s tabs slot, one section is the tabpanel, and its actions move to a row above the content.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel layout="tabs" [recordKey]="order.id">
+  <header slPageHeader>
+    …
+    <div slDetailPanelTabs label="Secções do pedido"></div>
+  </header>
+  <div slDetailPanelBody>…</div>
+</article>
+```
+
+### aside: end, start, or none
+
+Where the fields stand. At the end, Jira’s and GitHub’s sidebar; at the start, HubSpot’s “about” column, with the rule on its other edge; none, and the sections take the whole width with no empty track beside them.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel aside="start" [recordKey]="order.id">…</article>
+```
+
+### Three hosts, one anatomy
+
+The same panel as a page’s content at level 1, as a drawer’s body with the drawer’s own close in the header actions, and as a split’s pane scrolling itself. Nothing in the panel names its host: scroll="self" is the one difference a pane makes.
+
+Excerpt — not a complete module
+
+```html
+<div slDrawer [(open)]="open">
+  <div slDrawerPanel>
+    <div slDrawerBody>
+      <article slDetailPanel [recordKey]="order.id">…</article>
+    </div>
+  </div>
+</div>
+
+<article slDetailPanel scroll="self" [recordKey]="order.id">…</article>
+```
+
+### Previous and next: focus follows the record
+
+Press the next control in the header, or Tab to it and press Enter: the record changes, the scroller returns to its start, and — because focus was inside the panel — the heading takes focus and a screen reader announces the new order. A recordKey changed while focus is elsewhere moves nothing.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel [recordKey]="order().id">
+  <header slPageHeader>
+    …
+    <div slPageHeaderNavigation>
+      <button slIconButton aria-label="Pedido seguinte" (click)="next()">…</button>
+    </div>
+  </header>
+  …
+</article>
+```
+
+### The section model: value, reason, mount
+
+The value is controlled and every change is a request with a reason: the strip asks with pointer or keyboard, the link under the panel with programmatic, and the log below shows each one. Under stacked the same button scrolls the named section under the chrome and marks it data-current. mount="lazy" keeps a tab’s content once it has been seen.
+
+Excerpt — not a complete module
+
+```html
+<article
+  slDetailPanel
+  layout="tabs"
+  mount="lazy"
+  [section]="section()"
+  (sectionRequest)="onRequest($event)"
+  [recordKey]="order.id"
+>
+  …
+</article>
+```
+
+### loading: the frame waits, the words arrive
+
+The record has not arrived. The heading and the subheading are the page-header’s skeleton; each section shows three placeholder lines in place of content that is not mounted; the aside four short ones. The tab labels stay, because they are known before the record is. Toggle the switch to see the words land without the frame moving.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel [loading]="loading()" [recordKey]="order.id">
+  <header slPageHeader [loading]="loading()">…</header>
+  <div slDetailPanelBody>…</div>
+</article>
+```
+
+### status: not-found, and error
+
+A record that does not exist and a request that failed need different words and different actions, so they are two statuses. Both replace the columns with the message and keep the chrome: the back link still goes back and the footer’s close still closes.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel status="not-found" recordKey="SO-2026-01900">
+  <header slPageHeader>…</header>
+  <div slDetailPanelBody>
+    <div slDetailPanelMessage>
+      <section slResultState status="not-found">
+        <div slResultStateContent>
+          <div slResultStateTitle>Este pedido já não existe</div>
+        </div>
+      </section>
+    </div>
+  </div>
+</article>
+```
+
+### banner: the record changed under the reader
+
+Marta Silva registered a payment two minutes ago. The alert sits between the header and the columns, the width of both, in the flow rather than as a toast that disappears — it is read before the stale content, and Reload is the one action.
+
+Excerpt — not a complete module
+
+```html
+<div slDetailPanelBody>
+  <div slDetailPanelBanner>
+    <section slAlert tone="warning">
+      <div slAlertContent>
+        <div slAlertTitle>Esta fatura foi alterada por outra pessoa</div>
+      </div>
+      <div slAlertActions>
+        <button slButton size="sm" tone="warning">Recarregar</button>
+      </div>
+    </section>
+  </div>
+  …
+</div>
+```
+
+### footer: the actions that stay
+
+In a box that scrolls itself the footer stays at the bottom edge, painted so the content passes under it, with an ActionBar inside aligned to the column above. Scroll to the end: the last section stops above the footer, not behind it.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel scroll="self" [recordKey]="order.id">
+  …
+  <footer slDetailPanelFooter>
+    <div slActionBar aria-label="Ações do pedido" variant="plain">
+      <div slActionBarActions>
+        <div slActionBarAction><button slButton variant="ghost">Fechar</button></div>
+        <div slActionBarAction><button slButton tone="accent">Registar pagamento</button></div>
+      </div>
+    </div>
+  </footer>
+</article>
+```
+
+### size: sm, md, lg
+
+One step moves the header’s title, the sections’ headings, the gap between the columns and the aside’s track together: 14, 16 and 18 rem. The size says nothing about rank — every heading here is the same h2.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel size="sm" [recordKey]="order.id">…</article>
+```
+
+### Below 600 pixels
+
+The root measures its own width, not the viewport. At 360 pixels the columns are one: the aside follows the sections in the flow with a rule above it, the header’s actions wrap under the title, and nothing is hidden — a phone reader reaches every field a desktop reader does.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel [recordKey]="order.id">…</article>
+```
+
+### Content the family did not choose
+
+A title of a whole sentence, clamped by the page-header at three lines with the full text in its title attribute; a supplier reference with no spaces, which the aside wraps rather than widening; and twelve sections, whose strip scrolls with paging controls that are the tabs family’s own.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel layout="tabs" [recordKey]="order.id">
+  <header slPageHeader>…</header>
+  <div slDetailPanelBody>
+    @for (month of months; track month) {
+      <ng-template slDetailPanelSection [name]="month" [label]="month">…</ng-template>
+    }
+  </div>
+</article>
+```
+
+### What a section holds, and what sits beside it
+
+A Table in the lines section, a Timeline feed in the history, a DescriptionList of fields in the aside with a copy control on the invoice, a Toolbar with overflow in the header’s actions and a Tag in its marks. Each is placed by the panel and owned by its own family; the panel writes none of their behaviour.
+
+Excerpt — not a complete module
+
+```html
+<ng-template slDetailPanelSection name="historico" label="Histórico">
+  <div slTimeline label="Histórico do pedido" order="newest-first">
+    @for (event of history; track event.time) {
+      <li slTimelineItem [title]="event.title" [time]="event.time"></li>
+    }
+  </div>
+</ng-template>
+```
+
+### Setting it once, and reaching past it
+
+The provider carries the layout, the aside’s side, the rank, the size, who scrolls, and the mount policy for every panel under it; the two panels here state nothing and both read tabbed with the fields at the start. The handle reaches focus() and scrollToSection().
+
+Excerpt — not a complete module
+
+```ts
+@Component({
+  providers: [provideDetailPanelDefaults({ aside: 'start', layout: 'tabs' })],
+})
+export class OrdersPage {}
+```
+
+### What a reader hears
+
+The article is named by the heading, so the record is announced by its identifier and customer; the aside is a complementary landmark named by the aside message; under tabs, Tab from the strip lands on the tabpanel with the outward ring and then on the table inside it. Press next: the heading takes focus and says the new record.
+
+Excerpt — not a complete module
+
+```html
+<article slDetailPanel aria-label="Pedido de venda SO-2026-01842" [recordKey]="order.id">…</article>
+```