@slotted/angular 0.1.0-beta.7 → 0.1.0-beta.9

package/docs/markdown.md

@@ -44,48 +44,48 @@ Excerpt — not a complete module
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `tree` | `MarkdownNode \| null` | — | [slMarkdown] | O documento em mdast; nunca HTML |
-| `size` | `'md' \| 'lg' \| 'xl'` | lg | [slMarkdown] | O degrau de tipo da região, de prose |
-| `flow` | `'tight' \| 'normal' \| 'loose'` | normal | [slMarkdown] | O espaço entre blocos, de prose |
-| `status` | `'ready' \| 'error'` | ready | [slMarkdown] | error troca o documento pela parte error |
-| `loading` | `boolean` | false | [slMarkdown] | Um parágrafo de espera, depois do delay do skeleton |
-| `streaming` | `boolean` | false | [slMarkdown] | aria-busy enquanto a fonte chega |
-| `external` | `'new-tab' \| 'same-tab'` | new-tab | [slMarkdown] | Onde abre um link que sai da aplicação |
-| `headingAnchors` | `boolean` | false | [slMarkdown] | Um permalink em cada título |
-| `headingOffset` | `number` | 0 | [slMarkdown] | Somado ao nível de cada título, até seis |
-| `idPrefix` | `string` |  | [slMarkdown] | Antes de cada id gerado; obrigatório com duas regiões na página |
-| `alerts` | `boolean` | true | [slMarkdown] | Lê > [!NOTE] e os irmãos como alert |
-| `allow` | `string[]` | CommonMark + GFM sem html | [slMarkdown] | Os tipos mdast desenhados |
-| `unwrapDisallowed` | `boolean` | false | [slMarkdown] | Um tipo recusado entrega os filhos ao pai |
-| `transformUrl` | `(url, kind, node) => string \| null` | safeUrl | [slMarkdown] | A política de URL; null recusa |
-| `isExternal` | `(href) => boolean` | isExternalUrl | [slMarkdown] | Se um link sai da aplicação |
-| `messages` | `PartialMessages<MarkdownMessages>` | — | [slMarkdown] | As palavras da família sobre o idioma em vigor, chave a chave |
-| `editableTasks` | `boolean` | false | [slMarkdown] | Liga os checkboxes das tarefas; um output não diz se alguém o ouve |
-| `retryable` | `boolean` | false | [slMarkdown] | Desenha o botão de repetir na parte error |
-| `ng-template[slMarkdownNode]` | `kind \| type` | — | conteúdo | Substitui o elemento de um tipo conhecido, ou desenha um tipo desconhecido; recebe o elemento preparado |
-| `[slMarkdownChildren]` | `MarkdownElement` | — | ng-container | Desenha os filhos de um elemento dentro de um template, sem elemento próprio |
-| `[slMarkdownEmpty]` | `conteúdo projetado` | — | conteúdo | O conteúdo da parte empty |
-| `exportAs` | `slMarkdown` | — | [slMarkdown] | document(): os headings e as notas, com os ids da página |
-| `provideMarkdownDefaults` | `external \| headingAnchors \| alerts \| allow \| transformUrl \| isExternal` | — | Aplicação | Decidido uma vez para todos os documentos por baixo; um input ganha |
-| `prepareMarkdown` | `(tree, options) => MarkdownDocument` | — | @slotted/core/markdown | headings para um índice, com os ids da página |
-| `completeMarkdown` | `(source) => string` | — | @slotted/core/markdown | Fecha uma fonte cortada antes do parser |
-| `fromMarkedTokens` | `(tokens) => MarkdownNode` | — | @slotted/core/markdown | O lexer do marked como mdast |
-| `id, aria-*, data-*` | `atributos nativos` | — | [slMarkdown] | Ficam no elemento do consumidor |
+| `tree` | `MarkdownNode \| null` | — | [slMarkdown] | The document in mdast; never HTML |
+| `size` | `'md' \| 'lg' \| 'xl'` | lg | [slMarkdown] | The region’s type step, from prose |
+| `flow` | `'tight' \| 'normal' \| 'loose'` | normal | [slMarkdown] | The space between blocks, from prose |
+| `status` | `'ready' \| 'error'` | ready | [slMarkdown] | error replaces the document with the error part |
+| `loading` | `boolean` | false | [slMarkdown] | A waiting paragraph, after the skeleton delay |
+| `streaming` | `boolean` | false | [slMarkdown] | aria-busy while the source arrives |
+| `external` | `'new-tab' \| 'same-tab'` | new-tab | [slMarkdown] | Where a link that leaves the application opens |
+| `headingAnchors` | `boolean` | false | [slMarkdown] | A permalink on every heading |
+| `headingOffset` | `number` | 0 | [slMarkdown] | Added to the level of each heading, up to six |
+| `idPrefix` | `string` |  | [slMarkdown] | Before each generated id; required with two regions on the page |
+| `alerts` | `boolean` | true | [slMarkdown] | Reads > [!NOTE] and its siblings as alert |
+| `allow` | `string[]` | CommonMark + GFM without html | [slMarkdown] | The mdast types drawn |
+| `unwrapDisallowed` | `boolean` | false | [slMarkdown] | A refused type hands its children to the parent |
+| `transformUrl` | `(url, kind, node) => string \| null` | safeUrl | [slMarkdown] | The URL policy; null refuses |
+| `isExternal` | `(href) => boolean` | isExternalUrl | [slMarkdown] | Whether a link leaves the application |
+| `messages` | `PartialMessages<MarkdownMessages>` | — | [slMarkdown] | The family’s words over the current locale, key by key |
+| `editableTasks` | `boolean` | false | [slMarkdown] | Turns on the task checkboxes; an output does not say whether anyone listens to it |
+| `retryable` | `boolean` | false | [slMarkdown] | Draws the retry button in the error part |
+| `ng-template[slMarkdownNode]` | `kind \| type` | — | content | Replaces the element of a known type, or draws an unknown type; receives the prepared element |
+| `[slMarkdownChildren]` | `MarkdownElement` | — | ng-container | Draws the children of an element inside a template, without an element of its own |
+| `[slMarkdownEmpty]` | `projected content` | — | content | The content of the empty part |
+| `exportAs` | `slMarkdown` | — | [slMarkdown] | document(): the headings and the notes, with the page’s ids |
+| `provideMarkdownDefaults` | `external \| headingAnchors \| alerts \| allow \| transformUrl \| isExternal` | — | Application | Decided once for every document below; an input wins |
+| `prepareMarkdown` | `(tree, options) => MarkdownDocument` | — | @slotted/core/markdown | headings for a table of contents, with the page’s ids |
+| `completeMarkdown` | `(source) => string` | — | @slotted/core/markdown | Closes a cut source before the parser |
+| `fromMarkedTokens` | `(tokens) => MarkdownNode` | — | @slotted/core/markdown | The marked lexer as mdast |
+| `id, aria-*, data-*` | `native attributes` | — | [slMarkdown] | Stay on the consumer’s element |
 
 ## Events
 
 | Name | Payload | When |
 | --- | --- | --- |
