@maggioli-design-system/magma-react 2.8.0 → 2.10.0

package/agents/patterns/labels-and-values.md

@@ -0,0 +1,184 @@
+---
+# A Magma building block: the format and the commands are in docs/PATTERNS.md, "A building block".
+id: labels-and-values
+kind: block
+title: Labels and values
+group: data
+layer: magma
+status: decided
+need: >-
+  The person reads the data of an item, each value under the name of what it is.
+principle: Each value stands under its label, row by row, in two columns where there is room.
+keywords: [labels and values, data, details, description list, dl, key value, key-value pairs, fields of a record, read-only data, summary of the data, properties]
+not-for:
+  - need: changing the data (a form, its fields and their errors)
+    use: form-and-validation
+  - need: many items, each with the same properties (a table)
+    use: item-list
+high-stakes: false
+components: [mds-text]
+used-by: [record-detail, confirm-action]
+related: [record-detail, confirm-action, item-list, form-and-validation]
+validated-on: []
+
+variables:
+  place: { values: [section, inside], means: "section: the data is a section of a page, with a title of its own; inside: the data is inside a container that names it already (the window of a dialog, a card, a form above its row of actions)" }
+
+regions:
+  - { id: title, when: { place: section }, what: "the title of the section, which names the group of data (\"Dati anagrafici\", \"Recapiti\")", use: ["mds-text typography=section tag=h2"] }
+  - { id: pairs, required: true, what: "the list of the data: for each one its label, then its value, in the order the person reads them; a long value takes the whole row; a value not given says so", use: ["mds-text typography=label tag=dt", "mds-text tag=dd"] }
+
+always-true:
+  - id: label-above-value
+    rule: "Each value stands under its label: a dl with one div for each pair, the label (dt) in the muted foreground, the value (dd) in the default one; never a table of two columns, never a form."
+    checked-by: review
+  - id: columns-by-room
+    rule: "Two columns where the list has room, one under it, at the threshold of the halves of a form (28rem, field-group): the data and the fields that change it go to one column together; never a number of columns fixed on the page."
+    checked-by: review
+  - id: long-value-whole-row
+    rule: "A long value (a text, an address on several lines, a list) takes the whole row, at every width."
+    checked-by: review
+  - id: missing-says-so
+    rule: "A value not given says so, \"Non indicato\", in the muted foreground; never an empty space or a dash."
+    checked-by: review
+  - id: read-not-disabled
+    rule: "Data the person cannot change here is read as labels and values, never shown as fields disabled or read-only; changing it is a form of its own (record-detail, edit-data)."
+    checked-by: review
+  - id: section
+    from: titles
+  - id: title-content
+    from: rhythm
+  - id: label-control
+    from: rhythm
+  - id: between-fields
+    from: rhythm
+
+open-choices: []
+
+situations:
+  - { id: data-of-a-contact, situation: "The personal data of a contact, a section of its page", place: section }
+  - { id: what-is-sent, situation: "What a reminder sends and to whom, in the dialog that asks before sending it", place: inside }
+  - { id: payment-before-paying, situation: "The data of a payment, above the button that pays it", place: inside }
+---
+
+# Labels and values
+
+**Each value stands under its label, row by row, in two columns where there is room.**
+
+## When to use it
+
+Wherever a page or a container shows the data of one item to read: the personal data of a
+contact, what a message sends and to whom before it goes, the amount of a payment above the
+button that pays it. It came out of the round of the building blocks (2026-11-03): the list of
+labels and values comes back in `record-detail` (the data of the record, section by section)
+and in `confirm-action` (`ask-before-sending`: the recipient and the text), and the previews of
+`error-recovery` and `loading` write it too. Not for changing the data (a form,
+`form-and-validation`), and not for many items with the same properties (a table, `item-list`).
+
+## What decides it
+
+One question: whether the data is a section of the page, with a title of its own, or stands
+inside a container that names it already.
+
+## Regions
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `place` | `section`, `inside` | section: the data is a section of a page, with a title of its own; inside: the data is inside a container that names it already (the window of a dialog, a card, a form above its row of actions) |
+
+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 |
+| --- | --- | --- | --- | --- |
+| `title` | place: section |  | the title of the section, which names the group of data ("Dati anagrafici", "Recapiti") | `mds-text typography=section tag=h2` |
+| `pairs` | any | yes | the list of the data: for each one its label, then its value, in the order the person reads them; a long value takes the whole row; a value not given says so | `mds-text typography=label tag=dt`, `mds-text tag=dd` |
+
+## Layout
+
+- The list is a `dl` with one `div` for each pair; in each pair the label, then the value,
+  `gap-label-control` (300) between them (`rhythm/label-control`), as the label and the control
+  of a field.
+- The pairs are rows of data: `gap-between-fields` (600) between them (`rhythm/between-fields`),
+  in both directions.
+- Two columns from 28rem of the list, one under it: the threshold of `field-group`, so the data
+  and the form that changes it break at the same width; the pairs fill the rows in reading
+  order, each starting at the top of its row (`items-start`, as `field-group`). A long value
+  spans the row (`col-span-full`, never `col-span-2`, which adds a track on one column).
+- Until Magma carries the columns (Magma gaps): `@md:grid-cols-2` on the `dl`, measured by a
+  container as wide as the list: a `section` is one; any other parent takes `@container` (a
+  `form`, the `div` that holds the tabs of a record and their panels); inside `mds-banner` a
+  `div class="@container"` wraps the list (the banner measures its close button too).
+- In a section of a page the list stands in the column of a form (`max-w-form`): the shape it
+  has in a dialog and in the form that changes it.
+- With a title (`place: section`), the title and the list are `gap-title-content` (300) apart
+  (`rhythm/title-content`), and the section stands from the next one as the sections of a page
+  do (`rhythm/between-sections`).
+- Inside a container, the list takes its width and its inset; in a form, it stands above the
+  fields or the row of actions, `gap-content-actions` from the row (`rhythm/content-actions`).
+
+## 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 |
+| --- | --- | --- |
+| `label-above-value` | Each value stands under its label: a dl with one div for each pair, the label (dt) in the muted foreground, the value (dd) in the default one; never a table of two columns, never a form. | review |
+| `columns-by-room` | Two columns where the list has room, one under it, at the threshold of the halves of a form (28rem, field-group): the data and the fields that change it go to one column together; never a number of columns fixed on the page. | review |
+| `long-value-whole-row` | A long value (a text, an address on several lines, a list) takes the whole row, at every width. | review |
+| `missing-says-so` | A value not given says so, "Non indicato", in the muted foreground; never an empty space or a dash. | review |
+| `read-not-disabled` | Data the person cannot change here is read as labels and values, never shown as fields disabled or read-only; changing it is a form of its own (record-detail, edit-data). | review |
+| `section` | the style `h5` (20px), the tag of its place in the outline (`h2` under the page) (from `titles`) |  |
+| `title-content` | `gap-title-content` (300) between a title and the content it names (from `rhythm`) |  |
+| `label-control` | `gap-label-control` (300) between the label of a field, its control and its message (from `rhythm`) |  |
+| `between-fields` | `gap-between-fields` (600) between two fields of a form, or two rows of data (from `rhythm`) |  |
+
+## 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 |
+| --- | --- | --- |
+| `data-of-a-contact` | The personal data of a contact, a section of its page | `title`, `pairs` |
+| `what-is-sent` | What a reminder sends and to whom, in the dialog that asks before sending it | `pairs` |
+| `payment-before-paying` | The data of a payment, above the button that pays it | `pairs` |
+
+## Accessibility
+
+- A `dl` with `dt` and `dd` (`mds-text tag="dt"`, `tag="dd"`): a screen reader announces a
+  list of terms and reads each label with its value.
+- The title of a section is a heading of the outline of the page (`h2` under the `h1` of the
+  page, `titles/section`).
+- A value that is a link names where it goes; a status is an `mds-badge` with its label.
+
+## Content
+
+- A label names the datum in a few words, with a capital and no colon: "Codice fiscale",
+  "Nato il", "Destinatario".
+- A value is written as the person reads it, not as the system stores it: "1 gennaio 1980",
+  "16,00 euro", never `1980-01-01` or `16.0`.
+- A value not given: "Non indicato".
+
+## Magma gaps
+
+- No component nor carrier for labels and values: a `dl` of `mds-text`, laid out with Tailwind.
+  `@md` copies the threshold of `field-group` by its value, which `widths/by-role` forbids, and
+  in px (448): with a root font other than 16 px the two part (measured at 17 px: a list of
+  449 px, one column in `field-group`, two with `@md`). A class with the tracks of
+  `field-group`, whose children take one track unless they span the row, would carry them; or
+  a container size in rem with a variant of its own, as `--magma-container-actions` does.
+- The base styles of Magma keep the margins the browser gives `dl` and `dd` (the indent of
+  `dd`): `m-0` on both.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-11-03 | Labels and values are a block: they come back in `record-detail` and `confirm-action` | The round of the building blocks, from the previews of the patterns; `record-detail` listed the missing component among its Magma gaps. |
+| 2026-11-03 | Two columns from the threshold of `field-group`, one under it | The previews fixed two columns on the page, which squeeze a long value on a phone; the threshold of the halves of a form keeps the data and its form together. |
+| 2026-11-03 | In a section of a page the list stands in the column of a form, `max-w-form` | The shape it has in a dialog and in the form that changes it; across the whole section at 1024 px its columns were 476 px for values of a few words. The maintainer's choice A in the review of round 3. |

