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

package/docs/loading-overlay.md

@@ -0,0 +1,248 @@
+<!-- index: ./index.md -->
+# loading-overlay
+
+`data-ui="loading-overlay"` · Veil and indicator over a loading region.
+
+## Import
+
+```ts
+import { SlLoadingOverlay, SlLoadingOverlayCancel, provideLoadingOverlayDefaults } from '@slotted/angular/loading-overlay';
+```
+
+Selector: `[slLoadingOverlay] · [slLoadingOverlayCancel]` · exportAs: `slLoadingOverlay`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<section slLoadingOverlay [loading]="saving()" [messages]="{ label: 'Saving changes' }">
+  <app-billing-form />
+</section>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element you put slLoadingOverlay on | yes |
+| `announcement` | span | yes |
+| `content` | div | no |
+| `scrim` | div | yes |
+| `panel` | div | no |
+| `indicator` | span | no |
+| `label` | span | no |
+| `description` | span | no |
+| `cancel` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `loading` | `boolean` | true | SlLoadingOverlay | Whether the data is still on its way. The consumer’s own fact: the family never moves it, so it is an input() and not a model() |
+| `scope` | `'region' \| 'page'` | region | SlLoadingOverlay | What is covered. region is the element the directive sits on; page is the whole viewport, portalled and modal |
+| `veil` | `'wash' \| 'blur' \| 'none'` | wash | SlLoadingOverlay | How the covered content is obscured. none blocks exactly as much and dims nothing |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlLoadingOverlay | The panel’s step: its padding, its type, and the size of the default mark |
+| `live` | `'polite' \| 'off'` | polite | SlLoadingOverlay | Whether the overlay announces the wait at all. off is for a page that already says it elsewhere |
+| `messages` | `Partial<LoadingOverlayMessages>` | — | SlLoadingOverlay | Words laid over the language in force, key by key: the short line (label), painted in the panel and announced once, and the cancel control’s words (cancel) |
+| `loadedLabel` | `string` | — | SlLoadingOverlay | What a screen reader hears when the wait ends. Silent unless set, so one wait says one thing |
+| `description` | `string` | — | SlLoadingOverlay | The second line, for what the first cannot hold. Painted, never announced |
+| `cancellable` | `boolean` | false | SlLoadingOverlay | Renders the control that asks to stop, and binds Escape to it |
+| `delay` | `number` | 0 | SlLoadingOverlay | Milliseconds the wait must last before anything is painted |
+| `minDuration` | `number` | 0 | SlLoadingOverlay | Milliseconds a layer that did appear is held before it is withdrawn |
+| `container` | `HTMLElement \| null` | — | SlLoadingOverlay | Where a page-scoped layer is portalled. Defaults to the document body; meaningless for a region |
+| `<ng-content>` | `—` | — | SlLoadingOverlay | Content is covered rather than replaced: it keeps its geometry, stays measured, and goes inert while the layer blocks |
+| `[slLoadingOverlayIndicator]` | `projection slot` | — | SlLoadingOverlay | Replaces the mark. A determinate wait projects progress-indicator’s own slProgressBar with a value |
+| `[slLoadingOverlayCancel]` | `directive` | — | SlLoadingOverlay | Your own control in the slot. It takes the part and the press; the family’s control paint is written :not([data-ui]) and steps back |
+| `the selector` | `[slLoadingOverlay]` | — | SlLoadingOverlay | A bare attribute, so the region is the element you already have — a section, a li, a form — and your attributes and listeners sit on it |
+| `exportAs` | `slLoadingOverlay` | — | SlLoadingOverlay | Reaches the instance from a template, including painted(), which is not the same signal as loading |
+| `provideLoadingOverlayDefaults()` | `LoadingOverlayDefaults` | — | Application | Sets veil, size, live, loadedLabel, delay and minDuration once for the whole injector; an input still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(cancel)` | `{ reason: "dismiss" \| "escape"; source: Event }` | The reader presses the control or the Escape key. The family commits nothing — it does not lower loading and does not hide itself — because the operation has not stopped until the application has stopped it. |
+| `(reveal)` | `void` | The covered content is reachable again, which is later than loading turning false whenever minDuration is still holding the layer. It is the moment an application moves focus on. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `scope` | `region`, `page` | `region` |
+| `veil` | `wash`, `blur`, `none` | `wash` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `live` | `polite`, `off` | `polite` |
+
+## Rules
+
+- The covered content carries inert while the layer blocks, which takes it out of the tab order and out of the accessibility tree. It is the capability the two surveyed implementations that document accessibility both decline: Quasar states that the content it covers stays focusable and asks the developer to solve it, and Mantine says the same in its usage section.
+- The region carries aria-busy="true" while it waits, which is the platform’s own answer: ARIA 1.2 asks an author to set it on the region until it is finished loading. Page scope writes it nowhere, because the busy region would be the document root and this family owns no part of it.
+- One overlay is one announcement. A visually-hidden role="status" holds the label while waiting and is emptied afterwards, and emptying a live region announces nothing, so a wait says one thing. The two painted lines carry aria-hidden, so the same sentence is not heard twice.
+- Focus is read before the content goes inert. If it was inside, it moves to the control or to the panel itself — the container destination the APG advises for content that must be read before it is operated — and returns to where it came from when the wait ends. Focus that was elsewhere is never moved: a background save does not take the caret out of another form.
+- There is no APG pattern for a loading overlay: the pattern index holds none for a busy region or a blocking layer, and claiming the Dialog pattern would import aria-modal and a close affordance into something that is neither. Page scope makes the rest of the document inert instead, which is what ARIA 1.2 asks of a modal element, and writes no aria-modal because that property inherits only into dialog and alertdialog.
+- Escape is bound only while a control exists for it to ask. A key that appears to do something and does nothing is worse than a key nobody bound, and an overlay with nothing to cancel has nothing for the key to ask for.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-loading-overlay-blur`, `--slotted-loading-overlay-inset`, `--slotted-loading-overlay-measure`, `--slotted-loading-overlay-radius`, `--slotted-loading-overlay-scrim`, `--slotted-loading-overlay-surface`, `--slotted-radius-md`, `--slotted-scrim`, `--slotted-shadow-lg`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-overlay`
+
+## Examples
+
+### The content is still there
+
+The covered card keeps its height, so nothing below it moves twice per save. Tab from the button above: focus walks past the covered fields, because they are inert rather than merely dimmed.
+
+Excerpt — not a complete module
+
+```html
+<div slLoadingOverlay [loading]="saving()" [messages]="{ label: 'Saving changes' }">
+  <div slCard>
+    <div slCardBody>…</div>
+  </div>
+</div>
+```
+
+### When the whole application waits
+
+scope="page" moves the layer into a portal root, makes every sibling of that root inert and locks the document scroll. Reach for it only when partial interaction would be unsafe — a month-end close, not a row that is saving.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slLoadingOverlay
+  scope="page"
+  [loading]="closing()"
+  [messages]="{ label: 'Closing the accounting period' }"
+  description="Do not close this tab."
+></div>
+```
+
+### Three ways to say out of reach
+
+wash is the theme’s own scrim; blur adds a backdrop filter, so text stops being legible before it stops being visible; none blocks exactly as much and dims nothing, for a wait short enough that a wash would read as a flash.
+
+Excerpt — not a complete module
+
+```html
+<div slLoadingOverlay veil="wash">…</div>
+<div slLoadingOverlay veil="blur">…</div>
+<div slLoadingOverlay veil="none">…</div>
+```
+
+### Three steps, and each moves three things
+
+The mark grows on the control-height scale, the two lines on the control type scale, and the panel on the space scale. Switch the toolbar to dense: the type and the mark shrink together and the meaning does not change.
+
+Excerpt — not a complete module
+
+```html
+<div slLoadingOverlay size="sm" [messages]="{ label: 'Reconciling' }">…</div>
+<div slLoadingOverlay size="md" [messages]="{ label: 'Reconciling' }">…</div>
+<div slLoadingOverlay size="lg" [messages]="{ label: 'Reconciling' }">…</div>
+```
+
+### The panel answers the region, not the viewport
+
+A tall region gets a column, a short one gets a bar carrying the same four things, and a small one gets the mark alone. Nothing is lost in the third: the words are in the live region, which is where they were doing the work.
+
+Excerpt — not a complete module
+
+```html
+<tr slLoadingOverlay [messages]="{ label: 'Updating the row' }" cancellable>
+  …
+</tr>
+```
+
+### Two flashes, and the two durations that prevent them
+
+delay is the wait before anything is painted, so data that arrives in eighty milliseconds draws nothing. minDuration holds a layer that did appear, so it is not taken away thirty milliseconds later. Both default to zero and cost no timer.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideLoadingOverlayDefaults({ delay: 200, minDuration: 400 })],
+});
+```
+
+### A wait that has gone wrong
+
+cancellable renders the control and binds Escape to it. The request carries the reason and commits nothing: abort the work and lower loading when it has actually stopped, which is what the second card is showing.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slLoadingOverlay
+  [loading]="importing()"
+  cancellable
+  [messages]="{ label: 'Importing 4 812 rows' }"
+  (cancel)="abort($event.reason)"
+>
+  …
+</div>
+```
+
+### Where the keyboard goes
+
+Put the caret in the field and press Salvar. Focus was inside the content that is about to go inert, so it moves to the panel; when the wait ends it returns to the field it came from. Focus that was elsewhere is never moved.
+
+Excerpt — not a complete module
+
+```html
+<form slLoadingOverlay [loading]="saving()" cancellable (reveal)="field.focus()">
+  <input #field />
+</form>
+```
+
+### A wait with a number on it
+
+The mark is a projection slot. The default is the contained loader; a determinate upload projects a slProgressBar with its own value, and the family that owns a measured quantity draws it.
+
+Excerpt — not a complete module
+
+```html
+<div slLoadingOverlay [messages]="{ label: 'Uploading contrato.pdf' }">
+  <div slLoadingOverlayIndicator slProgressBar [value]="62" label="Uploaded" hideLabel></div>
+  …
+</div>
+```
+
+### Words the family did not choose
+
+A translated sentence is longer than the English one that was measured. The panel wraps it, keeps its own measure, and never truncates: the announcement holds the same sentence whole for the reader who would otherwise lose it.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slLoadingOverlay
+  [messages]="{ label: 'A reconciliar os lançamentos do período com o extrato bancário' }"
+  description="Interromper agora deixaria metade do período conciliado."
+></div>
+```
+
+### The parts a consumer owns
+
+The selector is a bare attribute, so the region is the element the page already has. Project [slLoadingOverlayCancel] to bring your own control: the family’s control paint is written :not([data-ui]), so an slButton keeps its own.
+
+Excerpt — not a complete module
+
+```html
+<section slLoadingOverlay cancellable #overlay="slLoadingOverlay">
+  <button slLoadingOverlayCancel slButton variant="outline" size="sm">Interromper</button>
+  …
+</section>
+```
+
+### What a screen reader gets
+
+aria-busy on the region, one role="status" holding one sentence, and the covered subtree out of the accessibility tree entirely. Emptying the live region announces nothing, so a wait says one thing unless loadedLabel asks for a second.
+
+Excerpt — not a complete module
+
+```html
+<div slLoadingOverlay [messages]="{ label: 'Saving changes' }" loadedLabel="Changes saved">…</div>
+```