-| `taskChange` | `{ index, checked, offset, request }` | Quando o leitor marca ou desmarca uma tarefa com editableTasks ligado, com a razão pointer ou keyboard em request. A caixa não se move: a árvore nova do consumidor é que a move. |
-| `retry` | `'pointer' \| 'keyboard'` | Quando o leitor pressiona o botão de repetir da parte error, desenhado com retryable. |
+| `taskChange` | `{ index, checked, offset, request }` | When the reader checks or unchecks a task with editableTasks on, with the reason pointer or keyboard in request. The box does not move: the consumer’s new tree moves it. |
+| `retry` | `'pointer' \| 'keyboard'` | When the reader presses the retry button of the error part, drawn with retryable. |
 
 ## Rules
 
-- Nenhuma string da fonte chega a innerHTML: a família recebe uma árvore, recusa HTML cru e esquemas executáveis por omissão, e cada elemento é criado pelo framework.
-- Os títulos são títulos de verdade, deslocáveis com headingOffset para caberem no esboço da página; a âncora fica na ordem de tabulação e na árvore de acessibilidade, com o nome "Link to section: <título>".
-- Uma tarefa é um checkbox nomeado pelo texto do item; sem editableTasks é aria-readonly, não disabled, por isso continua focável e legível.
-- Cada referência de nota tem aria-describedby para o título escondido da secção, e cada retorno diz para qual referência volta; um alerta do GitHub é live="off", porque é conteúdo e não um evento.
-- streaming e loading põem aria-busy na raiz, e o skeleton faz um único anúncio educado; nada move o foco quando o conteúdo chega.
+- No source string reaches innerHTML: the family receives a tree, refuses raw HTML and executable schemes by default, and each element is created by the framework.
+- The headings are real headings, shiftable with headingOffset to fit the page outline; the anchor stays in the tab order and in the accessibility tree, with the name "Link to section: <heading>".
+- A task is a checkbox named by the item’s text; without editableTasks it is aria-readonly, not disabled, so it stays focusable and readable.
+- Each note reference has aria-describedby pointing to the hidden heading of the section, and each return says which reference it goes back to; a GitHub alert is live="off", because it is content and not an event.
+- streaming and loading put aria-busy on the root, and the skeleton makes a single polite announcement; nothing moves focus when the content arrives.
 
 ## Tokens
 
