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

package/docs/loading-overlay.json

@@ -0,0 +1,440 @@
+{
+  "family": "loading-overlay",
+  "ui": "loading-overlay",
+  "binding": "angular",
+  "catalog": {
+    "group": "Feedback",
+    "summary": "Veil and indicator over a loading region."
+  },
+  "axes": {
+    "scope": [
+      "region",
+      "page"
+    ],
+    "veil": [
+      "wash",
+      "blur",
+      "none"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "live": [
+      "polite",
+      "off"
+    ]
+  },
+  "members": {
+    "loadingOverlay": {
+      "nativeElement": "div",
+      "defaults": {
+        "scope": "region",
+        "veil": "wash",
+        "size": "md",
+        "live": "polite",
+        "loading": true,
+        "cancellable": false,
+        "delay": 0,
+        "minDuration": 0
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "placement",
+        "loading",
+        "live",
+        "content"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "loading",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "announcement",
+        "content",
+        "scrim",
+        "panel",
+        "indicator",
+        "label",
+        "description",
+        "cancel"
+      ]
+    }
+  },
+  "docs": {
+    "loadingOverlay": {
+      "imports": {
+        "source": "import { SlLoadingOverlay, SlLoadingOverlayCancel, provideLoadingOverlayDefaults } from '@slotted/angular/loading-overlay';",
+        "selector": "[slLoadingOverlay] · [slLoadingOverlayCancel]",
+        "exportAs": "slLoadingOverlay"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element you put slLoadingOverlay on",
+          "required": true,
+          "purpose": "The region. The selector is a bare attribute, so the element stays yours — a section, a card, a list item. Carries aria-busy while the layer blocks. Under scope=\"page\" it is the fixed layer itself, moved into a portal root."
+        },
+        {
+          "part": "announcement",
+          "element": "span",
+          "required": true,
+          "purpose": "The one visually-hidden role=\"status\" per overlay. A child of the root and never of the layer, so the sentence it holds is not deleted at the moment it has something to say."
+        },
+        {
+          "part": "content",
+          "element": "div",
+          "required": false,
+          "purpose": "The projected content, made inert while the layer blocks. display: contents, so a covered grid keeps its tracks. Absent under scope=\"page\", where what is covered is the application."
+        },
+        {
+          "part": "scrim",
+          "element": "div",
+          "required": true,
+          "purpose": "The wash, the one-cell grid that centres the panel, and the query container. In the document for the life of the family, so both directions of the fade are transitions."
+        },
+        {
+          "part": "panel",
+          "element": "div",
+          "required": false,
+          "purpose": "The box the reader reads. A column in a tall region, a bar in a short one, and the mark alone in a small one. Mounted while the layer is painted and held through its exit."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The mark. Holds progress-indicator's contained loader by default; project [slLoadingOverlayIndicator] to replace it, including with a determinate slProgressBar."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": false,
+          "purpose": "The short line. Painted and never announced from here: the announcement above holds the same sentence, and a wait should be heard once."
+        },
+        {
+          "part": "description",
+          "element": "span",
+          "required": false,
+          "purpose": "The second line, for what the first cannot hold. Rendered only when given."
+        },
+        {
+          "part": "cancel",
+          "element": "button",
+          "required": false,
+          "purpose": "Asks to stop. Rendered when cancellable is set, and the only thing in the layer that takes focus. Escape is bound only while it exists. Project [slLoadingOverlayCancel] to bring your own."
+        }
+      ],
+      "api": [
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "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()"
+        },
+        {
+          "name": "scope",
+          "type": "'region' | 'page'",
+          "defaultValue": "region",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "What is covered. region is the element the directive sits on; page is the whole viewport, portalled and modal"
+        },
+        {
+          "name": "veil",
+          "type": "'wash' | 'blur' | 'none'",
+          "defaultValue": "wash",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "How the covered content is obscured. none blocks exactly as much and dims nothing"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "The panel’s step: its padding, its type, and the size of the default mark"
+        },
+        {
+          "name": "live",
+          "type": "'polite' | 'off'",
+          "defaultValue": "polite",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Whether the overlay announces the wait at all. off is for a page that already says it elsewhere"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<LoadingOverlayMessages>",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "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)"
+        },
+        {
+          "name": "loadedLabel",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "What a screen reader hears when the wait ends. Silent unless set, so one wait says one thing"
+        },
+        {
+          "name": "description",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "The second line, for what the first cannot hold. Painted, never announced"
+        },
+        {
+          "name": "cancellable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Renders the control that asks to stop, and binds Escape to it"
+        },
+        {
+          "name": "delay",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Milliseconds the wait must last before anything is painted"
+        },
+        {
+          "name": "minDuration",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Milliseconds a layer that did appear is held before it is withdrawn"
+        },
+        {
+          "name": "container",
+          "type": "HTMLElement | null",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Where a page-scoped layer is portalled. Defaults to the document body; meaningless for a region"
+        }
+      ],
+      "composition": [
+        {
+          "name": "<ng-content>",
+          "type": "—",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Content is covered rather than replaced: it keeps its geometry, stays measured, and goes inert while the layer blocks"
+        },
+        {
+          "name": "[slLoadingOverlayIndicator]",
+          "type": "projection slot",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Replaces the mark. A determinate wait projects progress-indicator’s own slProgressBar with a value"
+        },
+        {
+          "name": "[slLoadingOverlayCancel]",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "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"
+        },
+        {
+          "name": "the selector",
+          "type": "[slLoadingOverlay]",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "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"
+        },
+        {
+          "name": "exportAs",
+          "type": "slLoadingOverlay",
+          "defaultValue": "—",
+          "appliesTo": "SlLoadingOverlay",
+          "description": "Reaches the instance from a template, including painted(), which is not the same signal as loading"
+        },
+        {
+          "name": "provideLoadingOverlayDefaults()",
+          "type": "LoadingOverlayDefaults",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets veil, size, live, loadedLabel, delay and minDuration once for the whole injector; an input still wins"
+        }
+      ],
+      "events": [
+        {
+          "name": "(cancel)",
+          "payload": "{ reason: \"dismiss\" | \"escape\"; source: Event }",
+          "when": "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."
+        },
+        {
+          "name": "(reveal)",
+          "payload": "void",
+          "when": "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."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A form covered mid-save, driven by the controls below the canvas. Turn loading off: the fields are exactly where they were, because they never left.",
+      "language": "html",
+      "source": "<section slLoadingOverlay [loading]=\"saving()\" [messages]=\"{ label: 'Saving changes' }\">\n  <app-billing-form />\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "region",
+      "title": "The content is still there",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slLoadingOverlay [loading]=\"saving()\" [messages]=\"{ label: 'Saving changes' }\">\n  <div slCard>\n    <div slCardBody>…</div>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "page",
+      "title": "When the whole application waits",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slLoadingOverlay\n  scope=\"page\"\n  [loading]=\"closing()\"\n  [messages]=\"{ label: 'Closing the accounting period' }\"\n  description=\"Do not close this tab.\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "veil",
+      "title": "Three ways to say out of reach",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slLoadingOverlay veil=\"wash\">…</div>\n<div slLoadingOverlay veil=\"blur\">…</div>\n<div slLoadingOverlay veil=\"none\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three steps, and each moves three things",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slLoadingOverlay size=\"sm\" [messages]=\"{ label: 'Reconciling' }\">…</div>\n<div slLoadingOverlay size=\"md\" [messages]=\"{ label: 'Reconciling' }\">…</div>\n<div slLoadingOverlay size=\"lg\" [messages]=\"{ label: 'Reconciling' }\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shapes",
+      "title": "The panel answers the region, not the viewport",
+      "note": "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.",
+      "language": "html",
+      "source": "<tr slLoadingOverlay [messages]=\"{ label: 'Updating the row' }\" cancellable>\n  …\n</tr>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "timing",
+      "title": "Two flashes, and the two durations that prevent them",
+      "note": "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.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideLoadingOverlayDefaults({ delay: 200, minDuration: 400 })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "cancel",
+      "title": "A wait that has gone wrong",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slLoadingOverlay\n  [loading]=\"importing()\"\n  cancellable\n  [messages]=\"{ label: 'Importing 4 812 rows' }\"\n  (cancel)=\"abort($event.reason)\"\n>\n  …\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "focus",
+      "title": "Where the keyboard goes",
+      "note": "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.",
+      "language": "html",
+      "source": "<form slLoadingOverlay [loading]=\"saving()\" cancellable (reveal)=\"field.focus()\">\n  <input #field />\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "indicator",
+      "title": "A wait with a number on it",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slLoadingOverlay [messages]=\"{ label: 'Uploading contrato.pdf' }\">\n  <div slLoadingOverlayIndicator slProgressBar [value]=\"62\" label=\"Uploaded\" hideLabel></div>\n  …\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Words the family did not choose",
+      "note": "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.",
+      "language": "html",
+      "source": "<div\n  slLoadingOverlay\n  [messages]=\"{ label: 'A reconciliar os lançamentos do período com o extrato bancário' }\"\n  description=\"Interromper agora deixaria metade do período conciliado.\"\n></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "The parts a consumer owns",
+      "note": "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.",
+      "language": "html",
+      "source": "<section slLoadingOverlay cancellable #overlay=\"slLoadingOverlay\">\n  <button slLoadingOverlayCancel slButton variant=\"outline\" size=\"sm\">Interromper</button>\n  …\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a screen reader gets",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slLoadingOverlay [messages]=\"{ label: 'Saving changes' }\" loadedLabel=\"Changes saved\">…</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}