@maggioli-design-system/magma-react 2.9.0 → 2.11.0

package/agents/patterns/loading.md

@@ -0,0 +1,221 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: loading
+kind: pattern
+title: Waiting for something
+group: messages-and-states
+layer: magma
+status: decided
+need: >-
+  The person waits for content or for the end of an action, and must know that it is coming and
+  whether they can do something else meanwhile.
+principle: The wait shows where the person looked, keeps what is on screen, and always ends.
+keywords: [loading, spinner, progress, please wait, busy, in progress, uploading, exporting, skeleton]
+not-for:
+  - need: where the outcome of the action is told
+    use: message-placement
+  - need: a load that ended with nothing to show
+    use: empty-state
+  - need: a load that failed
+    use: error-recovery
+assumptions:
+  - The application knows before starting whether an operation is long and whether it can tell how far it is.
+high-stakes: false
+components: [mds-spinner, mds-progress, mds-button, mds-input, mds-text, mds-toast]
+related: [message-placement, empty-state, error-recovery, list-with-filters, record-detail, item-list]
+validated-on: []
+
+variables:
+  what: { values: [content, action], means: "content: data a part of the page shows; action: an operation the person started from a control" }
+  on-screen: { values: [nothing, previous], means: "for content: is there something to keep while it loads (a reload, a new search)" }
+  length: { values: [short, long], means: "long: an operation that can take more than 10 s, known before it starts (an export, an upload, many items, a report)" }
+  measurable: { values: ["no", "yes"], means: "can the application tell how far it is (bytes sent, items done)" }
+  needed: { values: ["yes", "no"], means: "does the person need the result before going on" }
+
+cases:
+  - { id: first-load, what: content, on-screen: nothing, length: short, where: "a skeleton with the shape of the content, in its place; until Magma has one, a well as tall as the content to come (`surface-muted`, `rounded-md`) with a spinner in the middle; aria-busy on the part", use: ["mds-spinner"], magma-gap: "no skeleton" }
+  - { id: keep-while-reloading, what: content, on-screen: previous, length: short, where: "what was there stays; the region has aria-busy; the control that started it waits; a newer request cancels the older; in the new results, what was searched is marked (`mark`)", use: ["mds-input await"] }
+  - { id: long-load, what: content, length: long, measurable: "no", where: "the well and the spinner of the short case, with a sentence under the spinner that says what is happening", use: ["mds-spinner", "mds-text"] }
+  - { id: long-load-measured, what: content, length: long, measurable: "yes", where: "the well and the spinner of the short case, a sentence that says what is happening and how far, and a progress bar under it", use: ["mds-spinner", "mds-text", "mds-progress steps"] }
+  - { id: await-the-control, what: action, length: short, where: "the control that started it waits: its spinner, no second press, aria-busy, the focus stays on it", use: ["mds-button await"] }
+  - { id: progress-in-place, what: action, length: long, measurable: "yes", needed: "yes", where: "a progress bar next to the control, with a sentence that says what is happening", use: ["mds-progress steps", "mds-button await"] }
+  - { id: await-and-say, what: action, length: long, measurable: "no", needed: "yes", where: "the control waits, and a sentence next to it says what is happening", use: ["mds-button await", "mds-text"] }
+  - { id: run-in-background, what: action, length: long, needed: "no", where: "the control stops waiting at once and a toast says it started; the outcome comes later, as action-later", use: ["mds-toast variant=info"], see: message-placement }
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: no-flash-empty
+    rule: A reload never empties what is on screen.
+    checked-by: review
+  - id: control-waits
+    rule: The control that started an action shows the wait and cannot be pressed again.
+    checked-by: review
+    note: a double payment is what it prevents
+  - id: busy-region
+    rule: "The region being updated has aria-busy: mds-spinner has no role and leaves it to the context."
+    checked-by: review
+  - id: newest-wins
+    rule: An older answer never replaces a newer one.
+    checked-by: review
+  - id: always-ends
+    rule: A wait ends in content, an empty state or an error.
+    checked-by: review
+  - id: long-says-what
+    rule: A long wait says what is happening, not only an icon that turns.
+    checked-by: review
+  - id: cancel-only-if-it-stops
+    rule: Cancel is offered only when it stops the operation; it never only hides the wait.
+    checked-by: review
+
+situations:
+  - { situation: A list opens for the first time, case: first-load }
+  - { situation: A search narrows a list already on screen, case: keep-while-reloading }
+  - { situation: "A report takes a minute to compute, with no measure of how far it is", case: long-load }
+  - { situation: A dashboard loads twelve widgets and counts them, case: long-load-measured }
+  - { situation: A form is saved, case: await-the-control }
+  - { situation: A file is uploaded and the form needs it, case: progress-in-place, note: with Cancel }
+  - { situation: A payment is sent and its answer is slow, case: await-and-say, note: without Cancel }
+  - { situation: An export of ten thousand rows is asked for, case: run-in-background }
+---
+
+# Waiting for something
+
+**The wait shows where the person looked, keeps what is on screen, and always ends.**
+
+## When to use it
+
+Every wait the person sees: the first load of a part of the page, a reload of what is on
+screen (a new search, a new page of results), an action started from a control (save, send,
+delete), a long operation (an upload, an export, a report). Not the outcome of the wait: it is
+told by `message-placement`, and it may be an empty state (`empty-state`) or an error
+(`error-recovery`).
+
+## What decides it
+
+Five questions: whether the person waits for content or for an action, whether something is
+already on screen to keep, whether the wait is short or long, whether the application can tell
+how far it is, and whether the person needs the result before going on.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `what` | `content`, `action` | content: data a part of the page shows; action: an operation the person started from a control |
+| `on-screen` | `nothing`, `previous` | for content: is there something to keep while it loads (a reload, a new search) |
+| `length` | `short`, `long` | long: an operation that can take more than 10 s, known before it starts (an export, an upload, many items, a report) |
+| `measurable` | `no`, `yes` | can the application tell how far it is (bytes sent, items done) |
+| `needed` | `yes`, `no` | does the person need the result before going on |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `first-load` | what: content; on-screen: nothing; length: short | a skeleton with the shape of the content, in its place; until Magma has one, a well as tall as the content to come (`surface-muted`, `rounded-md`) with a spinner in the middle; aria-busy on the part; Magma gap: no skeleton | `mds-spinner` |
+| `keep-while-reloading` | what: content; on-screen: previous; length: short | what was there stays; the region has aria-busy; the control that started it waits; a newer request cancels the older; in the new results, what was searched is marked (`mark`) | `mds-input await` |
+| `long-load` | what: content; length: long; measurable: no | the well and the spinner of the short case, with a sentence under the spinner that says what is happening | `mds-spinner`, `mds-text` |
+| `long-load-measured` | what: content; length: long; measurable: yes | the well and the spinner of the short case, a sentence that says what is happening and how far, and a progress bar under it | `mds-spinner`, `mds-text`, `mds-progress steps` |
+| `await-the-control` | what: action; length: short | the control that started it waits: its spinner, no second press, aria-busy, the focus stays on it | `mds-button await` |
+| `progress-in-place` | what: action; length: long; measurable: yes; needed: yes | a progress bar next to the control, with a sentence that says what is happening | `mds-progress steps`, `mds-button await` |
+| `await-and-say` | what: action; length: long; measurable: no; needed: yes | the control waits, and a sentence next to it says what is happening | `mds-button await`, `mds-text` |
+| `run-in-background` | what: action; length: long; needed: no | the control stops waiting at once and a toast says it started; the outcome comes later, as action-later; see `message-placement` | `mds-toast variant=info` |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+- The first load of a part: a skeleton with the shape of the content (rows of a list, the
+  blocks of a detail), so the layout does not jump when the data comes; until Magma has one, a
+  well that keeps the place of the content (`bg-surface-muted rounded-md`, as tall as what
+  comes), with `mds-spinner` in its middle: the spinner never floats alone on the page.
+- A reload: the content stays, the region has `aria-busy="true"`, the control that started it
+  waits (`await` on `mds-input` shows the spinner in the search field). In the results of a
+  search, what was searched is marked (`mark`, painted with `bg-warning-surface`).
+- An action: `await` on `mds-button`, which shows its spinner, refuses a second press, sets
+  `aria-busy` and keeps the focus.
+- A long wait: a sentence that says what is happening ("Preparing the PDF..."), under the
+  spinner, in the well; `mds-progress` under the sentence when the application can tell how far
+  it is, with `steps` in the language of the page: the spinner stays, so the wait looks alive
+  between two steps of the bar.
+- A long action the person does not need to wait for: a toast that says it started, then the
+  outcome as `action-later` of `message-placement`.
+
+## Behaviour over time
+
+- A newer request cancels the one still running: an older, slower answer never replaces a
+  newer one (`list-with-filters`).
+- The wait ends in content, in an empty state or in an error, never in an indicator that runs
+  for ever.
+- A long wait the person needs has Cancel next to it when the operation can be stopped without
+  harm: it stops, and the message says what was done and what was not (`message-placement`,
+  partial outcome). An operation that cannot be called back, a payment already sent, offers
+  none.
+
+## Always true
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+These hold in every product: a product layer cannot change them.
+
+| Id | Rule | Checked by |
+| --- | --- | --- |
+| `no-flash-empty` | A reload never empties what is on screen. | review |
+| `control-waits` | The control that started an action shows the wait and cannot be pressed again. | review; a double payment is what it prevents |
+| `busy-region` | The region being updated has aria-busy: mds-spinner has no role and leaves it to the context. | review |
+| `newest-wins` | An older answer never replaces a newer one. | review |
+| `always-ends` | A wait ends in content, an empty state or an error. | review |
+| `long-says-what` | A long wait says what is happening, not only an icon that turns. | review |
+| `cancel-only-if-it-stops` | Cancel is offered only when it stops the operation; it never only hides the wait. | review |
+
+## Situations
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+Situations every application has, each with its case: they give the examples, the texts and the keywords. The situations of a product's own domain go in its layer.
+
+| Situation | Case |
+| --- | --- |
+| A list opens for the first time | `first-load` |
+| A search narrows a list already on screen | `keep-while-reloading` |
+| A report takes a minute to compute, with no measure of how far it is | `long-load` |
+| A dashboard loads twelve widgets and counts them | `long-load-measured` |
+| A form is saved | `await-the-control` |
+| A file is uploaded and the form needs it | `progress-in-place`: with Cancel |
+| A payment is sent and its answer is slow | `await-and-say`: without Cancel |
+| An export of ten thousand rows is asked for | `run-in-background` |
+
+## Accessibility
+
+- `aria-busy` on the region tells assistive technologies that it is being updated; the result
+  is read out by the status region of `message-placement`, or the summary of the results.
+- The spinner is decorative; with reduced motion it slows down and never stops (`mds-spinner`).
+- `mds-progress` reads out the step reached, not a raw number.
+
+## Content
+
+- A long wait says what is happening, in the words of the person: "Preparing the PDF...", not
+  "Processing request".
+
+## Magma gaps
+
+- No skeleton, neither a component nor a utility, and no component for the states of a load
+  (the well, the spinner, the sentence, the bar): an issue to open; until then, the well
+  written with classes.
+- `mark` has no Magma style: the browser paints it in its own yellow, so the previews paint it
+  with `bg-warning-surface text-inherit`.
+- `mds-progress`: the default `steps` are in Italian (`Inizio,Un quarto,...`) whatever the
+  language of the page.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-16 | Proposed: a skeleton for the first load of a region, `await` on the control that started an action, the results stay while the next ones load | Open decision of the docs site, `agents/patterns.md`. |
+| 2026-10-28 | Draft with variables; the first load, when a wait is long, and Cancel left as gaps | The sources do not settle them. |
+| 2026-10-28 | The first load shows a skeleton with the shape of the content; a spinner until Magma has one (`first-load`) | The layout does not jump when the data comes; the open decision of the docs site. |
+| 2026-10-28 | A wait is long when the operation can take more than 10 s, known before it starts | The application picks the form of the wait before starting; 10 s is the limit of attention (Nielsen). |
+| 2026-10-28 | Cancel next to a long wait the person needs, only when the operation can be stopped | A Cancel that only hides the wait lies about what happens. |
+| 2026-11-03 | Until Magma has a skeleton, the first load is a well that keeps the place of the content, with the spinner in its middle; a long load keeps the well and the spinner, and adds the sentence and the bar (`first-load`, `long-load`, `long-load-measured`) | A spinner alone floats on the page and says nothing of what is coming, or where. Asked in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |
+| 2026-11-03 | In the results of a search, what was searched is marked (`keep-while-reloading`) | The person sees at once why each result is there. Asked in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |

package/agents/patterns/message-placement.md

@@ -0,0 +1,304 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: message-placement
+kind: pattern
+title: Where a message goes
+group: messages-and-states
+layer: magma
+status: decided
+need: >-
+  The person did something or opened a view, and must know what happened without looking for
+  it.
+principle: A message goes where the thing it talks about is.
+keywords: [message, toast, banner, error message, saved, deleted, copied, failed, could not load, try again, connection lost, session ending]
+not-for:
+  - need: deciding whether to ask before acting
+    use: confirm-action
+  - need: what an empty part of the page says
+    use: empty-state
+  - need: what stays on screen and how to try again after a failure
+    use: error-recovery
+assumptions:
+  - The application has a shell, with one mds-toast-region in it.
+  - Desktop and mobile; on mobile with the keyboard open the bottom edge is still to verify.
+high-stakes: false
+components: [mds-input-field, mds-input, mds-banner, mds-toast, mds-toast-region, mds-modal]
+related: [confirm-action, error-recovery, loading, empty-state, notification-center, app-shell]
+validated-on: []
+
+variables:
+  about: { values: [field, region, action, application], means: "what the message talks about" }
+  outcome: { values: [success, failure, partial, info], means: "what happened" }
+  place: { values: [on-screen, off-screen], means: "is the thing it talks about on screen when the message comes" }
+  timing: { values: [now, later], means: "later: the outcome comes after the person moved on" }
+  decision: { values: [none, needed, deadline], means: "does the person have to choose before going on" }
+  scope: { values: [page, part], means: "what an action changed: data shown across the page, or a part that works on its own" }
+
+cases:
+  - { id: field-error, about: field, outcome: failure, place: on-screen, where: "under the field", use: ["mds-input-field message"] }
+  - { id: field-hint, about: field, outcome: info, place: on-screen, where: "under the field, its helper text; where an example of the value helps, the empty field shows one as its placeholder (\"Es: Mario Rossi\")", use: ["mds-input-field message", "mds-input placeholder"], magma-gap: "validation overwrites it" }
+  - { id: field-valid, about: field, outcome: success, place: on-screen, where: "no message, the field shows its valid state", use: ["mds-input-field"] }
+  - { id: region-failed, about: region, outcome: failure, where: "in that region, with Try again; what was there stays", use: ["mds-banner variant=error tone=strong"] }
+  - { id: region-info, about: region, outcome: info, where: "in that region", use: ["mds-banner variant=info"] }
+  - { id: action-failed-in-place, about: action, outcome: failure, place: on-screen, timing: now, where: "in its place, right above the row of actions of the dialog; what was written stays", use: ["mds-banner variant=error tone=strong"] }
+  - { id: action-done-elsewhere, about: action, outcome: success, place: off-screen, timing: now, where: "toast; the default light toast for a removal (`removal-toast-neutral`)", use: ["mds-toast variant=success"] }
+  - { id: action-done-in-page, about: action, outcome: success, place: on-screen, timing: now, scope: page, where: "toast; the default light toast for a removal (`removal-toast-neutral`)", use: ["mds-toast variant=success"] }
+  - { id: action-done-in-part, about: action, outcome: success, place: on-screen, timing: now, scope: part, where: "next to the part that was saved, inside it", use: ["mds-banner variant=success"], magma-gap: "no light confirmation that goes away" }
+  - { id: action-failed-elsewhere, about: action, outcome: failure, place: off-screen, timing: now, where: "a toast that stays, with Try again", use: ["mds-toast variant=error duration=0 dismissible"] }
+  - { id: action-partial-in-place, about: action, outcome: partial, place: on-screen, timing: now, where: "as a failure in its place: a banner that says how many worked and which did not", use: ["mds-banner variant=error tone=strong"], see: error-recovery }
+  - { id: action-partial-elsewhere, about: action, outcome: partial, place: off-screen, timing: now, where: "as a failure elsewhere: a toast that stays, with what to do about the ones that did not work", use: ["mds-toast variant=error duration=0 dismissible"], see: error-recovery }
+  - { id: action-taken, about: action, outcome: info, timing: now, where: "toast: taken in charge, and how the outcome will come", use: ["mds-toast variant=info"] }
+  - { id: action-later, about: action, timing: later, where: "a toast with its action, which therefore stays; then kept in the notification center", use: ["mds-toast duration=0 dismissible"], see: notification-center }
+  - { id: decision, decision: needed, where: "dialog", use: ["mds-modal"], see: confirm-action }
+  - { id: app-info, about: application, outcome: info, decision: none, where: "a toast that goes after its time: `warning` for a trouble that does not stop the work (the connection dropped), `info` for news", use: ["mds-toast variant=warning", "mds-toast variant=info"] }
+  - { id: app-failed, about: application, outcome: failure, where: "in place of the content of the page, with Try again; the shell stays", use: ["mds-banner variant=error tone=strong"], see: region-failed }
+  - { id: app-deadline, about: application, decision: deadline, where: "dialog, also over an open one; closing it means staying (`deadline-close` of actions)", use: ["mds-modal", "mds-banner slot=window variant=warning tone=box dismissible"] }
+gaps: []
+not-applicable:
+  - { about: field, place: off-screen, why: "a message about a field goes with its field" }
+  - { about: region, outcome: success, why: "a region that loads shows its content, the content is the message" }
+  - { about: [field, region, action], decision: deadline, why: "a deadline is about the whole application" }
+  - { about: [field, region, application], outcome: partial, why: "a partial outcome is about an action on several items" }
+  - { about: application, outcome: success, why: "an application does not succeed, its actions do" }
+
+always-true:
+  - id: no-toast-over-dialog
+    rule: "Never a toast over an open dialog: what is about a dialog goes inside it."
+    checked-by: review
+  - id: one-toast-region
+    rule: One mds-toast-region per application.
+    checked-by: review
+  - id: toast-action-stays
+    rule: A toast with an action has duration="0" and dismissible.
+    checked-by: review
+    lint-planned: magma/toast-action-stays
+  - id: no-dismissible-banner-in-dialog
+    rule: "A banner inside an mds-modal is not dismissible: closing it closes the dialog, and what the person wrote is lost."
+    checked-by: review
+    lint-planned: magma/no-dismissible-banner-in-modal
+  - id: success-after-change
+    rule: "After every create, edit and delete the person is told it worked: a toast, or a confirmation next to the part when that part works on its own."
+    checked-by: review
+  - id: removal-toast-neutral
+    rule: "The toast of a removal (an item removed, archived, deleted after a confirmation), with or without Undo, is the default light toast: variant=\"success\" is for what an action creates or completes."
+    checked-by: review
+  - id: no-internal-text
+    rule: Never internal messages, HTTP status text or "coming soon".
+    checked-by: review
+
+open-choices:
+  - { id: success-toast-duration, default: 5000 ms, may: "choose up to 8000 ms" }
+  - { id: message-wording, default: the texts under Content, may: "write its own, in its voice" }
+
+situations:
+  - { situation: A form is sent with a required field empty, case: field-error }
+  - { situation: A field explains its format before it is filled, case: field-hint }
+  - { situation: The field is filled in correctly, case: field-valid }
+  - { situation: A list does not load, case: region-failed }
+  - { situation: A list shows data that are updated once a night, case: region-info }
+  - { situation: Saving a form in a dialog fails, case: action-failed-in-place }
+  - { situation: "Saving a form in a dialog works, and the dialog closes", case: action-done-elsewhere }
+  - { situation: An item is deleted from a list, case: action-done-elsewhere, note: "the default light toast (`removal-toast-neutral`)" }
+  - { situation: A link is copied, case: action-done-elsewhere }
+  - { situation: "Saving the details of a record, shown in its header and its tabs too, works", case: action-done-in-page }
+  - { situation: "Saving a card of settings that has its own Save, on a page that stays open, works", case: action-done-in-part }
+  - { situation: "Sending something from the menu of a row fails, after the menu closed", case: action-failed-elsewhere }
+  - { situation: An item is about to be deleted for good, case: decision }
+  - { situation: "The connection drops, then comes back", case: app-info }
+  - { situation: The server answers nothing at all, case: app-failed }
+  - { situation: "The session is about to end, with work not saved", case: app-deadline }
+  - { situation: "An export is ready minutes later, while the person works elsewhere", case: action-later }
+  - { situation: "A request is taken in charge; the answer comes by email", case: [action-taken, action-later], note: "the first at once, the second when the answer comes" }
+  - { situation: "An action on 20 items of a list on screen: 3 fail", case: action-partial-in-place }
+  - { situation: "An action on 20 items from a menu that closed: 3 fail", case: action-partial-elsewhere }
+---
+
+# Where a message goes
+
+**A message goes where the thing it talks about is.**
+
+## When to use it
+
+Every message the application gives the person: the outcome of an action, a part of the page
+that failed, the state of the whole application. Never internal messages, the raw text of an
+HTTP status, or "coming soon".
+
+## What decides it
+
+Six questions about the message: what it talks about (a field, a region of the page, an
+action, the whole application), its outcome (success, failure, partial, information), whether
+the thing it talks about is on screen when the message comes, whether the message comes now
+or later, after the person moved on, whether the person has to choose before going on, and,
+for an action, what it changed: data shown across the page, or a part that works on its own.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `about` | `field`, `region`, `action`, `application` | what the message talks about |
+| `outcome` | `success`, `failure`, `partial`, `info` | what happened |
+| `place` | `on-screen`, `off-screen` | is the thing it talks about on screen when the message comes |
+| `timing` | `now`, `later` | later: the outcome comes after the person moved on |
+| `decision` | `none`, `needed`, `deadline` | does the person have to choose before going on |
+| `scope` | `page`, `part` | what an action changed: data shown across the page, or a part that works on its own |
+
+A case that leaves a variable out holds for any of its values, except `decision`, which then means `none`.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `field-error` | about: field; outcome: failure; place: on-screen | under the field | `mds-input-field message` |
+| `field-hint` | about: field; outcome: info; place: on-screen | under the field, its helper text; where an example of the value helps, the empty field shows one as its placeholder ("Es: Mario Rossi"); Magma gap: validation overwrites it | `mds-input-field message`, `mds-input placeholder` |
+| `field-valid` | about: field; outcome: success; place: on-screen | no message, the field shows its valid state | `mds-input-field` |
+| `region-failed` | about: region; outcome: failure | in that region, with Try again; what was there stays | `mds-banner variant=error tone=strong` |
+| `region-info` | about: region; outcome: info | in that region | `mds-banner variant=info` |
+| `action-failed-in-place` | about: action; outcome: failure; place: on-screen; timing: now | in its place, right above the row of actions of the dialog; what was written stays | `mds-banner variant=error tone=strong` |
+| `action-done-elsewhere` | about: action; outcome: success; place: off-screen; timing: now | toast; the default light toast for a removal (`removal-toast-neutral`) | `mds-toast variant=success` |
+| `action-done-in-page` | about: action; outcome: success; place: on-screen; timing: now; scope: page | toast; the default light toast for a removal (`removal-toast-neutral`) | `mds-toast variant=success` |
+| `action-done-in-part` | about: action; outcome: success; place: on-screen; timing: now; scope: part | next to the part that was saved, inside it; Magma gap: no light confirmation that goes away | `mds-banner variant=success` |
+| `action-failed-elsewhere` | about: action; outcome: failure; place: off-screen; timing: now | a toast that stays, with Try again | `mds-toast variant=error duration=0 dismissible` |
+| `action-partial-in-place` | about: action; outcome: partial; place: on-screen; timing: now | as a failure in its place: a banner that says how many worked and which did not; see `error-recovery` | `mds-banner variant=error tone=strong` |
+| `action-partial-elsewhere` | about: action; outcome: partial; place: off-screen; timing: now | as a failure elsewhere: a toast that stays, with what to do about the ones that did not work; see `error-recovery` | `mds-toast variant=error duration=0 dismissible` |
+| `action-taken` | about: action; outcome: info; timing: now | toast: taken in charge, and how the outcome will come | `mds-toast variant=info` |
+| `action-later` | about: action; timing: later | a toast with its action, which therefore stays; then kept in the notification center; see `notification-center` | `mds-toast duration=0 dismissible` |
+| `decision` | decision: needed | dialog; see `confirm-action` | `mds-modal` |
+| `app-info` | about: application; outcome: info; decision: none | a toast that goes after its time: `warning` for a trouble that does not stop the work (the connection dropped), `info` for news | `mds-toast variant=warning`, `mds-toast variant=info` |
+| `app-failed` | about: application; outcome: failure | in place of the content of the page, with Try again; the shell stays; see `region-failed` | `mds-banner variant=error tone=strong` |
+| `app-deadline` | about: application; decision: deadline | dialog, also over an open one; closing it means staying (`deadline-close` of actions) | `mds-modal`, `mds-banner slot=window variant=warning tone=box dismissible` |
+
+Not applicable:
+
+| When | Why |
+| --- | --- |
+| about: field; place: off-screen | a message about a field goes with its field |
+| about: region; outcome: success | a region that loads shows its content, the content is the message |
+| about: field or region or action; decision: deadline | a deadline is about the whole application |
+| about: field or region or application; outcome: partial | a partial outcome is about an action on several items |
+| about: application; outcome: success | an application does not succeed, its actions do |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+The toasts live in one `mds-toast-region` per application, at `bottom-center`, three at most.
+
+## Behaviour over time
+
+- A toast never takes the focus: the region reads it out.
+- Its timer stops while the pointer or the focus is on it.
+- A toast with an action has no timer and can be sent away (`dismissible`).
+- When a toast leaves with the focus inside it, the focus goes to the title of the page.
+- When the element that opened a dialog is gone (the item just deleted), the focus goes to
+  the title of the page when the dialog closes: an `h1` with `tabindex="-1"`.
+
+## Always true
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+These hold in every product: a product layer cannot change them.
+
+| Id | Rule | Checked by |
+| --- | --- | --- |
+| `no-toast-over-dialog` | Never a toast over an open dialog: what is about a dialog goes inside it. | review |
+| `one-toast-region` | One mds-toast-region per application. | review |
+| `toast-action-stays` | A toast with an action has duration="0" and dismissible. | review; lint `magma/toast-action-stays` to write |
+| `no-dismissible-banner-in-dialog` | A banner inside an mds-modal is not dismissible: closing it closes the dialog, and what the person wrote is lost. | review; lint `magma/no-dismissible-banner-in-modal` to write |
+| `success-after-change` | After every create, edit and delete the person is told it worked: a toast, or a confirmation next to the part when that part works on its own. | review |
+| `removal-toast-neutral` | The toast of a removal (an item removed, archived, deleted after a confirmation), with or without Undo, is the default light toast: variant="success" is for what an action creates or completes. | review |
+| `no-internal-text` | Never internal messages, HTTP status text or "coming soon". | review |
+
+## Open choices
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+The default decides these; a product layer may narrow them.
+
+| Id | Default | A product may |
+| --- | --- | --- |
+| `success-toast-duration` | 5000 ms | choose up to 8000 ms |
+| `message-wording` | the texts under Content | write its own, in its voice |
+
+## Situations
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+Situations every application has, each with its case: they give the examples, the texts and the keywords. The situations of a product's own domain go in its layer.
+
+| Situation | Case |
+| --- | --- |
+| A form is sent with a required field empty | `field-error` |
+| A field explains its format before it is filled | `field-hint` |
+| The field is filled in correctly | `field-valid` |
+| A list does not load | `region-failed` |
+| A list shows data that are updated once a night | `region-info` |
+| Saving a form in a dialog fails | `action-failed-in-place` |
+| Saving a form in a dialog works, and the dialog closes | `action-done-elsewhere` |
+| An item is deleted from a list | `action-done-elsewhere`: the default light toast (`removal-toast-neutral`) |
+| A link is copied | `action-done-elsewhere` |
+| Saving the details of a record, shown in its header and its tabs too, works | `action-done-in-page` |
+| Saving a card of settings that has its own Save, on a page that stays open, works | `action-done-in-part` |
+| Sending something from the menu of a row fails, after the menu closed | `action-failed-elsewhere` |
+| An item is about to be deleted for good | `decision` |
+| The connection drops, then comes back | `app-info` |
+| The server answers nothing at all | `app-failed` |
+| The session is about to end, with work not saved | `app-deadline` |
+| An export is ready minutes later, while the person works elsewhere | `action-later` |
+| A request is taken in charge; the answer comes by email | `action-taken`, `action-later`: the first at once, the second when the answer comes |
+| An action on 20 items of a list on screen: 3 fail | `action-partial-in-place` |
+| An action on 20 items from a menu that closed: 3 fail | `action-partial-elsewhere` |
+
+## Accessibility
+
+- The region is a status region, in the page before any message: a toast is read out without
+  moving the focus. The button of a toast is reachable with the keyboard.
+- An error banner is read out at once (`role="alert"`).
+- An urgent message that is not a toast goes through a hidden `role="alert"` region.
+
+## Content
+
+- An outcome names the object: "Mario Rossi deleted."
+- An error says what did not happen and what to do: "Nothing was changed. Try again in a
+  moment."
+- The placeholder of a field is an example of the value, "Es: Mario Rossi", never its label
+  or its hint: it goes at the first letter typed.
+
+## Magma gaps
+
+- The hidden region for urgent messages is written by hand: an announcer next to
+  `mds-toast-region`? (to decide)
+- `mds-toast` shows its text only when it has one at load, a gap left by #688 (to verify).
+- The helper text of a field goes in the `message` of `mds-input-field`, which the validation
+  overwrites: the help is gone at the first check. A hint of its own, kept next to the errors?
+  (an issue to open)
+- A light confirmation next to a part ("Saved" by its button), read out and then gone: Magma
+  has none, only `mds-banner`, which stays. (to decide whether it is needed)
+- The notification center: `mds-push-notification` is a stack of messages with its own
+  "Clear notifications"; whether it can be a list to come back to is for the pattern
+  `notification-center` to verify.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-16 | The rule and the table of cases | A message read far from what it is about is missed or misread. |
+| 2026-10-16 | To confirm: the session ending is a strict dialog, also over an open one; agreed first as a toast | A toast over an open dialog can be seen but not used. |
+| 2026-10-27 | Id `message-placement`, group Messages and states (was Feedback) | "Feedback" read as the person telling the product something. |
+| 2026-10-27 | `toast-action-stays` and `no-dismissible-banner-in-dialog` become lint rules | Both show in the markup; the second one loses data. |
+| 2026-10-28 | The default is defined on variables of the situation, with situations every application has; no domain; real cases come later, as a validation | A domain scenario brought business rules into a default. |
+| 2026-10-28 | To confirm: `field-valid` and `action-done-in-place`, two cases the variables showed and the table did not say | The table covered a field that fails and an action whose place is gone, not their other halves. |
+| 2026-10-28 | A deadline is about the whole application; a partial outcome is about an action on several items; the cases of a field hold with the field on screen | Found by the check: 58 combinations that had no answer and no meaning. |
+| 2026-10-28 | Information about a region goes in that region, as an info banner (`region-info`) | The rule: a message goes where the thing it talks about is. |
+| 2026-10-28 | The whole application failing is a region that failed, the largest one: the shell stays (`app-failed`) | No new case for the same answer; the person keeps the menu and the way out. |
+| 2026-10-28 | Information about a field is its helper text; an application does not succeed; information about an action joins the gap "later" | The last combinations the check found with no answer. |
+| 2026-10-28 | Confirmed: a valid field shows its state and no message (`field-valid`); the session ending is a strict dialog, also over an open one (`app-deadline`); strict superseded on 2026-11-01 | Magma already does the first; a toast over an open dialog can be seen but not used. |
+| 2026-10-28 | A success whose place stays on screen depends on what the action changed: data shown across the page, a toast (`action-done-in-page`); a part that works on its own, a confirmation next to it (`action-done-in-part`). `success-after-change` rewritten to match | A change that shows in many places is not "here"; an independent part is, and the confirmation belongs to it. |
+| 2026-10-28 | To decide: the two gaps, later and partial | An outcome that comes later may belong to the candidate "Notification center"; a partial one to `error-recovery`. |
+| 2026-10-28 | An outcome that comes later is a toast with its action, kept in the notification center (`action-later`); an action taken in charge says so at once (`action-taken`) | The person may have moved on or left: told when it comes, found again later. The notification center becomes a pattern of its own. |
+| 2026-10-28 | A partial outcome goes where a failure goes (`action-partial-in-place`, `action-partial-elsewhere`); what to say and how to retry the ones that failed is `error-recovery` | The same places as a failure; the difference is in the text and in the retry. |
+| 2026-11-01 | The toast of a removal, with or without Undo, is the default `light` toast; `success` is for what an action creates or completes (`removal-toast-neutral`) | A removal is a loss the person wanted, and green celebrates it; the colour follows the kind of action, not the presence of Undo. Chosen live with the domain Actions of the design language. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6556983924 |
+| 2026-11-01 | The session ending is a dialog that closes as Resta collegato: the default `interaction`, the `warning` window with its X; `strict` goes (`app-deadline`) | No gesture loses the work, and Esc closes it as every dialog; the focus and the meaning of closing are `deadline-close` of the domain Actions. Chosen live with the domain Actions of the design language. https://github.com/magma-design-system/magma/issues/1189#issuecomment-6558535505 |
+| 2026-11-03 | An error that stops the person is `tone="strong"` in every place: a part that does not load as an action that fails (`region-failed`, `action-failed-in-place`, `action-partial-in-place`, `app-failed`) | One tone for every error; the weak tone of the drafts of 2026-10-29 read as a note. Chosen in review round 2 of the previews (https://github.com/magma-design-system/magma/issues/1233), over the weak tone. |
+| 2026-11-03 | The error of a dialog stands right above its row of actions (`action-failed-in-place`) | Where the eye goes to try again; the place `actions` decided for the error of an action. Confirmed in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |
+| 2026-11-03 | The connection that drops is a `warning` toast that goes after its time (`app-info`) | A trouble that does not stop the work is a warning, not news; and what was written stays, so the toast need not stay. Chosen in review round 2 of the previews (https://github.com/magma-design-system/magma/issues/1233), over a toast that stays while the connection is off. |
+| 2026-11-03 | Where an example of the value helps, the empty field shows one as its placeholder, "Es: ..." (`field-hint`) | The person sees the shape of the value before typing it; the hint under the field still says the rule. Asked in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |

package/agents/patterns/notification-center.md

@@ -0,0 +1,18 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: notification-center
+kind: pattern
+title: Notification center
+group: messages-and-states
+layer: magma
+status: candidate
+need: >-
+  The person comes back to the outcomes that arrived while they were elsewhere, and to what they
+  still have to act on.
+---
+
+# Notification center
+
+A candidate: a need Magma knows and has not defined yet, cited by `message-placement` (`action-
+later`). Until it is defined, the agent says that no default covers it, and proposes the pattern
+(`get_guide reporting`).