@@ -93,9 +93,9 @@ Excerpt — not a complete module
 
 ## Examples
 
-### Um documento inteiro
+### A whole document
 
-Títulos com id estável, ênfase, código em linha, listas aninhadas, uma citação e uma régua: tudo em prose, cuja tipografia é a da região. Passe o ponteiro por um título para ver a âncora; com Tab ela aparece também.
+Headings with a stable id, emphasis, inline code, nested lists, a quote and a rule: all in prose, whose typography is the region’s. Hover a heading to see the anchor; with Tab it appears too.
 
 Excerpt — not a complete module
 
@@ -103,21 +103,21 @@ Excerpt — not a complete module
 <div slMarkdown headingAnchors [tree]="tree"></div>
 ```
 
-### Tabelas do GFM
+### GFM tables
 
-O alinhamento :-- e --: chega como start e end, por isso uma tabela vista em RTL mantém os preços contra a aresta onde a leitura termina. Uma tabela mais larga do que a coluna rola dentro da parte scroll de prose, que só ganha tabindex e nome enquanto transborda.
+The :-- and --: alignment arrives as start and end, so a table seen in RTL keeps the prices against the edge where reading ends. A table wider than the column scrolls inside the prose scroll part, which only gains tabindex and a name while it overflows.
 
 Excerpt — not a complete module
 
 ```markdown
-| Plano | Lugares |   Preço |
-| :---- | :-----: | ------: |
-| Team  |   10    | $120.00 |
+| Plan | Seats |   Price |
+| :--- | :---: | ------: |
+| Team |  10   | $120.00 |
 ```
 
-### Cercas com code-block
+### Fences with code-block
 
-Cada cerca é um CodeBlock: a linguagem da info string, e o que vem depois dela — title="…", {2} e showLineNumbers — chega como título, linha realçada e números. O realce de sintaxe é o do CodeBlockDefaultsProvider.
+Each fence is a CodeBlock: the language from the info string, and what comes after it — title="…", {2} and showLineNumbers — arrives as title, highlighted line and numbers. The syntax highlighting is that of the CodeBlockDefaultsProvider.
 
 Excerpt — not a complete module
 
@@ -128,9 +128,9 @@ await deploy({ env: 'production' });
 ```
 ````
 
-### Listas de tarefas
+### Task lists
 
