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

package/docs/progress-indicator.md

@@ -0,0 +1,329 @@
+<!-- index: ./index.md -->
+# progress-indicator
+
+`data-ui="progress-indicator"` · Progress bar or ring, known or indeterminate.
+
+## Import
+
+```ts
+import { SlProgressBar, SlProgressCircle, SlLoader, provideProgressIndicatorDefaults } from '@slotted/angular/progress-indicator';
+```
+
+Selector: `[slProgressBar] · [slProgressCircle] · [slLoader]` · exportAs: `slProgressBar · slProgressCircle · slLoader`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Uploading invoices" showValue [value]="uploaded()"></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element you put the attribute on | yes |
+| `label` | span | no |
+| `value` | span | no |
+| `track` | div, or an svg circle | yes |
+| `indicator` | div, or an svg circle or path | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `number \| null` | null (indeterminate) | slProgressBar, slProgressCircle | The quantity. Absent or null is a wait rather than nought per cent, and a value outside the range is clamped |
+| `min` | `number` | 0 | slProgressBar, slProgressCircle | The bottom of the range, and what aria-valuemin reports |
+| `max` | `number` | 100 | slProgressBar, slProgressCircle | The top of the range, and what aria-valuemax reports. Reaching it writes data-complete |
+| `buffer` | `number \| null` | — | slProgressBar | A second, further quantity: received but not yet processed. Never painted behind the value |
+| `size` | `sm \| md \| lg` | md | all three | The bar’s thickness, the ring’s diameter, the loader’s box. Rings and loaders read the control height scale, so they match a control of the same step |
+| `tone` | `accent \| secondary \| success \| warning \| danger` | accent | all three | The five the theme owns. The indicator is the tone’s text role and the track is a computed tint of it |
+| `label` | `string` | — | all three | The rendered accessible name. Without it, or an aria-label on your own element, or decorative, a development warning names the component |
+| `hideLabel` | `boolean` | false | all three | Clips the label with visually-hidden and keeps it as the name. A page-level bar sets it by itself |
+| `showValue` | `boolean` | false | slProgressBar, slProgressCircle | Whether the formatted number is rendered beside the name. A wait needs no number to be understood |
+| `valueText` | `string` | — | slProgressBar, slProgressCircle | A string the family cannot compute — “3 of 7 files”. It becomes both aria-valuetext and the rendered value |
+| `format` | `Intl.NumberFormatOptions` | — | slProgressBar, slProgressCircle | How the number is written, applied to the value. Absent, the ratio is written as a percentage |
+| `locale` | `string` | — | slProgressBar, slProgressCircle | BCP 47. Absent, the token’s, then the runtime’s own |
+| `wave` | `boolean` | false | slProgressBar, slProgressCircle | M3 Expressive’s wavy active indicator. The ring grows a fifth to make room for its crests |
+| `contained` | `boolean` | false | slLoader | M3’s fully rounded container behind the morphing shape, at M3’s own 38:48 ratio |
+| `placement` | `inline \| page \| edge-start \| edge-end` | inline | slProgressBar | page pins the bar to the top edge of the viewport, squares it, drops its track and reads the sticky stacking token; edge-start and edge-end stand it on the block-start or block-end edge of the nearest positioned box, over the line that edge draws. Every value but inline clips the label and grows the bar out of its edge |
+| `decorative` | `boolean` | false | all three | Takes the indicator out of the accessibility tree — no role, no range, no name — for a spinner beside text that already says what is happening |
+| `loading` | `boolean` | true | all three | Whether the wait is still on. false withdraws the indicator, honouring minDuration |
+| `delay` | `number` | 0 | all three | Milliseconds the wait must last before anything is painted. Until then the host carries hidden — no box, no role, no reserved band |
+| `minDuration` | `number` | 0 | all three | Milliseconds an indicator that did appear is held before it is withdrawn |
+| `the host element` | `any element` | — | all three | The selector is a bare attribute, so the element stays yours: a bar is the row that already holds it, and a ring is the menu item it sits in |
+| `exportAs` | `slProgressBar \| slProgressCircle \| slLoader` | — | all three | Reaches the instance from a template, for the painted signal and the resolved size and tone |
+| `provideProgressIndicatorDefaults` | `ProgressIndicatorDefaults` | — | Application | Sets size, tone, delay, minDuration, locale and label once through PROGRESS_INDICATOR_DEFAULTS_TOKEN; an input on an indicator still wins |
+| `ng-content` | `projected content` | — | slLoader | Content after the label, so a loader can stand inside a sentence you wrote rather than only beside a string it was given |
+| `aria-busy, aria-describedby` | `boolean, string` | — | Your own region | ARIA asks a consumer to write both on the region that is loading, pointing at the indicator’s id. The family cannot: the region is yours |
+| `slInlineMessage` | `a p beside the indicator` | — | Beside the indicator | The words that carry the wait. role="progressbar" prunes its own subtree, so a message inside an indicator is never heard — it belongs next to one |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `withdraw` | `void` | The indicator actually leaves the page — later than loading turning false whenever minDuration is still holding it. It is the moment an application unmounts the card the indicator was in. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `accent` |
+| `placement` | `inline`, `page`, `edge-start`, `edge-end` | `inline` |
+
+## Rules
+
+- The host carries role="progressbar" with aria-valuemin and aria-valuemax written out, and aria-valuenow only while there is a value. ARIA 1.3 asks an author to omit aria-valuenow when the value is indeterminate, and the omission is what says “in progress, and nobody knows how far”.
+- A value outside the range is clamped, and the clamped value is what both the paint and aria-valuenow report — so the picture a reader sees and the number a reader hears cannot disagree. Progress is usually computed from numbers an application does not fully control.
+- progressbar carries Children Presentational: True in ARIA 1.3, which means everything inside the host is pruned from the accessibility tree. The label reaches a reader through aria-labelledby and the number through aria-valuetext; anything else you project is silent. A live region inside an indicator is silent too, which is why the words that carry a wait belong to slInlineMessage beside it rather than to a hidden region within it.
+- An accessible name is required, and there are three ways to give one: label, an aria-label or aria-labelledby you wrote on your own element — read once through HostAttributeToken and never overwritten — or decorative for the case the feature guide names. With none of the three, development warns and the indicator still renders: a nameless bar reports visually, and taking a screen down mid-upload is worse than the defect.
+- If the indicator describes the loading of a region, ARIA asks you to set aria-busy on that region and point aria-describedby at the indicator. The family writes neither, because the region is yours; the accessibility demonstration shows both.
+- Under prefers-reduced-motion every loop stops rather than shortening — an animation that repeats forever needs to stop, and the indeterminate indicator rests at a length that reads as a fraction rather than as nought or as full. The cost is real: a still indicator says nothing on its own, so the name matters more, and the loader is best given a visible label.
+- The indicator is a tone’s text role, which the theme holds to the 4.5:1 reading ratio against every surface — more than the 3:1 WCAG 2.2 1.4.11 asks of a meaningful graphic — in all three colour schemes. Under forced colours the track keeps a ButtonBorder edge and the indicator takes Highlight, so the geometry survives a palette the family did not choose.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--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-duration-long`, `--slotted-duration-loop`, `--slotted-duration-loop-slow`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-emphasized`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-line-height-md`, `--slotted-progress-indicator-buffer-color`, `--slotted-progress-indicator-buffer-percent`, `--slotted-progress-indicator-gap`, `--slotted-progress-indicator-indicator-color`, `--slotted-progress-indicator-percent`, `--slotted-progress-indicator-position`, `--slotted-progress-indicator-radius`, `--slotted-progress-indicator-size`, `--slotted-progress-indicator-stroke`, `--slotted-progress-indicator-thickness`, `--slotted-progress-indicator-track-color`, `--slotted-progress-indicator-travel-size`, `--slotted-progress-indicator-travel-start`, `--slotted-progress-indicator-wave-amplitude`, `--slotted-progress-indicator-wave-phase`, `--slotted-radius-full`, `--slotted-radius-none`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-surface`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-z-index-sticky`
+
+## Examples
+
+### Three shapes, three jobs
+
+The bar reports a quantity along a row, the ring reports one in a cell too narrow for a bar, and the loader keeps a short wait company. Pick the directive; there is no shape input.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Uploading invoices" [value]="40"></div>
+<div slProgressCircle label="Rebuilding index" [value]="70"></div>
+<span slLoader label="Signing you in"></span>
+```
+
+### A quantity, and the range it is measured against
+
+value against min and max, the number written by Intl in the page language, and the finished bar closing its own gap. Compare the four per cent bar with the one at forty.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Copying files" showValue [value]="copied()"></div>
+
+<!-- A range of your own, written in the unit you passed in. -->
+<div
+  slProgressBar
+  label="Downloading"
+  showValue
+  [format]="{ style: 'unit', unit: 'megabyte', unitDisplay: 'narrow' }"
+  [max]="512"
+  [value]="128"
+></div>
+```
+
+### A wait with no number in it
+
+Leave value alone and the indicator reports a wait instead of a quantity: aria-valuenow is omitted, the whole track shows, and the arc has no remainder to draw.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Preparing your export"></div>
+<div slProgressCircle label="Checking availability"></div>
+
+<!-- Reporting nought per cent would be a claim nobody made. -->
+<div slProgressBar label="Preparing" [value]="null"></div>
+```
+
+### The wait a shape keeps
+
+M3 Expressive’s loading indicator: a shape morphs through a sequence while it turns, at two periods that never repeat a frame. Google recommends it over a spinning ring below five seconds.
+
+Excerpt — not a complete module
+
+```html
+<span slLoader label="Signing you in"></span>
+
+<!-- On a photograph or a coloured surface, where a bare shape has no ground. -->
+<span slLoader contained label="Signing you in" size="lg"></span>
+```
+
+### The wavy active indicator
+
+M3 Expressive’s wave, on the bar and on the ring. The crests run back toward the start, which reads as the fill flowing forward; the track stays flat, and the ring grows a fifth to make room for its own crests, as M3’s does from 40dp to 48dp.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Rendering the report" size="lg" wave [value]="62"></div>
+<div slProgressCircle label="Rendering the report" wave [value]="62"></div>
+```
+
+### The wave flattens at both ends
+
+The amplitude is a ramp on the value rather than a switch: flat to six per cent, full from sixteen to eighty-four, flat again from ninety-six. The fill’s own spring moves it, so the crests settle as the bar arrives.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Five per cent" size="lg" wave [value]="5"></div>
+<div slProgressBar label="Half way" size="lg" wave [value]="50"></div>
+<div slProgressBar label="Finished" size="lg" wave [value]="100"></div>
+```
+
+### The wave keeps its own pace
+
+The crests run back toward the start at one wavelength every 1.1 seconds whatever the value does, which is what reads on screen as the fill flowing forward. A load of a second and a half overtakes them and closes before they have crossed the track; a load of half a minute lets them pass its standing end many times.
+
+Excerpt — not a complete module
+
+```html
+<!-- Four points every sixty milliseconds, or one every three hundred: the wave is the same. -->
+<div slProgressBar label="Compressing" showValue size="lg" wave [value]="fast()"></div>
+<div slProgressBar label="Rebuilding the index" showValue size="lg" wave [value]="slow()"></div>
+```
+
+### The wave with no value
+
+Leave value alone and the travelling bar carries M3’s tighter indeterminate wave — one period every five thicknesses instead of ten — wavy along its whole length, because there is no value to flatten it against.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Preparing your export" size="lg" wave></div>
+```
+
+### The wave is measured in thicknesses
+
+One wavelength is ten thicknesses and a crest is three quarters of one at every size, so the small bar’s wave is twenty pixels long and the large bar’s eighty. Every ring carries eight crests, because the wave is wound on the viewBox and the viewBox scales.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Small" size="sm" wave [value]="55"></div>
+<div slProgressBar label="Large" size="lg" wave [value]="55"></div>
+<div slProgressCircle label="Saving" size="lg" wave [value]="55"></div>
+```
+
+### Received, and not yet processed
+
+Two quantities in one track: the indicator is what is done and the lighter band is what has arrived. Beside it, the same value with no buffer, so the gap is visible again.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slProgressBar
+  label="Processing uploaded pages"
+  showValue
+  size="lg"
+  [buffer]="72"
+  [value]="34"
+></div>
+```
+
+### Three steps, in the geometry each shape has
+
+size is the bar’s thickness, the ring’s diameter and the loader’s box. The rings read the control height scale, so one standing beside a button is exactly as tall as the button.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Small" size="sm" [value]="55"></div>
+<div slProgressCircle label="Beside a button" size="md" [value]="55"></div>
+<span slLoader label="Large" size="lg"></span>
+```
+
+### What the wait means, in colour
+
+The five the theme owns, each in the context it exists for: work in hand, a background job, an upload that landed, a quota nearly spent, a transfer that failed.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Uploading invoices" [value]="62"></div>
+<div slProgressBar label="Reindexing in the background" tone="secondary" [value]="62"></div>
+<div slProgressBar label="Storage used" tone="warning" [value]="88"></div>
+<div slProgressBar label="Transfer failed" tone="danger" [value]="41"></div>
+```
+
+### The flash, and the flash in reverse
+
+Two loads that finish every nine hundred milliseconds. On the left nothing is timed and the row churns; on the right the delay withholds the paint and minDuration holds it.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideProgressIndicatorDefaults({ delay: 200, minDuration: 400 })],
+});
+```
+
+### The bar on an edge: the viewport’s, or a box’s
+
+placement="page" pins the bar to the top edge of the viewport, squares its corners, drops its track and reads the sticky stacking token. edge-start and edge-end stand the same bar on the block-start or block-end edge of the nearest positioned box, over the line that edge draws; slAppShellProgress and slPageHeaderProgress are the boxes the library gives it. Each grows out of its edge and goes back into it.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Loading page" placement="page" [loading]="navigating()"></div>
+
+<!-- The same bar on an edge of the nearest positioned box. -->
+<div slProgressBar label="Refreshing" placement="edge-start"></div>
+<div slProgressBar label="Saving" placement="edge-end" [value]="62"></div>
+
+<!-- The name is clipped by the placement, because an edge bar has nowhere to show it. -->
+<div slProgressBar label="Loading page" placement="page" [hideLabel]="false"></div>
+```
+
+### Content the family did not choose
+
+A four-word label in a 360-pixel column, an unbreakable digest beside a number that must not break, and a right-to-left row where every edge changes ends but the clock does not.
+
+Excerpt — not a complete module
+
+```html
+<div slProgressBar label="Verificando assinaturas do pacote publicado" showValue [value]="47"></div>
+
+<div dir="rtl">
+  <div
+    slProgressCircle
+    label="جارٍ التحقق من التوقيعات"
+    locale="ar-EG"
+    showValue
+    [value]="47"
+  ></div>
+</div>
+```
+
+### A wait a product would ship
+
+An upload row: the file, the bar, the number, and a button to cancel. Beside it the provider that sets the timing, the tone and the language of every indicator below it.
+
+Excerpt — not a complete module
+
+```html
+<div slInline gap="5">
+  <span slText>report-q3.pdf</span>
+  <div slProgressBar hideLabel label="Uploading report-q3.pdf" showValue [value]="uploaded()"></div>
+  <button slButton tone="secondary" variant="outline" type="button">Cancel</button>
+</div>
+```
+
+### What a reader hears
+
+The two attributes ARIA asks a consumer to write on their own region, the sentence that carries the wait in words, and the indicator that leaves the tree because the words already say it.
+
+Excerpt — not a complete module
+
+```html
+<section [attr.aria-busy]="pending() ? 'true' : null" aria-describedby="import-progress">
+  <div slProgressBar id="import-progress" label="Importing contacts" showValue [value]="62"></div>
+</section>
+
+<!-- The words a reader hears are the words a reader sees. -->
+<div slInline gap="4">
+  <span slLoader decorative size="sm"></span>
+  <p slInlineMessage>Importing contacts — 62%</p>
+</div>
+```