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

package/docs/app-shell.examples.md

@@ -0,0 +1,349 @@
+<!-- index: ./index.md -->
+# app-shell
+
+`data-ui="app-shell"` · Application frame with header, nav, main and aside.
+
+## Examples
+
+### Playground
+
+Aurora Logística, a freight operator’s back office, whole: the search a coordinator reaches for first, the destinations with their counts, the order table with the consignment that has no price yet, and the detail pane with its own head, body and foot. Every axis is on the controls below — change navSide and the pane moves to the other side with it; close the pane and the content takes the room.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell>
+  <header slAppShellBanner>…</header>
+  <nav slAppShellNav>…</nav>
+  <main slAppShellMain>…</main>
+  <aside slAppShellAside>…</aside>
+  <footer slAppShellFooter>…</footer>
+</div>
+```
+
+### The frame with nothing in it
+
+Every part the contract declares, drawn as its own name. Everything else on this page is a product standing in these boxes; this is the family on its own — four rows, three columns, one gutter, the card the content stands on, three clusters in the bar, and a pane with a head, a body and a foot.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell>
+  <header slAppShellBanner>
+    <div slAppShellBrand>
+      <button slAppShellNavToggle></button>
+    </div>
+    <div slAppShellCentre>…</div>
+    <div slAppShellActions>…</div>
+  </header>
+  <nav slAppShellNav>
+    <div slAppShellNavHeader>…</div>
+    <div slAppShellNavBody>…</div>
+    <div slAppShellNavFooter>…</div>
+  </nav>
+  <main slAppShellMain>…</main>
+  <aside slAppShellAside>
+    <div slAppShellAsideHeader>
+      …
+      <button slAppShellAsideToggle></button>
+    </div>
+    <div slAppShellAsideBody>…</div>
+    <div slAppShellAsideFooter>…</div>
+  </aside>
+  <footer slAppShellFooter>…</footer>
+</div>
+```
+
+### Five regions, five landmarks
+
+Each region is the HTML element that already means what it is, so none of them writes a role: header is banner, nav is navigation, main is main, aside is complementary, footer is contentinfo. The root is a div precisely so that stays true — a main inside an article is not a landmark. Cadence has no pane and no footer, and the landmark list is then exactly three.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell canvas="flush" primary="nav">
+  <nav slAppShellNav>…</nav>
+  <header slAppShellBanner>…</header>
+  <main slAppShellMain>…</main>
+</div>
+```
+
+### Three clusters, and the one that grows
+
+brand starts the line, centre takes whatever room is left, actions ends it. Aurora puts a search field with its shortcut in the middle; Cadence puts the route’s trail there and the route’s actions at the end; Átrio puts a title. What each holds is the product’s — slTextField, slBreadcrumb, slAvatar — and where it goes is the shell’s. Narrow the frame: the middle gives way first, and a control in actions keeps its width rather than breaking its label one letter per line.
+
+Excerpt — not a complete module
+
+```html
+<header slAppShellBanner>
+  <div slAppShellBrand>
+    <button slAppShellNavToggle></button>
+    <span>Aurora</span>
+  </div>
+  <div slAppShellCentre>
+    <div slTextField size="sm" variant="subtle">
+      <span slTextFieldStart><ng-icon name="lucideSearch" /></span>
+      <input slTextFieldInput type="search" placeholder="Search…" />
+    </div>
+  </div>
+  <div slAppShellActions>
+    <button slIconButton aria-label="Notifications">…</button>
+    <span slAvatar><span slAvatarFallback>AB</span></span>
+  </div>
+</header>
+```
+
+### The plane every region sits on
+
+One input decides the plane of every region at once, and each of its four values is drawn and tested in every primary and both separations. inset lifts the content and the pane onto cards over a sunken frame; flush runs every region edge to edge and draws its seams; floating lifts the column onto a card of its own as well; panel holds the column, the content and the pane in one card with the bar on the frame above it. The same product on all four.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell canvas="inset">…</div>
+<div slAppShell canvas="flush">…</div>
+<div slAppShell canvas="floating">…</div>
+<div slAppShell canvas="panel">…</div>
+```
+
+### A rule, or a tone
+
+Where two regions touch without a gutter — every seam of flush, the seams inside the panel card, the bar over the content under primary="main" — separation decides what is drawn. rule is a line. tone is no line: the chrome regions take a ground 0.036 OKLab L from the surface, and the subtle tones inside them are recomputed from that ground so a hover still answers. Under forced colours a tone separates nothing, and the rule is drawn whatever the input says.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell canvas="flush" separation="rule">…</div>
+<div slAppShell canvas="flush" separation="tone">…</div>
+<div slAppShell canvas="panel" primary="main" separation="tone">…</div>
+```
+
+### Every region repaintable, one at a time
+
+Cadence paints its column dark on a light frame with two declarations: data-slotted-scheme on the region, and one custom property for the ground. Written on the region rather than on the frame, the property resolves in the region’s scope, so the destinations, the counts and the focus ring are calibrated against the ground they are actually on. Switch the page to dark: the column stays the column, and the frame joins it.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell canvas="flush" primary="nav">
+  <nav slAppShellNav class="cadence-nav" data-slotted-scheme="dark">…</nav>
+</div>
+
+<!-- .cadence-nav { --slotted-app-shell-nav-surface: var(--slotted-surface-sunken); } -->
+```
+
+### Inline, overlaid, and the width that decides
+
+inline makes the region a column; overlay takes it out of the grid and over the content with a veil, a focus scope and inert on everything behind it; auto answers the shell’s own inline size at 600 pixels — not the window’s, which is why the narrow frame here behaves like a phone inside a wide page. Press the toggle in the overlaid frame: Escape and a press outside both close it.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell navMode="inline">…</div>
+<div slAppShell navMode="overlay">…</div>
+<div slAppShell navMode="auto">…</div>
+```
+
+### What a closed region leaves behind
+
+rail keeps a strip one mark column wide with a row’s inset on each side: every destination stays reachable by its mark, the region stays in the tab order, and the column’s own query container is what tells the rows to drop their labels. hidden takes the region out of the layout and the tab order entirely. Under primary="nav" the control stands in the column’s own foot, over the column it moves, and survives the rail.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell collapsedTo="rail" [navOpen]="false">…</div>
+<div slAppShell collapsedTo="hidden" [navOpen]="false">…</div>
+```
+
+### Two levels, one region
+
+slAppShellNavRail puts a strip of marks before the column: the modules in the strip, the destinations of the chosen module in the column. It is one nav landmark and one open state, where the field ships two sidebars with a state each. Closed to rail, the strip stays and the column goes — cut while the width moves, then out of the tab order. The control that moves the region stands at the foot of the strip, the part that survives. The module is the product’s state, held here in a signal.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell primary="main">
+  <header slAppShellBanner>…</header>
+  <nav slAppShellNav>
+    <div slAppShellNavRail aria-label="Modules">
+      @for (module of modules; track module.id) {
+        <button
+          slIconButton
+          type="button"
+          tone="secondary"
+          [variant]="module.id === moduleId() ? 'solid' : 'ghost'"
+          [attr.aria-current]="module.id === moduleId() ? 'true' : null"
+          [attr.aria-label]="module.label"
+          (click)="moduleId.set(module.id)"
+        >
+          <ng-icon [name]="module.icon" />
+        </button>
+      }
+      <button slAppShellNavToggle></button>
+    </div>
+    <div slAppShellNavHeader>{{ module().label }}</div>
+    <div slAppShellNavBody>
+      <div slSideNavigation [value]="module().current">…</div>
+    </div>
+  </nav>
+  <main slAppShellMain>…</main>
+</div>
+```
+
+### The pane opens on a selection, and closes from its own head
+
+The pane holds the second open state, under the same shape as the navigation’s: a two-way asideOpen model and asideOpenChangeRequest with a reason. Select a row and the product opens the pane; press the control in the pane’s head, or Escape when it is a layer, and it closes — the content takes the room, because a closed pane leaves no rail. The skip link to the pane exists only while it is open. Drag the pane’s inner edge, or focus it and press the arrows, Home and End: the two-way asideExtent is a fraction of the shell between minAsideExtent and maxAsideExtent, and asideExtentChangeRequest says which hand moved it.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slAppShell
+  [asideOpen]="selected() !== undefined"
+  (asideOpenChangeRequest)="$event.value ? null : selected.set(undefined)"
+>
+  <main slAppShellMain>
+    <div slTable selectionMode="single" [value]="selectedKeys()" (valueChange)="select($event)">
+      …
+    </div>
+  </main>
+  <aside slAppShellAside>
+    <div slAppShellAsideResizer></div>
+    <div slAppShellAsideHeader>
+      <span>{{ selected() }}</span>
+      <button slAppShellAsideToggle></button>
+    </div>
+    <div slAppShellAsideBody>…</div>
+    <div slAppShellAsideFooter>…</div>
+  </aside>
+</div>
+```
+
+### The layer, and what it does to the rest
+
+Átrio overlays its navigation at every width. While the layer is modal, the rest of the shell is inert — the banner and its toggle included, exactly as a dialog’s trigger is — and the ways out are Escape, the veil, a destination, and whatever control the product put in the panel. The pane is a layer of its own under the same policies: escape="none" keeps it open on Escape, outsidePress="none" keeps it open on a press outside, modal={false} draws no veil and inerts nothing.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell navMode="overlay" escape="close" outsidePress="close" modal>…</div>
+<div slAppShell asideMode="overlay" escape="none" outsidePress="none" [modal]="false">…</div>
+```
+
+### Which region reaches the corner
+
+banner spans the full width and the navigation starts below it, which is Aurora. nav spans the full height and the banner starts beside it, which is Cadence: the workspace and the bar sit on one line, and the control that moves the column stands in the column’s own head. main spans the column the full height as well and puts the bar in the plane of the content, inside the card that holds the page. The grid changes where a region is drawn and never where it is written, so the focus order is the same under all three.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell primary="banner">…</div>
+<div slAppShell primary="nav">…</div>
+<div slAppShell primary="main">…</div>
+```
+
+### Sides, sizes and the mirror
+
+Átrio puts the navigation at the end of the line and the pane at the start; the controls turn their marks with them. Switch the direction to right-to-left and the whole frame mirrors, because every distance is logical. navSize and asideSize are steps on the family’s own scale — a theme retunes a step, and nothing retunes a pixel string.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell navSide="end" navSize="sm" asideSize="sm">…</div>
+```
+
+### Who scrolls
+
+content, the default, makes the shell the height it was given — capped at 100dvh, which is the space a mobile browser actually has — and lets only the content column and the pane’s body scroll, so the banner, the column and the pane’s head and foot stay put. document lets the shell grow and the whole document scroll, and the banner travels with it; a page-header inside then owns the sticky offset on its own.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell scroll="content">…</div>
+<div slAppShell scroll="document">…</div>
+```
+
+### The wait for the next page
+
+slAppShellProgress draws an indeterminate bar on the line between the chrome and the content — wherever the canvas draws that line — after 200 ms, holds it for at least 400 ms, and marks main aria-busy for exactly as long as it is painted. A page header inside a busy content region draws no bar of its own. Pass loading from the router; nothing in the family knows one.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell>
+  <header slAppShellBanner>…</header>
+  <main slAppShellMain>…</main>
+  <div slAppShellProgress [loading]="navigating()"></div>
+</div>
+
+<!-- navigating = toSignal(router.events.pipe(filter(isStartOrEnd), map((e) => e instanceof NavigationStart))) -->
+```
+
+### The first thing a keyboard meets
+
+Press Tab from the top of the frame: a link to the content appears, then one to the navigation, then one to the pane — one per region that rendered and is open, out of the flow until focused. The content region carries tabindex="-1", so the link moves the focus as well as the scroll.
+
+Excerpt — not a complete module
+
+```html
+<div slAppShell [messages]="{ skipToMain: 'Skip to the order' }">
+  <main slAppShellMain>…</main>
+</div>
+```
+
+### Telling the reader’s choice from the layout’s
+
+Every request carries a reason. pointer and keyboard are the reader’s own choice; resize is the layout closing the region because the shell became narrow; select is a destination; escape and outsidePress are the layer. A product that persists the reader’s preference writes one line on the request — if the reason is not resize, persist — and keeps the wide preference through every narrow window the reader ever opens. Narrow the frame and read the log.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slAppShell
+  [(navOpen)]="open"
+  (navOpenChangeRequest)="$event.reason === 'resize' || persist($event.value)"
+>
+  …
+</div>
+```
+
+### Setting it once, and reaching past it
+
+provideAppShellDefaults carries every axis and the strings for every shell under the injector, and a shell that states any of them itself still wins. exportAs reaches the instance from the template: openNav, closeNav, openAside, closeAside and focusMain are the actions an input cannot express. The element the directive sits on was always the consumer’s, so there is nothing to substitute.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideAppShellDefaults({ canvas: 'flush', navSize: 'lg', primary: 'nav' })],
+});
+
+// In a template: <div slAppShell #shell="slAppShell">…</div>
+// and a button that calls shell.closeAside().
+```
+
+### The families that live inside it
+
+The shell owns where a region is drawn and nothing about what is in it. slPage with landmark="none" and scroll="ancestor" lives in the content region, so its header sticks at the top of the column the shell scrolls; an sl-drawer opened from the page lands in the shell’s own layer, over the content and under nothing; slDialog, slMenu and toasts do the same. Long translated labels truncate in the column rather than pushing the frame wider.
+
+Excerpt — not a complete module
+
+```html
+<main slAppShellMain>
+  <main slPage landmark="none" scroll="ancestor" width="full">
+    <header slPageHeader>…</header>
+    <div slPageBody>…</div>
+  </main>
+</main>
+```
+
+### The landmarks and the keyboard
+
+Walk the landmark list of this frame: banner, navigation, main, complementary, contentinfo, one of each and none of them written as a role. Then Tab through it: skip link, banner, toggle, navigation, content, pane, the pane’s control, footer — the DOM order, and it does not move when primary does. Enter and Space work both controls, which is the whole of the Disclosure pattern’s keyboard; the control takes its wiring from the shell, so it stands wherever the product wants it.
+
+Excerpt — not a complete module
+
+```html
+<nav slAppShellNav aria-label="Main navigation">…</nav>
+<aside slAppShellAside aria-label="Order details">…</aside>
+```