-Sem editableTasks as caixas são checkbox em readOnly: focáveis, anunciadas como só de leitura. Com ele, marcar uma tarefa pede a mudança com o índice e o offset na fonte; a caixa só se move quando a árvore nova chega.
+Without editableTasks the boxes are checkboxes in readOnly: focusable, announced as read only. With it, checking a task requests the change with the index and the offset in the source; the box only moves when the new tree arrives.
 
 Excerpt — not a complete module
 
@@ -143,9 +143,9 @@ Excerpt — not a complete module
 ></div>
 ```
 
-### Alertas do GitHub
+### GitHub alerts
 
-> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] e [!CAUTION] tornam-se alert em reach="section" e live="off" — conteúdo, não anúncio — nos tons accent, success, secondary, warning e danger. alerts={false} devolve a citação.
+> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] and [!CAUTION] become an alert with reach="section" and live="off" — content, not an announcement — in the tones accent, success, secondary, warning and danger. alerts={false} gives back the quote.
 
 Excerpt — not a complete module
 
@@ -154,9 +154,9 @@ Excerpt — not a complete module
 > A deployment during a migration waits for the migration to finish.
 ```
 
-### Notas de rodapé
+### Footnotes
 
-Numeradas pela primeira referência, com uma seta de retorno por referência dentro do último parágrafo da nota. A secção tem um título escondido que dá nome ao conjunto; uma definição que ninguém referencia não é desenhada, como no GitHub.
+Numbered by the first reference, with one return arrow per reference inside the last paragraph of the note. The section has a hidden heading that names the set; a definition nobody references is not drawn, as on GitHub.
 
 Excerpt — not a complete module
 
@@ -164,9 +164,9 @@ Excerpt — not a complete module
 <div slMarkdown [messages]="{ footnotes: 'Notas' }" [tree]="tree"></div>
 ```
 
-### Links internos e externos
+### Internal and external links
 
-Um endereço absoluto http(s) sai da aplicação: é um Link com o glifo e a dica de nova aba. Um caminho relativo é um a simples. external="same-tab" mantém a aba; isExternal decide quais hosts são da casa.
+An absolute http(s) address leaves the application: it is a Link with the glyph and the new-tab hint. A relative path is a plain a. external="same-tab" keeps the tab; isExternal decides which hosts belong to the application.
 
 Excerpt — not a complete module
 
@@ -174,9 +174,9 @@ Excerpt — not a complete module
 <div slMarkdown [isExternal]="isOwnDomainInternal" [tree]="tree"></div>
 ```
 
-### Sanitização por construção
+### Sanitization by construction
 
-A família nunca escreve innerHTML. HTML cru não é desenhado; javascript:, data: e as grafias disfarçadas perdem o link e ficam como texto; uma imagem recusada fica como o seu texto alternativo. transformUrl troca a política; allow restringe os tipos.
+The family never writes innerHTML. Raw HTML is not drawn; javascript:, data: and the disguised spellings lose the link and stay as text; a refused image stays as its alternative text. transformUrl swaps the policy; allow restricts the types.
 
 Excerpt — not a complete module
 
@@ -189,9 +189,9 @@ Excerpt — not a complete module
 ></div>
 ```
 
-### Renderizadores e extensões
+### Renderers and extensions
 
-ng-template[slMarkdownNode] com o nome de um tipo conhecido substitui o seu elemento — aqui o link vira o routerLink da aplicação — e slMarkdownChildren desenha os filhos no lugar. Com o nome de um tipo desconhecido, desenha esse tipo: aqui uma menção a uma pessoa, que um passo sobre a árvore criou. Um tipo sem renderizador não aparece.
+ng-template[slMarkdownNode] with the name of a known type replaces its element — here the link becomes the application’s routerLink — and slMarkdownChildren draws the children in place. With the name of an unknown type, it draws that type: here a mention of a person, which a pass over the tree created. A type without a renderer does not appear.
 
 Excerpt — not a complete module
 
@@ -206,9 +206,9 @@ Excerpt — not a complete module
 </div>
 ```
 
-### Uma resposta que ainda está a chegar
+### An answer that is still arriving
 