package/agents/patterns/list-with-filters.md

@@ -0,0 +1,282 @@
+---
+# A Magma pattern: the format and the commands are in docs/PATTERNS.md.
+id: list-with-filters
+kind: pattern
+title: List with filters
+group: data
+layer: magma
+status: decided
+need: >-
+  The person finds the items they need in a long list, by searching, filtering and paging.
+principle: The back end finds the items, the address keeps the query, and nothing on screen moves until the person asks.
+keywords: [list, search, filter, filters, results, table, pages, pagination, sort, select rows, bulk actions, batch actions, queue, new items]
+not-for:
+  - need: choosing items from a list for something else (members to add to a group, documents to attach)
+    use: choose-items
+  - need: choosing one value for a field of a form (the recipient of a message)
+    use: form-and-validation
+  - need: a list with nothing to show
+    use: empty-state
+  - need: a list that is loading
+    use: loading
+  - need: a list that could not be loaded
+    use: error-recovery
+  - need: where the outcome of an action on the list is told
+    use: message-placement
+  - need: what a role may not see or do in the list
+    use: permissions
+assumptions:
+  - The back end can search, count, sort and page the set.
+  - The application knows whether other people or systems change the set while it is on screen.
+high-stakes: false
+components: [mds-input, mds-input-field, mds-input-select, mds-filter, mds-filter-item, mds-table, mds-table-header-cell, mds-paginator, mds-notification, mds-text, mds-badge, mds-button, mds-card]
+related: [loading, empty-state, error-recovery, message-placement, confirm-action, record-detail, choose-items, page-header, item-list, app-shell]
+validated-on: []
+
+variables:
+  goal: { values: [open, act], means: "open: the person opens one item at a time (a request, to work on it); act: the person acts on several items at once (archive, assign, delete)" }
+  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)" }
+
+cases:
+  - { id: find-and-open, goal: open, changes: "no", where: "the title of the list, a search form, the summary, the results and the pages; the name or the number of each item is the link to its page", use: ["mds-input type=search", "mds-filter", "mds-input-select", "mds-table sorting=external", "mds-table-header-cell sortable sort-key", "mds-paginator"] }
+  - { id: act-on-many, goal: act, changes: "no", where: "a checkbox on each row and the bar of the batch actions, with how many are selected; the selection is the page on screen; an action that cannot be taken back asks first, saying how many; the outcome is told as message-placement says, a partial one as error-recovery says", use: ["mds-table selectable", "mds-button slot=batch-action"], see: confirm-action }
+  - { id: show-new-items, changes: by-others, where: "nothing on screen moves by itself: at the end of the line of the summary, how many items are new or changed, the count in an info dot that pulses three times when it grows and the words in the info colour, and Show, which loads the list again with the same query; the line keeps its place while there is nothing new, so the results never move; the count is read out without moving the focus; Show hides once pressed, and the focus goes to the heading of the list", use: ["mds-notification variant=info pulse", "mds-text typography=detail", "mds-button variant=info tone=outline size=sm"] }
+gaps: []
+not-applicable: []
+
+always-true:
+  - id: server-does-the-work
+    rule: The back end searches, counts, sorts and pages the items; the page receives one page of results.
+    checked-by: review
+  - id: query-in-address
+    rule: "Search, filters, order and page are in the address, the defaults left out: a reload, a link or Back shows the same results."
+    checked-by: review
+  - id: filters-reset-page
+    rule: Any change but the page goes back to the first page; a page past the end gives the last one.
+    checked-by: review
+  - id: sort-the-whole-set
+    rule: A list with pages is sorted by the back end, never only the rows on screen.
+    checked-by: review
+  - id: summary-says-how-many
+    rule: The summary says which items are on screen out of how many, and is read out after every change.
+    checked-by: review
+  - id: link-names-the-item
+    rule: Each item is opened by a link that names it, never by an Open repeated on every row.
+    checked-by: review
+  - id: selection-on-screen
+    rule: "A selection holds only items on screen: a new page, filter or search empties it."
+    checked-by: review
+  - id: nothing-moves-by-itself
+    rule: Items added or changed by others never move what is on screen; they wait until the person asks for them.
+    checked-by: review
+  - id: newest-wins
+    from: loading
+  - id: no-flash-empty
+    from: loading
+  - id: not-an-error
+    from: empty-state
+
+open-choices:
+  - { id: page-size, default: "10 items, as the example of the docs site", may: "show more items in a page, the same in every list of the product" }
+  - { id: select-all-matching, default: "none: the selection is the page on screen", may: "offer Select all N that match, for an action the back end runs on the query" }
+
+situations:
+  - { situation: A person opens the list of their requests and searches one by number, case: find-and-open }
+  - { situation: "Back from a request, the list is as it was", case: find-and-open }
+  - { situation: "The documents of a case, in a section of its page", case: find-and-open, note: "under the heading of the section; its query in the address too, with names of its own" }
+  - { situation: Export the requests that match the filters, case: find-and-open, note: "Export acts on the query, from the header of the page; a long export runs in the background (loading)" }
+  - { situation: An operator archives 12 requests at once, case: act-on-many }
+  - { situation: 12 items are deleted for good, case: act-on-many, note: "the dialog says how many (confirm-action)" }
+  - { situation: New requests arrive while an operator works through the queue, case: show-new-items }
+  - { situation: Members are added to a group from the list of users, use: choose-items }
+  - { situation: "A recipient is chosen for a message, in a form", use: form-and-validation }
+---
+
+# List with filters
+
+**The back end finds the items, the address keeps the query, and nothing on screen moves until the person asks.**
+
+## When to use it
+
+People look for items in a set too large to read through: dozens of items or more, with a few
+properties worth filtering on (the requests of an office, the documents of a case, the users of
+an organisation). With a handful of items, show them all: search, filters and pages only get in
+the way. When the items are seen rather than read (images, documents to preview), the results
+are cards in a grid; the search, the filters and the pages stay the same. Not choosing items for
+something else (`choose-items`), not an empty list (`empty-state`), a list that is loading
+(`loading`) or one that failed (`error-recovery`): this pattern sends to them.
+
+## What decides it
+
+Two questions: what the person does with the items (opens one at a time, or acts on several at
+once), and whether other people change the set while it is on screen.
+
+## Cases
+
+<!-- Generated from the frontmatter: edit it there, then run nx run stencil:generate.pattern -- --sync. -->
+
+| Variable | Values | Means |
+| --- | --- | --- |
+| `goal` | `open`, `act` | open: the person opens one item at a time (a request, to work on it); act: the person acts on several items at once (archive, assign, delete) |
+| `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 case that leaves a variable out holds for any of its values.
+
+| Case | When | Where | Use |
+| --- | --- | --- | --- |
+| `find-and-open` | goal: open; changes: no | the title of the list, a search form, the summary, the results and the pages; the name or the number of each item is the link to its page | `mds-input type=search`, `mds-filter`, `mds-input-select`, `mds-table sorting=external`, `mds-table-header-cell sortable sort-key`, `mds-paginator` |
+| `act-on-many` | goal: act; changes: no | a checkbox on each row and the bar of the batch actions, with how many are selected; the selection is the page on screen; an action that cannot be taken back asks first, saying how many; the outcome is told as message-placement says, a partial one as error-recovery says; see `confirm-action` | `mds-table selectable`, `mds-button slot=batch-action` |
+| `show-new-items` | changes: by-others | nothing on screen moves by itself: at the end of the line of the summary, how many items are new or changed, the count in an info dot that pulses three times when it grows and the words in the info colour, and Show, which loads the list again with the same query; the line keeps its place while there is nothing new, so the results never move; the count is read out without moving the focus; Show hides once pressed, and the focus goes to the heading of the list | `mds-notification variant=info pulse`, `mds-text typography=detail`, `mds-button variant=info tone=outline size=sm` |
+
+No gaps: every combination has a case or is not applicable.
+
+## Parts
+
+- **The title** of the list, in the plural, as the heading of the page (`h1`), or of its section.
+  Actions on the whole set (New, Export) sit next to it: the block `page-header`.
+- **The search form**, `role="search"`: a field that searches the number and the name
+  (`mds-input type="search"` in `mds-input-field`), a select for each property with a few values
+  (`mds-input-select`).
+- **The order**: the headers of the columns that can sort (`sortable` and `sort-key` on
+  `mds-table-header-cell`), never a field of the search form.
+- **The status filter**: the statuses as `mds-filter`, one at a time, each with the number of
+  items it would show (`count` on `mds-filter-item`).
+- **The summary**: which items are on screen out of how many ("11-20 of 46 requests"), with
+  Clear filters ("Rimuovi i filtri", the words of `mds-filter`) when there are any;
+  `role="status"`. When nothing matches, Clear filters is only in the panel of `clear-filters`
+  (`empty-state`), not in the summary too.
+- **The results**: one row per item in `mds-table`, its number or name the link to its page; or
+  cards in a grid (`mds-card`) when the items are seen rather than read. What was searched is
+  marked in each result (`loading`, `keep-while-reloading`).
+- **The pages**: `mds-paginator`, only when there is more than one page.
+- The search form, the summary, the results and the pages stand as the block `item-list` lays
+  them out, around the page in the block `app-shell`.
+- When the person acts on several items: `selectable` on `mds-table`, and the actions as
+  `mds-button` in its `batch-action` slot; the bar says how many are selected.
+- When others change the set: at the end of the line of the summary, how many items are new: the
+  count as the `value` of `mds-notification variant="info" pulse`, the words after it in the
+  info colour (`--magma-info-fg`), `gap-inline` between them, then Show (`mds-button
+  variant="info" tone="outline" size="sm"`). The line keeps its place while there is nothing
+  new: Show is hidden (`visibility: hidden`), not removed, the dot is `dismissed`, and on a
+  narrow screen the line sits under the summary from the start, so neither its arrival nor its
+  count moves the results.
+
+## Behaviour over time
+
+- The search waits for a pause in the typing (300 ms); a new query cancels the one still
+  running (`newest-wins`).
+- The results stay while the next ones load: `await` on the search field, `aria-busy` on the
+  table (`no-flash-empty`).
+- Any change of the filters goes back to the first page; the address is replaced, not pushed,
+  so Back leaves the list instead of walking through every filter.
+- The counts of the statuses follow the search and the other filters, so an empty status shows
+  before it is picked.
+- A new page, filter or search empties the selection: an action never reaches items the person
+  cannot see.
+- After an action on several items, the list loads again on the same page, with the same query.
+- Items added or changed by others: the line says how many ("3 new requests"), and its count
+  grows while they come; at each new count the dot pulses three times and stops (3 seconds,
+  under the 5 of WCAG 2.2.2), and not at all when the animation is reduced
+  (`pref-animation-reduce`, or the system with no preference of Magma). Show loads the list
+  again, with the same query, empties the selection and empties the line; Show is gone, so the
+  focus goes to the heading of the list. Nothing moves before that.
+- Nothing matches: the `clear-filters` case of `empty-state`, never an error. The request fails:
+  `retry-content` of `error-recovery`, never "No requests match".
+
+## 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 |
+| --- | --- | --- |
+| `server-does-the-work` | The back end searches, counts, sorts and pages the items; the page receives one page of results. | review |
+| `query-in-address` | Search, filters, order and page are in the address, the defaults left out: a reload, a link or Back shows the same results. | review |
+| `filters-reset-page` | Any change but the page goes back to the first page; a page past the end gives the last one. | review |
+| `sort-the-whole-set` | A list with pages is sorted by the back end, never only the rows on screen. | review |
+| `summary-says-how-many` | The summary says which items are on screen out of how many, and is read out after every change. | review |
+| `link-names-the-item` | Each item is opened by a link that names it, never by an Open repeated on every row. | review |
+| `selection-on-screen` | A selection holds only items on screen: a new page, filter or search empties it. | 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. | review |
+| `newest-wins` | An older answer never replaces a newer one. (from `loading`) | review |
+| `no-flash-empty` | A reload never empties what is on screen. (from `loading`) | review |
+| `not-an-error` | A part that failed to load is an error, never an empty state. (from `empty-state`) | 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 |
+| --- | --- | --- |
+| `page-size` | 10 items, as the example of the docs site | show more items in a page, the same in every list of the product |
+| `select-all-matching` | none: the selection is the page on screen | offer Select all N that match, for an action the back end runs on the query |
+
+## 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 person opens the list of their requests and searches one by number | `find-and-open` |
+| Back from a request, the list is as it was | `find-and-open` |
+| The documents of a case, in a section of its page | `find-and-open`: under the heading of the section; its query in the address too, with names of its own |
+| Export the requests that match the filters | `find-and-open`: Export acts on the query, from the header of the page; a long export runs in the background (loading) |
+| An operator archives 12 requests at once | `act-on-many` |
+| 12 items are deleted for good | `act-on-many`: the dialog says how many (confirm-action) |
+| New requests arrive while an operator works through the queue | `show-new-items` |
+| Members are added to a group from the list of users | not here: `choose-items` |
+| A recipient is chosen for a message, in a form | not here: `form-and-validation` |
+
+## Accessibility
+
+- The search form is a landmark (`role="search"`); every control has a visible label given by
+  `mds-input-field`: the placeholder is an example, not the label.
+- The summary is a status region: after each change screen readers read out which items are
+  shown out of how many, while the focus stays on the control just used.
+- The line of the new items is read out when it appears and when its count changes, without
+  moving the focus: its count sits in a status region that is always on the page (a live region
+  added together with its text is not read reliably); the dot is the count, read with the words
+  after it (an `mds-notification` with no `target` is plain text).
+- The status of each item is the text of its badge, not only its colour.
+- The table keeps its column headers; on a narrow screen it scrolls sideways instead of
+  squeezing the columns.
+
+## Content
+
+- The list is named after what it holds, in the plural: "Requests", not "Request list" or
+  "Search".
+- The label of the search field says what it is; the placeholder says what it searches:
+  "Number or subject".
+- The statuses have the names the page of an item gives them, in the order of the process.
+- Count the results, with the singular for one: "1 request", "11-20 of 46 requests".
+- The line of the new items says how many and of what: "3 new requests", "1 request changed".
+- Dates in the format of the language of the page.
+
+## Magma gaps
+
+- No combobox: a search with facets (many properties, values to search among) waits for it;
+  until then, a select for each property with a few values.
+- `mds-card` has no selection: acting on several items works on rows (`mds-table`) only.
+- The bar of the batch actions of `mds-table` is a column at the end of the table, about 190 px
+  wide, taken from the columns: without `white-space: nowrap` on the cells, words break inside
+  ("Anagraf-e") and `mds-badge` breaks its own label (seen on the render of 2026-10-29).
+- `mds-table` sorts the rows in the DOM by default (`sorting="internal"`): a list with pages
+  must set `sorting="external"`, or a click on a header sorts only the page on screen.
+
+## Decisions
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 2026-10-29 | The back end does the work, the query is in the address, a new filter goes back to the first page, one query at a time, the results stay while the next load, no results is not an error | The draft page of the docs site, `patterns/list-with-filters`, and its example. |
+| 2026-10-29 | Draft with variables; the items added by others and choosing items left as gaps; how far a selection reaches to decide | The sources do not settle them. |
+| 2026-10-29 | A selection holds only the page on screen; a new page, filter or search empties it; Select all N that match is a product's choice (`select-all-matching`) | An action never reaches items the person cannot see; `mds-table` selects the rows it shows. |
+| 2026-10-29 | Items added or changed by others wait behind a line with how many and Show (`show-new-items`) | What the person is about to click never moves; the person decides when the list changes. |
+| 2026-10-31 | The line of the new items sits at the end of the line of the summary, no longer an info `mds-banner` above the results: a dot that pulses three times when the count grows, the count in the info colour, Show `variant="info" tone="outline" size="sm"`; the line keeps its place while empty | The banner pushed the results down by 167 px when it appeared, against the case itself; in the line of the summary nothing moves, on a phone too. A line with no dot was too quiet (vittorio); the pulse stops after three beats (WCAG 2.2.2) and honours a reduced animation. Show is outlined as the action of a toast (`actions/toast`, #1189). Chosen live against the banner and the plain line (#1210). |
+| 2026-10-29 | Choosing items for something else is a pattern of its own, the candidate `choose-items` | The selection lives across searches and ends in a choice, not in work on the items; each pattern stays shorter. |
+| 2026-11-04 | The dot of the new items is `mds-notification variant="info" pulse`, the count its `value`, before the words of the line inside its status region; Show `dismissed` it | Magma carries it since #1216 (PR #1239): the pulse follows `value`, so the dot shows the count, and the count is in the info colour as decided on 2026-10-31; a product never writes the animation itself. It replaces the dot the render of 2026-10-31 drew by hand. |
+| 2026-11-03 | The order is chosen from the headers of the columns, not from the search form; Clear filters is in the summary, but only in the panel when nothing matches; after Show the focus goes to the heading; what was searched is marked in the results | What the previews of the cases showed, confirmed in review round 2 of the previews: https://github.com/magma-design-system/magma/issues/1233 |