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

package/agents/patterns/error-recovery.md

@@ -0,0 +1,237 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: error-recovery
+kind: pattern
+title: When something fails
+group: messages-and-states
+layer: magma
+status: decided
+need: >-
+  Something did not work, and the person must understand what did not happen and go on without
+  losing their work.
+principle: >-
+  A failure keeps what the person did, says what did not happen, and gives a way on: Try again
+  when it may work, another way when it cannot.
+keywords: [error, failed, could not load, could not save, try again, retry, connection lost, not saved, session expired, conflict]
+not-for:
+  - need: where the error message goes
+    use: message-placement
+  - need: a field with a wrong value
+    use: form-and-validation
+  - need: a list with no results
+    use: empty-state
+  - need: merging the changes of two people on the same record
+    use: concurrent-editing
+assumptions:
+  - The application can tell a failure that trying again may fix from one it cannot.
+high-stakes: false
+components: [mds-banner, mds-toast, mds-button, mds-zero, mds-input-field]
+related: [message-placement, loading, empty-state, confirm-action, form-and-validation, concurrent-editing]
+validated-on: []
+
+variables:
+  what: { values: [content, action], means: "content: data a part of the page loads; action: an operation the person started" }
+  cause: { values: [transient, lasting, conflict, session], means: "transient: the network or the server failed, trying again may work; lasting: trying again fails the same way (no permission, the item is gone, the data is refused); conflict: someone else changed the same thing meanwhile; session: the session ended" }
+  known: { values: ["yes", "no"], means: "does the application know what happened (no: the connection dropped after sending)" }
+  items: { values: [one, many], means: "how many items the action acts on" }
+
+cases:
+  - { id: retry-content, what: content, cause: transient, known: "yes", where: "what was there stays; an error banner in that part with Try again; when it works, the banner goes", use: ["mds-banner variant=error tone=strong", "mds-button slot=action await"] }
+  - { id: content-another-way, what: content, cause: lasting, known: "yes", where: "no Try again: says why and gives another way (the not-found of empty-state for a thing that is gone; who can give access)", use: ["mds-banner variant=error tone=strong", "mds-zero"] }
+  - { id: retry-action, what: action, cause: transient, known: "yes", items: one, where: "says nothing was changed; what was written stays; in the place message-placement gives: a banner in place, right above the row, whose action on screen is the new try, so the banner has no Try again of its own; or a toast that stays, with Try again", use: ["mds-banner variant=error tone=strong", "mds-toast variant=error duration=0 dismissible"] }
+  - { id: action-another-way, what: action, cause: lasting, known: "yes", items: one, where: "no Try again: says why and gives another way (the errors on the fields for refused data; who can do it; back to the list for a thing that is gone)", use: ["mds-banner variant=error", "mds-input-field message"] }
+  - { id: check-or-repeat, what: action, cause: transient, known: "no", where: "Try again at once when repeating does no harm (saving the same values); otherwise the application first asks the server what happened, then tells it: done as a success, not done as retry-action, the action on screen being the new try", use: ["mds-banner variant=error tone=strong", "mds-toast variant=error duration=0 dismissible"] }
+  - { id: changed-meanwhile, what: action, cause: conflict, known: "yes", where: "never overwrite in silence: says who changed it and when, that nothing was saved, and the changes of the person stay on screen", use: ["mds-banner variant=error tone=strong"], see: concurrent-editing }
+  - { id: sign-in-again, cause: session, known: "yes", where: "says the session ended and nothing was saved; Sign in, alone in the banner, opens the sign-in in a new tab, and the action that failed is hidden until the session is back, so it cannot fail again; back on the page the banner goes and the action comes back: the work never leaves the page", use: ["mds-banner variant=error tone=strong", "mds-button slot=action href target=blank"] }
+  - { id: partial, what: action, cause: [transient, lasting], known: "yes", items: many, where: "says how many worked and which did not, and why; Try again acts only on those that failed for a transient cause", use: ["mds-banner variant=error tone=strong", "mds-toast variant=error duration=0 dismissible"] }
+gaps: []
+not-applicable:
+  - { what: content, cause: conflict, why: "loading changes nothing: there is nothing to conflict with" }
+  - { what: content, known: "no", why: "loading changes nothing: the outcome is always known" }
+  - { cause: [lasting, conflict, session], known: "no", why: "the server answered: the outcome is known" }
+
+always-true:
+  - id: keep-the-work
+    rule: A failure never loses what the person wrote or chose.
+    checked-by: review
+  - id: says-what-did-not-happen
+    rule: The error says what did not happen and what to do.
+    checked-by: review
+  - id: retry-only-if-it-may-work
+    rule: Try again only when trying again may work; otherwise another way.
+    checked-by: review
+  - id: no-raw-error
+    rule: Never the raw text of an HTTP status or an exception.
+    checked-by: review
+  - id: no-repeat-by-itself
+    rule: An action is never repeated by itself, unless repeating it does no harm.
+    checked-by: review
+  - id: no-silent-overwrite
+    rule: A save never overwrites a change made by someone else without saying so.
+    checked-by: review
+  - id: no-dismissible-banner-in-dialog
+    from: message-placement
+
+open-choices:
+  - { id: support-contact, default: "none: the text says to try again later", may: "say who to contact when the problem stays (\"If the problem stays, write to the help desk\")" }
+
+situations:
+  - { situation: A list does not load, case: retry-content }
+  - { situation: "A record opens, and the person may not see it", case: content-another-way }
+  - { situation: Saving a form fails on the server, case: retry-action }
+  - { situation: A form is refused by the server because a code is already in use, case: action-another-way }
+  - { situation: "12 items are archived, 3 fail", case: partial }
+  - { situation: A save fails because the session ended, case: sign-in-again }
+  - { situation: The connection drops while a message is being sent, case: check-or-repeat, note: the application checks first }
+  - { situation: The connection drops while a form is saved, case: check-or-repeat, note: Try again at once }
+  - { situation: "A record is saved, and someone else had changed it meanwhile", case: changed-meanwhile }
+---
+
+# When something fails
+
+**A failure keeps what the person did, says what did not happen, and gives a way on: Try again when it may work, another way when it cannot.**
+
+## When to use it
+
+A load or an action that failed: the network, the server, a permission, a thing that is gone,
+a change made by someone else, a session that ended. Where the message goes is
+`message-placement`; this pattern is what follows. Not a field with a wrong value
+(`form-and-validation`), not a list with no results (`empty-state`): no results is not an error.
+
+## What decides it
+
+Four questions: whether a load or an action failed, why (trying again may work, it will fail
+the same way, someone else changed the same thing, the session ended), whether the application
+knows what happened, and whether the action was on one item or many.
+
+## 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 loads; action: an operation the person started |
+| `cause` | `transient`, `lasting`, `conflict`, `session` | transient: the network or the server failed, trying again may work; lasting: trying again fails the same way (no permission, the item is gone, the data is refused); conflict: someone else changed the same thing meanwhile; session: the session ended |
+| `known` | `yes`, `no` | does the application know what happened (no: the connection dropped after sending) |
+| `items` | `one`, `many` | how many items the action acts on |
+
+A case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `retry-content` | what: content; cause: transient; known: yes | what was there stays; an error banner in that part with Try again; when it works, the banner goes | `mds-banner variant=error tone=strong`, `mds-button slot=action await` |
+| `content-another-way` | what: content; cause: lasting; known: yes | no Try again: says why and gives another way (the not-found of empty-state for a thing that is gone; who can give access) | `mds-banner variant=error tone=strong`, `mds-zero` |
+| `retry-action` | what: action; cause: transient; known: yes; items: one | says nothing was changed; what was written stays; in the place message-placement gives: a banner in place, right above the row, whose action on screen is the new try, so the banner has no Try again of its own; or a toast that stays, with Try again | `mds-banner variant=error tone=strong`, `mds-toast variant=error duration=0 dismissible` |
+| `action-another-way` | what: action; cause: lasting; known: yes; items: one | no Try again: says why and gives another way (the errors on the fields for refused data; who can do it; back to the list for a thing that is gone) | `mds-banner variant=error`, `mds-input-field message` |
+| `check-or-repeat` | what: action; cause: transient; known: no | Try again at once when repeating does no harm (saving the same values); otherwise the application first asks the server what happened, then tells it: done as a success, not done as retry-action, the action on screen being the new try | `mds-banner variant=error tone=strong`, `mds-toast variant=error duration=0 dismissible` |
+| `changed-meanwhile` | what: action; cause: conflict; known: yes | never overwrite in silence: says who changed it and when, that nothing was saved, and the changes of the person stay on screen; see `concurrent-editing` | `mds-banner variant=error tone=strong` |
+| `sign-in-again` | cause: session; known: yes | says the session ended and nothing was saved; Sign in, alone in the banner, opens the sign-in in a new tab, and the action that failed is hidden until the session is back, so it cannot fail again; back on the page the banner goes and the action comes back: the work never leaves the page | `mds-banner variant=error tone=strong`, `mds-button slot=action href target=blank` |
+| `partial` | what: action; cause: transient or lasting; known: yes; items: many | says how many worked and which did not, and why; Try again acts only on those that failed for a transient cause | `mds-banner variant=error tone=strong`, `mds-toast variant=error duration=0 dismissible` |
+
+Not applicable:
+
+| When | Why |
+| --- | --- |
+| what: content; cause: conflict | loading changes nothing: there is nothing to conflict with |
+| what: content; known: no | loading changes nothing: the outcome is always known |
+| cause: lasting or conflict or session; known: no | the server answered: the outcome is known |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+- An error banner, `mds-banner` with `variant="error" tone="strong"`, in the place
+  `message-placement` gives: a title that says what did not happen, a sentence with what to do,
+  and Try again (`mds-button` in its `action` slot) when trying again may work. Where the action
+  that failed is on screen (a form, a dialog), the banner stands right above its row and has no
+  Try again: the action itself is the new try.
+- When the place is gone, a toast that stays, with Try again (`message-placement`,
+  `action-failed-elsewhere`).
+- For a thing that is gone, the not-found panel of `empty-state`.
+- For an ended session, Sign in alone in the banner: the sign-in opens in a new tab, so the
+  page and what was written stay where they are; the action that failed is hidden until the
+  session is back, then the banner goes and the action comes back.
+
+## Behaviour over time
+
+- What was on screen stays, and what was written stays.
+- Try again waits (`await`), and when it works the banner goes.
+- From the third failure in a row on the same thing, the text says to try again later; Try
+  again stays.
+- An action whose outcome is unknown is repeated at once only when repeating does no harm;
+  otherwise the application asks the server first. A payment follows the rule of high-stakes
+  flows: no default decides for the person.
+
+## 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 |
+| --- | --- | --- |
+| `keep-the-work` | A failure never loses what the person wrote or chose. | review |
+| `says-what-did-not-happen` | The error says what did not happen and what to do. | review |
+| `retry-only-if-it-may-work` | Try again only when trying again may work; otherwise another way. | review |
+| `no-raw-error` | Never the raw text of an HTTP status or an exception. | review |
+| `no-repeat-by-itself` | An action is never repeated by itself, unless repeating it does no harm. | review |
+| `no-silent-overwrite` | A save never overwrites a change made by someone else without saying so. | review |
+| `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. (from `message-placement`) | review; lint `magma/no-dismissible-banner-in-modal` to write |
+
+## 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 |
+| --- | --- | --- |
+| `support-contact` | none: the text says to try again later | say who to contact when the problem stays ("If the problem stays, write to the help desk") |
+
+## 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 does not load | `retry-content` |
+| A record opens, and the person may not see it | `content-another-way` |
+| Saving a form fails on the server | `retry-action` |
+| A form is refused by the server because a code is already in use | `action-another-way` |
+| 12 items are archived, 3 fail | `partial` |
+| A save fails because the session ended | `sign-in-again` |
+| The connection drops while a message is being sent | `check-or-repeat`: the application checks first |
+| The connection drops while a form is saved | `check-or-repeat`: Try again at once |
+| A record is saved, and someone else had changed it meanwhile | `changed-meanwhile` |
+
+## Accessibility
+
+- An error banner is read out at once (`role="alert"`, `mds-banner` error).
+- The focus stays on the control that was waiting; Try again takes it only when the person
+  moves to it.
+
+## Content
+
+- What did not happen, then what to do: "The users could not be loaded. Check the connection,
+  then try again." "Nothing was changed."
+- For many items, how many and which: "9 archived, 3 not: they are open in another window."
+
+## Magma gaps
+
+None blocking: retrying is logic of the application.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-16 | Where the error goes is `message-placement`; this pattern is what follows | One answers where, the other what stays, how to retry, when to stop. |
+| 2026-10-28 | Draft with variables; the ended session, the unknown outcome, the conflict and several failures in a row left as gaps | The sources do not settle them. |
+| 2026-10-28 | An ended session signs in again in a new tab, then Try again (`sign-in-again`) | The work never leaves the page; it works with an external single sign-on too. |
+| 2026-10-28 | An unknown outcome is repeated at once only when repeating does no harm; otherwise the server is asked first (`check-or-repeat`) | A blind Try again can send or create twice. |
+| 2026-10-28 | A change made by someone else meanwhile: here only the rule (`no-silent-overwrite`, `changed-meanwhile`); merging is the candidate `concurrent-editing` | Locks, versions and merging are a pattern of their own. |
+| 2026-10-28 | From the third failure in a row, the text says to try again later; who to contact is a product's choice (`support-contact`) | Insisting with the same text does not help; the help desk differs by product. |
+| 2026-11-03 | An error that stops the person is `tone="strong"` (`retry-content`, `content-another-way`, `retry-action`, `check-or-repeat`, `changed-meanwhile`, `sign-in-again`, `partial`) | One tone for every error, as `message-placement`. Chosen in review round 2 of the previews (https://github.com/magma-design-system/magma/issues/1233), over the weak tone. |
+| 2026-11-03 | Where the action that failed is on screen, its banner has no Try again: the action is the new try (`retry-action`, `check-or-repeat`) | Two buttons that do the same thing; the rule `failed` of the domain Actions. Applied in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |
+| 2026-11-03 | An ended session shows Sign in alone, in the banner, and hides the action that failed until the session is back (`sign-in-again`) | The action would fail again until the person signs in: it is not offered. Asked in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |

package/agents/patterns/form-and-validation.md

@@ -0,0 +1,16 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: form-and-validation
+kind: pattern
+title: Form and validation
+group: input
+layer: magma
+status: candidate
+need: >-
+  The person fills in a form, sees what is wrong and where, and sends it.
+---
+
+# Form and validation
+
+A candidate: a need Magma knows and has not defined yet, cited by `error-recovery`. Until it is
+defined, the agent says that no default covers it, and proposes the pattern (`get_guide reporting`).

package/agents/patterns/item-list.md

@@ -0,0 +1,214 @@
+---
+# A Magma building block: the format and the commands are in docs/PATTERNS.md, "A building block".
+id: item-list
+kind: block
+title: Item list
+group: data
+layer: magma
+status: decided
+need: >-
+  The person sees a set of items, narrows it to the ones they need, knows how many there are,
+  and reaches the rest.
+principle: "The search on top, then how many, then the items, then the pages: the same order in every list."
+keywords: [list, list of items, results, search form, filter bar, filters, results summary, how many, table of items, list of cards, pages, pagination, sub-list, select rows, batch actions, new items]
+not-for:
+  - need: the head of the page that holds the list, its title and its actions (New, Export)
+    use: page-header
+  - need: choosing items from a list for something else (members to add to a group, documents to attach)
+    use: choose-items
+assumptions:
+  - The back end can search, count, sort and page the set (list-with-filters).
+high-stakes: false
+components: [mds-input, mds-input-field, mds-input-select, mds-filter, mds-filter-item, mds-notification, mds-text, mds-button, mds-table, mds-table-header-cell, mds-file, mds-paginator]
+used-by: [list-with-filters, empty-state, loading]
+related: [list-with-filters, empty-state, loading, error-recovery, page-header, choose-items]
+validated-on: []
+
+variables:
+  size: { values: [few, many], means: "few: the items fit in one page and are read at a glance (the documents of a request, the members of a small group); many: more than a page, to search and to page through" }
+  goal: { values: [open, act], means: "open: the person opens one item at a time; act: the person acts on several items at once (assign, archive)" }
+  changes: { values: ["no", by-others], means: "by-others: other people or systems add or change items while the list is on screen (a queue of incoming requests)" }
+
+regions:
+  - { id: search, when: { size: many }, what: "the search form: a field that searches the number and the name, then a select for each property with a few values, as short fields under it, two to a row, in a group of fields at the width of a form", use: ["mds-input type=search", "mds-input-field", "mds-input-select"] }
+  - { id: filters, when: { size: many }, what: "the statuses as one filter, each with how many items it would show, in the search form under its fields, when the items have a status", use: ["mds-filter", "mds-filter-item"] }
+  - { id: summary, when: { size: many }, what: "one line: which items are on screen out of how many (\"11-20 di 46 pratiche\"), read out after every change, with Rimuovi i filtri when there are any", use: ["mds-text typography=detail tag=p", "mds-button variant=dark tone=text size=sm"] }
+  - { id: new-items, when: { changes: by-others }, what: "at the end of the line of the summary: how many items are new, the count in an info dot that pulses when it grows and the words in the info colour, and Mostra; the line keeps its place while nothing is new; Mostra hides once pressed and the focus goes to the heading of the list (list-with-filters, show-new-items)", use: ["mds-notification variant=info pulse", "mds-text typography=detail", "mds-button variant=info tone=outline size=sm"] }
+  - { id: selection, when: { goal: act }, what: "a checkbox on each row and the bar of the batch actions, with how many are selected (list-with-filters, act-on-many)", use: ["mds-table selectable", "mds-button slot=batch-action"] }
+  - { id: results, required: true, what: "the items: one row each, its number or its name the link to its page; the columns that can order the list order it from their headers; files as mds-file, one per file, in a grid; cards in a grid when the items are seen rather than read (results-as-cards)", use: ["mds-table sorting=external", "mds-table-header-cell sortable sort-key", "mds-file"] }
+  - { id: pages, when: { size: many }, what: "the pages, under the items, only when there is more than one", use: ["mds-paginator"] }
+
+always-true:
+  - id: same-order
+    rule: "The search form, the summary, the items, the pages: in this order in every list; a region with nothing to show is left out, with its space."
+    checked-by: review
+  - id: order-in-the-headers
+    rule: "The order of the list is set from the headers of the columns that can sort it, never by a field of the search form."
+    checked-by: review
+  - id: frame-wide-results
+    rule: "The fields of the search form stand at the width of a form, the filter of the statuses as wide as its statuses; the items take the whole frame of the page or of their section."
+    checked-by: review
+  - id: summary-says-how-many
+    from: list-with-filters
+  - id: link-names-the-item
+    from: list-with-filters
+  - id: nothing-moves-by-itself
+    from: list-with-filters
+  - id: form
+    from: widths
+  - id: between-groups
+    from: rhythm
+  - id: between-fields
+    from: rhythm
+  - id: title-content
+    from: rhythm
+
+open-choices:
+  - { id: results-as-cards, default: "a table, one row per item", may: "show the items as cards in a grid (mds-card) when they are seen rather than read: pictures, documents, people" }
+
+situations:
+  - { id: requests-of-an-office, situation: "The requests of an office, opened one at a time", size: many, goal: open, changes: "no" }
+  - { id: requests-to-assign, situation: "Requests to assign to an operator, several at once", size: many, goal: act, changes: "no" }
+  - { id: queue-of-a-desk, situation: "The queue of a front desk, where requests arrive while it is open", size: many, goal: open, changes: by-others }
+  - { id: documents-of-a-request, situation: "The documents of a request, a section of its page", size: few, goal: open, changes: "no" }
+---
+
+# Item list
+
+**The search on top, then how many, then the items, then the pages: the same order in every list.**
+
+## When to use it
+
+Wherever a page shows a set of items: the list of the requests of an office, the queue of a
+desk, the documents of a request in a section of its page. It came out of the round of the
+building blocks (2026-11-03): the search form, the summary and the results come back in the same
+arrangement in `list-with-filters`, in `empty-state` (`clear-filters`: the panel takes the place
+of the results, the search and the summary stay) and in `loading` (`keep-while-reloading`: the
+results stay while the search reloads them). One block, not a bar of filters and a summary
+apart: the regions always come together, in one order, and their spaces relate. The behaviour
+over time (the query in the address, the first page after a change, the newest answer wins) is
+`list-with-filters`; the block is where each part stands. Not the head of the page that holds
+the list (`page-header`).
+
+## What decides it
+
+Three questions: whether the items fit in one page (then there is nothing to search nor to
+page), whether the person acts on several at once (then they select them), and whether others
+change the set while it is on screen (then the new items wait behind a line).
+
+## Regions
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `size` | `few`, `many` | few: the items fit in one page and are read at a glance (the documents of a request, the members of a small group); many: more than a page, to search and to page through |
+| `goal` | `open`, `act` | open: the person opens one item at a time; act: the person acts on several items at once (assign, archive) |
+| `changes` | `no`, `by-others` | by-others: other people or systems add or change items while the list is on screen (a queue of incoming requests) |
+
+A region shows where its When holds, in this order: a required one always, the others when there is something to put in them.
+
+| Region | When | Required | What | Use |
+| --- | --- | --- | --- | --- |
+| `search` | size: many |  | the search form: a field that searches the number and the name, then a select for each property with a few values, as short fields under it, two to a row, in a group of fields at the width of a form | `mds-input type=search`, `mds-input-field`, `mds-input-select` |
+| `filters` | size: many |  | the statuses as one filter, each with how many items it would show, in the search form under its fields, when the items have a status | `mds-filter`, `mds-filter-item` |
+| `summary` | size: many |  | one line: which items are on screen out of how many ("11-20 di 46 pratiche"), read out after every change, with Rimuovi i filtri when there are any | `mds-text typography=detail tag=p`, `mds-button variant=dark tone=text size=sm` |
+| `new-items` | changes: by-others |  | at the end of the line of the summary: how many items are new, the count in an info dot that pulses when it grows and the words in the info colour, and Mostra; the line keeps its place while nothing is new; Mostra hides once pressed and the focus goes to the heading of the list (list-with-filters, show-new-items) | `mds-notification variant=info pulse`, `mds-text typography=detail`, `mds-button variant=info tone=outline size=sm` |
+| `selection` | goal: act |  | a checkbox on each row and the bar of the batch actions, with how many are selected (list-with-filters, act-on-many) | `mds-table selectable`, `mds-button slot=batch-action` |
+| `results` | any | yes | the items: one row each, its number or its name the link to its page; the columns that can order the list order it from their headers; files as mds-file, one per file, in a grid; cards in a grid when the items are seen rather than read (results-as-cards) | `mds-table sorting=external`, `mds-table-header-cell sortable sort-key`, `mds-file` |
+| `pages` | size: many |  | the pages, under the items, only when there is more than one | `mds-paginator` |
+
+## Layout
+
+- The block is one column of two groups, `gap-between-groups` (1000) between them
+  (`rhythm/between-groups`): the search form, then the items.
+- The search form is a `form role="search"`, its fields in a `field-group` at `max-w-form`
+  (`widths/form`): the search field, then the selects as `short` fields under it, two to a
+  row; the filter of the statuses under them, aligned to the start, as wide as its statuses;
+  `gap-between-fields` (600) between the fields and the filter.
+- The items group: the summary line, then the items, `gap-title-content` (300) between them, as
+  a title and the content it names (`rhythm/title-content`); the pages under the items,
+  `gap-between-fields` (600), aligned to the start.
+- The summary line is a row: the summary, Rimuovi i filtri beside it (`gap-inline`), and at its
+  end the line of the new items; on a narrow screen the line of the new items sits under the
+  summary from the start, so neither its arrival nor its count moves the items.
+- The items take the whole width of the frame or of their section (`w-full`); a table wider
+  than a phone scrolls inside its own border, never the page, with its cells on one line
+  (`[&_mds-table-cell]:text-nowrap`, as the usage of `mds-table` says).
+- With few items there is no search, no summary and no pages: the items stand right under the
+  title of their section.
+- Files are `mds-file`, one per file, in a grid at `gap-between-containers` (400): one column,
+  two from `@2xl` of their section, as `record-detail` lays out its documents.
+- When nothing matches, the panel of `empty-state` (`clear-filters`) takes the place of the
+  items, and the search and the summary stay; on the first load, the well of `loading` takes it.
+
+## 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 |
+| --- | --- | --- |
+| `same-order` | The search form, the summary, the items, the pages: in this order in every list; a region with nothing to show is left out, with its space. | review |
+| `order-in-the-headers` | The order of the list is set from the headers of the columns that can sort it, never by a field of the search form. | review |
+| `frame-wide-results` | The fields of the search form stand at the width of a form, the filter of the statuses as wide as its statuses; the items take the whole frame of the page or of their section. | review |
+| `summary-says-how-many` | The summary says which items are on screen out of how many, and is read out after every change. (from `list-with-filters`) | review |
+| `link-names-the-item` | Each item is opened by a link that names it, never by an Open repeated on every row. (from `list-with-filters`) | review |
+| `nothing-moves-by-itself` | Items added or changed by others never move what is on screen; they wait until the person asks for them. (from `list-with-filters`) | review |
+| `form` | `max-w-form` on the form, the width of the text around it (`56ch`, 532 px at 16 px); its fields take the whole column, and its row of actions stands at the end of the column (`actions/place`) (from `widths`) |  |
+| `between-groups` | `gap-between-groups` (1000) between two groups of fields of one form (the fieldsets of personal data and of residence) (from `rhythm`) |  |
+| `between-fields` | `gap-between-fields` (600) between two fields of a form, or two rows of data (from `rhythm`) |  |
+| `title-content` | `gap-title-content` (300) between a title and the content it names (from `rhythm`) |  |
+
+## 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 |
+| --- | --- | --- |
+| `results-as-cards` | a table, one row per item | show the items as cards in a grid (mds-card) when they are seen rather than read: pictures, documents, people |
+
+## Situations
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+Situations every application has, each with the regions it shows: they give the examples, the texts and the keywords. The situations of a product's own domain go in its layer.
+
+| Id | Situation | Regions |
+| --- | --- | --- |
+| `requests-of-an-office` | The requests of an office, opened one at a time | `search`, `filters`, `summary`, `results`, `pages` |
+| `requests-to-assign` | Requests to assign to an operator, several at once | `search`, `filters`, `summary`, `selection`, `results`, `pages` |
+| `queue-of-a-desk` | The queue of a front desk, where requests arrive while it is open | `search`, `filters`, `summary`, `new-items`, `results`, `pages` |
+| `documents-of-a-request` | The documents of a request, a section of its page | `results` |
+
+## Accessibility
+
+- The search form has `role="search"`; each field has its label (`mds-input-field`).
+- The summary has `role="status"`: it is read out after every change, without moving the focus.
+- Each item is opened by a link that names it, never by an Open repeated on every row.
+- The selection of a row is a checkbox named after its item (`mds-table selectable`).
+
+## Content
+
+- The summary says which items out of how many, with the noun of the set: "11-20 di 46
+  pratiche". When nothing matches it says so ("Nessuna pratica corrisponde") and the panel of
+  `empty-state` takes the place of the items, with Rimuovi i filtri only in the panel
+  (`clear-filters`).
+- Rimuovi i filtri, the words of `mds-filter`.
+- The new items: "2 nuove pratiche", the 2 in the dot, then Mostra.
+
+## Magma gaps
+
+- None for the default: every region is a component of Magma or a class of its Tailwind layer.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-11-03 | The list of items is a block: the search, the summary, the items and the pages come back in `list-with-filters`, `empty-state` and `loading` | The round of the building blocks, from the previews of the three patterns; the docs site names the filter bar and the results summary among the candidates (`plan/DIRECTION.md`, Building blocks section). |
+| 2026-11-03 | One block, not a bar of filters and a summary apart | The maintainer's choice: the regions always come together, in one order, with related spaces, so one answer of `get_pattern` gives the whole list; the regions with a When cover the list of a section, with no search. |
+| 2026-11-03 | The line of the new items carries the dot that pulses when the count grows, from `mds-notification` once #1216 lands; until then, none | The maintainer's note in the review of round 3 ("l'elemento dovrebbe avere una icona pulsante"); asked whether to draw it by hand meanwhile, he chose #1216 first: a product never writes the animation itself (`list-with-filters`, Magma gaps). |
+| 2026-11-04 | The dot of the new items is `mds-notification variant="info" pulse`, the count its `value` | #1216 landed (PR #1239), as the decision of 2026-11-03 waited for: the pulse follows `value`, so the dot carries the count (`list-with-filters`). |