-completeMarkdown fecha o que o fluxo deixou aberto — a cerca, o **, a crase, o link cortado — antes do parser. Os blocos já desenhados mantêm a chave e não voltam a montar; streaming põe aria-busy na região até ao fim.
+completeMarkdown closes what the stream left open — the fence, the **, the backtick, the cut link — before the parser. The blocks already drawn keep their key and do not mount again; streaming puts aria-busy on the region until the end.
 
 Excerpt — not a complete module
 
@@ -221,9 +221,9 @@ Excerpt — not a complete module
 ></div>
 ```
 
-### Carregando, vazio e erro
+### Loading, empty and error
 
-loading desenha um parágrafo de três linhas depois do delay do skeleton, na tipografia da região; vazio escreve messages.empty ou o conteúdo projetado em slMarkdownEmpty; status="error" troca o documento por uma mensagem e, com retryable, um botão que emite retry.
+loading draws a three-line paragraph after the skeleton delay, in the region’s typography; empty writes messages.empty or the content projected in slMarkdownEmpty; status="error" replaces the document with a message and, with retryable, a button that emits retry.
 
 Excerpt — not a complete module
 
@@ -236,18 +236,18 @@ Excerpt — not a complete module
   [tree]="tree()"
   (retry)="reload()"
 >
-  <span slMarkdownEmpty>Este serviço ainda não tem runbook.</span>
+  <span slMarkdownEmpty>This service has no runbook yet.</span>
 </div>
 ```
 
-### Numa página de documentação
+### On a documentation page
 
-slContainer dá a medida, prepareMarkdown dá o índice com os mesmos ids que a página desenha — e exportAs dá o mesmo document() a partir do template —, e provideMarkdownDefaults diz uma vez, em português, o que a família escreve.
+slContainer gives the measure, prepareMarkdown gives the table of contents with the same ids the page draws — and exportAs gives the same document() from the template —, and provideMarkdownDefaults says once, in Portuguese, what the family writes.
 
 Excerpt — not a complete module
 
 ```html
-<nav aria-label="Nesta página">
+<nav aria-label="On this page">
   @for (heading of outline.headings; track heading.id) {
     <a [href]="'#' + heading.id">{{ heading.text }}</a>
   }
@@ -255,9 +255,9 @@ Excerpt — not a complete module
 <div slContainer size="measure"><div slMarkdown headingAnchors [tree]="tree"></div></div>
 ```
 
-### Teclado e leitor de ecrã
+### Keyboard and screen reader
 
-Tab percorre as âncoras dos títulos, os links, uma tabela que rola, os controlos de um bloco de código, as tarefas editáveis e os retornos das notas. A família não acrescenta tecla nenhuma: cada parada é de uma família composta.
+Tab goes through the heading anchors, the links, a table that scrolls, the controls of a code block, the editable tasks and the footnote returns. The family adds no key: each stop belongs to a composed family.
 
 Excerpt — not a complete module
 

package/docs/page-header.json

@@ -95,7 +95,7 @@
           "part": "root",
           "element": "the header carrying slPageHeader",
           "required": true,
-          "purpose": "The family: sticky with a negative offset the size of the header area, carrying data-ui=\"page-header\", the four axes, data-expanded, data-revealed, data-loading and the measured facts data-scrolled, data-stuck and data-compact. Below 600 pixels of its own width it carries data-compact, is not sticky and scrolls away with the page. It is its own container, so the rows reflow on its own inline size."
+          "purpose": "The family: sticky with a negative offset the size of the header area, carrying data-ui=\"page-header\", the four axes, data-expanded, data-revealed, data-loading and the measured facts data-scrolled, data-stuck and data-compact. In a frame narrower than 600 pixels — a phone — it carries data-compact, is not sticky and scrolls away with the page. It is its own container, so the rows reflow on its own inline size."
         },
         {
           "part": "title-area",

package/docs/skills/compose-screen/SKILL.md

@@ -8,7 +8,17 @@ description: Use when writing or changing a screen of an application built with
 A screen is composed from the families' own parts first. An element of the
 screen's own exists only where no family names a place for it.
 
-## 1. Classify the screen
+## 1. Name the domain values
+
+Name the values the product is about on this screen — money, a period, a day,
+an account, a person — and the task the reader performs with each: enter it in
+one motion, step it, compare it. For each, write which family accepts the
+value and whether that family performs the task in one step with the value's
+own words. When it does not, CP-04 applies before any family is chosen: a
+family that technically accepts a value does not answer the reader's task by
+that fact.
+
+## 2. Classify the screen
 
 | The screen                                            | Topic              |
 | ----------------------------------------------------- | ------------------ |
@@ -26,28 +36,28 @@ screen's own exists only where no family names a place for it.
 A screen can be two of these: a record with an edit form in place reads both
 topics.
 
-## 2. Read
+## 3. Read
 
 1. `../../guidelines/index.md`.
 2. `../../guidelines/composition.md`, always.
-3. The topic of step 1. Add `layout-alignment.md` and `shell-composition.md`
+3. The topic of step 2. Add `layout-alignment.md` and `shell-composition.md`
    when the screen places controls in a row or in the application frame.
 4. Add `errors-and-conflicts.md` and `reading-permissions.md` when the screen
    writes data or reads under a role.
 5. When the screen writes an element of its own, follow
    `../../skills/build-own-element/SKILL.md`.
 
-## 3. Read each family before writing beside it
+## 4. Read each family before writing beside it
 
 For each family the screen uses, read `../../<family>.md` — its anatomy,
 its slots, its axes (CP-01). When the family names a slot for an element, the
 element stands in that slot.
 
-## 4. Compose
+## 5. Compose
 
-- The page's width follows its type: a list is `bleed` with `fill`; a record,
-  a dashboard and an overview keep `wide`; a create or edit form is `content`;
-  preferences read as prose are `measure` (CP-07).
+- Every destination of the navigation is `full`, and a list adds `fill`; a
+  create or edit form is `wide`; preferences read as prose are `measure`
+  (CP-10).
 - Siblings of the screen's own stand in `inline` (one row) or `stack` (one
   column) with a gap from the space scale; text of the screen's own takes its
   size from the `typography` family's `text` member (CP-02).
@@ -67,12 +77,12 @@ element stands in that slot.
   own instead of bending a family into a shape it does not have (CP-04). That
   element is built with `../../skills/build-own-element/SKILL.md`.
 
-## 5. Waits
+## 6. Waits
 
 Every region filled by a request and every control that starts one follow
 `../../skills/waiting-states/SKILL.md`.
 
-## 6. Done
+## 7. Done
 
 1. Each `MUST` rule of the topics read: its `Check` passes.
 2. Each `SHOULD` rule not followed is listed with its reason.
@@ -81,3 +91,5 @@ Every region filled by a request and every control that starts one follow
 4. In a browser with the CPU throttled 4×, each control that switches a region
    paints its new state in the next frame, with no long task between the input
    and that paint.
+5. For each value named in step 1, the control that edits it was chosen
+   against the task, and the reason is written beside it.

package/docs/skills/review-screen/SKILL.md

@@ -43,6 +43,12 @@ Each search below finds a defect without running the screen.
 | A grid or flex track around a family that scrolls, with no zero minimum                                                  | the page scrolls, not the family                         | CP-03        |
 | A badge, a tag or a colour beside a family that already draws the same state                                             | a state stated twice                                     | CP-06        |
 | An element of the screen's own that takes focus with no ring in its `focus-visible` state                                | focus not drawn                                          | OE-03        |
+| A `data-grid` or `table` with no `variant` on a page whose `width` is not `bleed`                                        | a grid with no frame on the page's surface               | LP-15        |
+| A list page's `page-header` with a heading and no subheading, no figures and no solid primary action                     | a header that does not say what the list covers          | LP-16        |
+| A grid whose column state unpins its `actions` column                                                                    | the row's actions leave the frame                        | LP-17        |
+| A row of `stat-card`s where a label has more than three words, or one card has a comparison the others lack              | a row of cards with no shared structure                  | OV-06        |
+| Two destinations of the navigation whose `page`s state different `width`s                                                | the column's edges move between destinations             | CP-10        |
+| A write whose success handler refreshes only the region of the control that wrote                                        | figures elsewhere stay stale after the write             | AF-08        |
 
 A rule whose `Check` needs the screen running — a size class, a throttled
 network, the accessibility tree — is run when the environment can run it, and

package/docs/skills/waiting-states/SKILL.md

@@ -136,4 +136,7 @@ animating behind a message.
       untouched.
 - [ ] Reduced motion stops the animation and keeps the shape.
 - [ ] Empty, no results and error are distinct states, each with its next step.
-- [ ] Each `Check` of AF-01 to AF-07 passes.
+- [ ] For each control that writes, the regions on any screen whose figures
+      the write changes are listed, and each is shown read again after the
+      write (AF-08).
+- [ ] Each `Check` of AF-01 to AF-08 passes.

package/docs/tags-input.json

@@ -130,7 +130,9 @@
         "message",
         "counter",
         "clear",
-        "hint"
+        "hint",
+        "suggestions",
+        "suggestion"
       ]
     }
   },
@@ -195,6 +197,18 @@
           "element": "span, visually hidden",
           "required": true,
           "purpose": "What the row answers to, for a reader who cannot see the remove buttons: Delete removes a value, and — while editable — Enter edits it. The row names it as its description."
+        },
+        {
+          "part": "suggestions",
+          "element": "div[role=\"listbox\"]",
+          "required": false,
+          "purpose": "With suggestions, the list under the frame of the ones the typed text matches, minus the values already chosen. Rendered only while open; the input controls it and names its highlighted option by aria-activedescendant."
+        },
+        {
+          "part": "suggestion",
+          "element": "div[role=\"option\"]",
+          "required": false,
+          "purpose": "One suggestion. data-highlighted and aria-selected on the one Enter adds; a press adds it and keeps focus in the input."
         }
       ],
       "api": [
@@ -254,6 +268,13 @@
           "appliesTo": "sl-tags-input",
           "description": "How a paste is split. The default splits on the delimiters and on every line break."
         },
+        {
+          "name": "suggestions",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "sl-tags-input",
+          "description": "Values the reader may choose instead of typing them whole. The input becomes a combobox: the typed text filters them by the locale’s collator, ArrowDown and ArrowUp move through them, Enter adds the highlighted one. A chosen suggestion is normalized, judged, deduplicated and capped like typed text, and typed text still commits."
+        },
         {
           "name": "formatLabel",
           "type": "(value: string) => string",
@@ -524,6 +545,7 @@
   },
   "tokens": [
     "--slotted-border-subtle",
+    "--slotted-border-width-thin",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
     "--slotted-control-font-family",
@@ -562,9 +584,12 @@
     "--slotted-font-size-xs",
     "--slotted-font-weight-medium",
     "--slotted-line-height-sm",
+    "--slotted-radius-lg",
     "--slotted-radius-none",
+    "--slotted-shadow-md",
     "--slotted-space-1",
     "--slotted-space-2",
+    "--slotted-surface-raised",
     "--slotted-surface-sunken",
     "--slotted-tags-input-action-active-background",
     "--slotted-tags-input-action-color",
@@ -604,7 +629,8 @@
     "--slotted-tone-accent-text",
     "--slotted-tone-danger-border",
     "--slotted-tone-secondary-subtle-active",
-    "--slotted-tone-secondary-subtle-hover"
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-z-index-popover"
   ],
   "examples": [
     {

package/docs/tags-input.md

@@ -37,6 +37,8 @@ Excerpt — not a complete module
 | `counter` | span | no |
 | `clear` | button | no |
 | `hint` | span, visually hidden | yes |
+| `suggestions` | div[role="listbox"] | no |
+| `suggestion` | div[role="option"] | no |
 
 ## Props
 
@@ -50,6 +52,7 @@ Excerpt — not a complete module
 | `invalidValues` | `'keep' \| 'refuse'` | keep | sl-tags-input | What becomes of a value that fails: a chip in the danger tone with its reason, or a report through valueRefuse. |
 | `normalize` | `(text: string) => string` | — | sl-tags-input | Runs before a value is judged. Trim by default. |
 | `split` | `(text: string) => readonly string[]` | — | sl-tags-input | How a paste is split. The default splits on the delimiters and on every line break. |
+| `suggestions` | `readonly string[]` | — | sl-tags-input | Values the reader may choose instead of typing them whole. The input becomes a combobox: the typed text filters them by the locale’s collator, ArrowDown and ArrowUp move through them, Enter adds the highlighted one. A chosen suggestion is normalized, judged, deduplicated and capped like typed text, and typed text still commits. |
 | `formatLabel` | `(value: string) => string` | — | sl-tags-input | The chip’s text for a value. |
 | `lockedValues` | `readonly string[]` | — | sl-tags-input | The values the reader may not remove. |
 | `pattern` | `string` | — | sl-tags-input | The input’s own pattern, applied to each value. |
@@ -124,7 +127,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-sm`, `--slotted-radius-none`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-tags-input-action-active-background`, `--slotted-tags-input-action-color`, `--slotted-tags-input-action-hover-background`, `--slotted-tags-input-action-size`, `--slotted-tags-input-autofill-background`, `--slotted-tags-input-background`, `--slotted-tags-input-border-color`, `--slotted-tags-input-color`, `--slotted-tags-input-counter-color`, `--slotted-tags-input-counter-complete-color`, `--slotted-tags-input-current-border-color`, `--slotted-tags-input-disabled-background`, `--slotted-tags-input-disabled-border-color`, `--slotted-tags-input-disabled-color`, `--slotted-tags-input-field-basis`, `--slotted-tags-input-field-min`, `--slotted-tags-input-hover-border-color`, `--slotted-tags-input-icon-size-min`, `--slotted-tags-input-invalid-border-color`, `--slotted-tags-input-invalid-edge-width`, `--slotted-tags-input-invalid-focus-ring-color`, `--slotted-tags-input-placeholder-color`, `--slotted-tags-input-plain-hover-background`, `--slotted-tags-input-radius`, `--slotted-tags-input-readonly-background`, `--slotted-tags-input-shadow`, `--slotted-tags-input-subtle-background`, `--slotted-tags-input-subtle-border-color`, `--slotted-tags-input-subtle-hover-background`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-tags-input-action-active-background`, `--slotted-tags-input-action-color`, `--slotted-tags-input-action-hover-background`, `--slotted-tags-input-action-size`, `--slotted-tags-input-autofill-background`, `--slotted-tags-input-background`, `--slotted-tags-input-border-color`, `--slotted-tags-input-color`, `--slotted-tags-input-counter-color`, `--slotted-tags-input-counter-complete-color`, `--slotted-tags-input-current-border-color`, `--slotted-tags-input-disabled-background`, `--slotted-tags-input-disabled-border-color`, `--slotted-tags-input-disabled-color`, `--slotted-tags-input-field-basis`, `--slotted-tags-input-field-min`, `--slotted-tags-input-hover-border-color`, `--slotted-tags-input-icon-size-min`, `--slotted-tags-input-invalid-border-color`, `--slotted-tags-input-invalid-edge-width`, `--slotted-tags-input-invalid-focus-ring-color`, `--slotted-tags-input-placeholder-color`, `--slotted-tags-input-plain-hover-background`, `--slotted-tags-input-radius`, `--slotted-tags-input-readonly-background`, `--slotted-tags-input-shadow`, `--slotted-tags-input-subtle-background`, `--slotted-tags-input-subtle-border-color`, `--slotted-tags-input-subtle-hover-background`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
 
 ## Examples