@slotted/react 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/docs/filter-bar.md

@@ -68,49 +68,49 @@ Excerpt — not a complete module
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `fields` | `FilterBarField[]` | — | FilterBar | Os campos filtráveis: key, label, kind, icon (nome de glifo ou nó), operators, pinned, required, defaultValue, section, options, searchable |
-| `value` | `FilterGroup \| null` | — | FilterBar | A árvore que o consumidor possui. Presente é controlado, para a vida da barra |
-| `defaultValue` | `FilterGroup \| null` | — | FilterBar | Onde uma barra não controlada começa, lida uma vez |
-| `query` | `string` | — | FilterBar | A busca global, controlada |
-| `defaultQuery` | `string` |  | FilterBar | A busca com que uma barra não controlada começa |
-| `presets` | `FilterBarPreset[]` | — | FilterBar | As vistas guardadas: key, label, value |
-| `preset` | `string \| null` | — | FilterBar | A vista corrente, controlada |
-| `defaultPreset` | `string \| null` | null | FilterBar | A vista com que começa |
-| `open` | `boolean` | — | FilterBar | Se o construtor está aberto, controlado |
-| `defaultOpen` | `boolean` | false | FilterBar | Se começa aberto |
-| `revealed` | `boolean` | — | FilterBar | Se os chips dobrados estão à vista, controlado |
-| `defaultRevealed` | `boolean` | false | FilterBar | Se começam à vista |
-| `apply` | `'live' \| 'manual'` | live | FilterBar | Pede a cada edição, ou edita um rascunho até Apply |
-| `sticky` | `boolean` | false | FilterBar | Cola sob o cabeçalho da página e soma a sua altura ao que segue |
-| `container` | `Element \| null` | — | FilterBar | Um pai só para o drawer do construtor, em vez da raiz de portal partilhada |
-| `size` | `'sm' \| 'md' \| 'lg'` | md | FilterBar | O passo dos controles |
-| `queryDelay` | `number` | 320 | FilterBar | Milissegundos que a busca e um operando de texto esperam sob live |
-| `chipLimit` | `number` | 6 | FilterBar | Chips à vista antes de dobrar |
-| `shortcut` | `string \| null` | null | FilterBar | A tecla do documento que foca a busca, fora de um campo editável |
-| `disabled` | `boolean` | false | FilterBar | Desliga todos os controles |
-| `readOnly` | `boolean` | false | FilterBar | Cada condição alcançável e legível, nenhuma alterável: sem X, add, clear nem pills vazios |
-| `loading` | `boolean` | false | FilterBar | Mantém a largura, desliga Apply, spinner no lugar da contagem |
-| `count` | `number` | — | FilterBar | Quantas linhas o filtro manteve |
-| `total` | `number` | — | FilterBar | Quantas há |
-| `messages` | `Partial<FilterBarMessages>` | — | FilterBar | Palavras sobre as da língua em vigor, chave a chave: o nome do landmark (bar), os controles, os nomes dos chips, a contagem e os anúncios |
-| `renderOperand` | `(props: FilterBarOperandProps) => ReactNode` | — | FilterBar | Substitui o controle do operando; undefined mantém o da espécie |
-| `children` | `ReactNode` | — | FilterBar | Os controles do consumidor no slot end |
-| `renderOperand` | `(props) => ReactNode` | — | FilterBar | A costura que a rodada 12 usa em table: date-range-picker num between, tags-input num conjunto grande |
-| `children` | `ReactNode` | — | FilterBar | O slot end: uma ordenação, um seletor de colunas, fora do anel da toolbar |
-| `ref` | `Ref<FilterBarHandle>` | — | FilterBar | focusSearch(), open(), root — as ações que uma prop não exprime |
-| `FilterBarDefaultsProvider` | `apply \| chipLimit \| queryDelay \| shortcut \| size` | — | Aplicação | Decide uma vez para tudo por baixo; uma prop na barra ganha |
-| `onKeyDown, id, aria-*, data-*` | `props nativas` | — | FilterBar | Chegam à raiz; o handler do consumidor corre antes do da família |
+| `fields` | `FilterBarField[]` | — | FilterBar | The filterable fields: key, label, kind, icon (glyph name or node), operators, pinned, required, defaultValue, section, options, searchable |
+| `value` | `FilterGroup \| null` | — | FilterBar | The tree the consumer owns. Present means controlled, for the life of the bar |
+| `defaultValue` | `FilterGroup \| null` | — | FilterBar | Where an uncontrolled bar starts, read once |
+| `query` | `string` | — | FilterBar | The global search, controlled |
+| `defaultQuery` | `string` |  | FilterBar | The search an uncontrolled bar starts with |
+| `presets` | `FilterBarPreset[]` | — | FilterBar | The saved views: key, label, value |
+| `preset` | `string \| null` | — | FilterBar | The current view, controlled |
+| `defaultPreset` | `string \| null` | null | FilterBar | The view it starts with |
+| `open` | `boolean` | — | FilterBar | Whether the builder is open, controlled |
+| `defaultOpen` | `boolean` | false | FilterBar | Whether it starts open |
+| `revealed` | `boolean` | — | FilterBar | Whether the folded chips are in view, controlled |
+| `defaultRevealed` | `boolean` | false | FilterBar | Whether they start in view |
+| `apply` | `'live' \| 'manual'` | live | FilterBar | Requests on every edit, or edits a draft until Apply |
+| `sticky` | `boolean` | false | FilterBar | Sticks under the page header and adds its height to what follows |
+| `container` | `Element \| null` | — | FilterBar | A parent for the builder drawer only, instead of the shared portal root |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | FilterBar | The step of the controls |
+| `queryDelay` | `number` | 320 | FilterBar | Milliseconds the search and a text operand wait under live |
+| `chipLimit` | `number` | 6 | FilterBar | Chips in view before folding |
+| `shortcut` | `string \| null` | null | FilterBar | The document key that focuses the search, outside an editable field |
+| `disabled` | `boolean` | false | FilterBar | Turns off every control |
+| `readOnly` | `boolean` | false | FilterBar | Every condition reachable and readable, none changeable: no X, add, clear or empty pills |
+| `loading` | `boolean` | false | FilterBar | Keeps the width, turns off Apply, spinner in place of the count |
+| `count` | `number` | — | FilterBar | How many rows the filter kept |
+| `total` | `number` | — | FilterBar | How many there are |
+| `messages` | `Partial<FilterBarMessages>` | — | FilterBar | Words over those of the current locale, key by key: the landmark name (bar), the controls, the chip names, the count and the announcements |
+| `renderOperand` | `(props: FilterBarOperandProps) => ReactNode` | — | FilterBar | Replaces the operand control; undefined keeps the one for the kind |
+| `children` | `ReactNode` | — | FilterBar | The consumer’s controls in the end slot |
+| `renderOperand` | `(props) => ReactNode` | — | FilterBar | The seam table uses: date-range-picker on a between, tags-input on a large set |
+| `children` | `ReactNode` | — | FilterBar | The end slot: a sort, a column picker, outside the toolbar ring |
+| `ref` | `Ref<FilterBarHandle>` | — | FilterBar | focusSearch(), open(), root — the actions a prop does not express |
+| `FilterBarDefaultsProvider` | `apply \| chipLimit \| queryDelay \| shortcut \| size` | — | Application | Decides once for everything below; a prop on the bar wins |
+| `onKeyDown, id, aria-*, data-*` | `native props` | — | FilterBar | Reach the root; the consumer’s handler runs before the family’s |
 
 ## Events
 
 | Name | Payload | When |
 | --- | --- | --- |
-| `onValueChange` | `(value: FilterGroup \| null, request)` | Antes de a árvore mover. A razão é pointer, keyboard, clear, remove, select, submit ou programmatic; cancelar não move nada. A árvore chega normalizada: sem regras incompletas, null quando nada resta. |
-| `onQueryChange` | `(query: string, request)` | Depois de queryDelay sob live, ou com submit sob manual; clear quando Escape ou o X do campo a limpam. |
-| `onPresetChange` | `(preset: string \| null, request)` | Quando uma vista é escolhida no select, com select; clear quando o select é esvaziado. |
-| `onPresetSave` | `(value: FilterGroup \| null)` | Quando o leitor pressiona "Save as view…" no construtor. A família não guarda: pergunta. |
-| `onOpenChange` | `(open: boolean, request)` | Antes de o construtor abrir ou fechar: pointer, keyboard, escape, outsidePress, dismiss, submit, programmatic. |
-| `onRevealedChange` | `(revealed: boolean, request)` | Antes de os chips dobrados aparecerem ou voltarem a dobrar. |
+| `onValueChange` | `(value: FilterGroup \| null, request)` | Before the tree moves. The reason is pointer, keyboard, clear, remove, select, submit or programmatic; cancelling moves nothing. The tree arrives normalized: no incomplete rules, null when nothing is left. |
+| `onQueryChange` | `(query: string, request)` | After queryDelay under live, or with submit under manual; clear when Escape or the field’s X clears it. |
+| `onPresetChange` | `(preset: string \| null, request)` | When a view is chosen in the select, with select; clear when the select is emptied. |
+| `onPresetSave` | `(value: FilterGroup \| null)` | When the reader presses "Save as view…" in the builder. The family does not save: it asks. |
+| `onOpenChange` | `(open: boolean, request)` | Before the builder opens or closes: pointer, keyboard, escape, outsidePress, dismiss, submit, programmatic. |
+| `onRevealedChange` | `(revealed: boolean, request)` | Before the folded chips appear or fold again. |
 
 ## Axes and defaults
 
@@ -122,12 +122,12 @@ Excerpt — not a complete module
 
 ## Rules
 
-- A raiz é role="search", não role="toolbar": o padrão Toolbar do APG pede que uma toolbar evite controles que precisam das setas, e o campo de busca é um. A busca é a primeira parada de tabulação e a toolbar a segunda — duas paradas sejam quantos forem os campos; a nota do APG para toolbars de várias linhas deixa as setas passar de linha em linha.
-- Um chip é role="group" com o nome "<campo>: <frase>", a mesma frase que describeFilter dá ao anúncio de table, e ", incomplete" enquanto falta o valor. O operador tem aria-haspopup="menu", o valor aria-haspopup="dialog" e o nome com a lista inteira, o X "Remove <campo>". Delete e Backspace em qualquer segmento removem com a razão remove e o foco vai ao segmento do mesmo papel no chip seguinte, ao anterior, ou ao Add filter.
-- Um pill tem aria-haspopup="dialog"; sob readOnly a toolbar leva aria-description="Read only" e os segmentos guardam a paragem com aria-disabled, e um valor bloqueado nomeia a lista inteira que o popover já não mostra.
-- A contagem é a própria região viva, em polite, por isso o efeito de um filtro é ouvido; aplicar, limpar, remover um chip e escolher uma vista são anunciados pelo live-announcer partilhado.
-- O construtor é um drawer: modal, Escape fecha e descarta, o foco volta ao gatilho. Cada grupo é um fieldset com legend, cada regra três controles nomeados — Field, Operator, Value ou From e To.
-- Abaixo de 36rem o operador, more, add e clear saem do anel de foco com visibility hidden, não só do desenho: uma parada onde nada se vê é uma parada que não existe. Os cartões fechados do construtor tiram os três controles do anel da mesma forma; a frase do cartão tem aria-expanded e aria-controls.
+- The root is role="search", not role="toolbar": the APG Toolbar pattern asks a toolbar to avoid controls that need the arrows, and the search field is one. The search is the first tab stop and the toolbar the second — two stops however many fields there are; the APG note on multi-row toolbars lets the arrows move from row to row.
+- A chip is role="group" named "<field>: <phrase>", the same phrase describeFilter gives to the table announcement, and ", incomplete" while the value is missing. The operator has aria-haspopup="menu", the value aria-haspopup="dialog" and the name with the whole list, the X "Remove <field>". Delete and Backspace on any segment remove with the reason remove and focus goes to the segment of the same role on the next chip, the previous one, or Add filter.
+- A pill has aria-haspopup="dialog"; under readOnly the toolbar carries aria-description="Read only" and the segments keep their stop with aria-disabled, and a locked value names the whole list the popover no longer shows.
+- The count is itself the live region, in polite, so the effect of a filter is heard; applying, clearing, removing a chip and choosing a view are announced by the shared live-announcer.
+- The builder is a drawer: modal, Escape closes and discards, focus returns to the trigger. Each group is a fieldset with a legend, each rule three named controls — Field, Operator, Value or From and To.
+- Below 36rem the operator, more, add and clear leave the focus ring with visibility hidden, not only the drawing: a stop where nothing is seen is a stop that does not exist. The builder’s closed cards take the three controls out of the ring the same way; the card’s phrase has aria-expanded and aria-controls.
 
 ## Tokens
 
@@ -135,9 +135,9 @@ Excerpt — not a complete module
 
 ## Examples
 
-### A barra sobre a tabela, e a mesma regra nos dois sítios
+### The bar over the table, and the same rule in both places
 
-A árvore é aplicada pelo consumidor com createFilterGroupPredicate e createSearchPredicate; a tabela abaixo encolhe e a contagem diz quanto. O filtro de coluna de Status no cabeçalho edita o mesmo objeto que o chip de Status da barra.
+The consumer applies the tree with createFilterGroupPredicate and createSearchPredicate; the table below shrinks and the count says by how much. The Status column filter in the header edits the same object as the bar’s Status chip.
 
 Excerpt — not a complete module
 
@@ -147,9 +147,9 @@ const find = createSearchPredicate(query, (row, field) => row[field], ['customer
 const kept = orders.filter((row) => keep(row) && find(row));
 ```
 
-### Campos fixados: um lugar tracejado que vira chip
+### Pinned fields: a dashed place that becomes a chip
 
-pinned deixa o campo sempre à vista. Sem condição é um pill tracejado com + e o nome — um lugar à espera de ser preenchido; premido, dá lugar ao chip do campo, no mesmo sítio, incompleto e com o popover do valor aberto. Remover a condição devolve o pill.
+pinned keeps the field always in view. Without a condition it is a dashed pill with + and the name — a place waiting to be filled; pressed, it gives way to the field’s chip, in the same place, incomplete and with the value popover open. Removing the condition brings the pill back.
 
 Excerpt — not a complete module
 
@@ -168,9 +168,9 @@ const FIELDS = [
 ];
 ```
 
-### Cada condição escrita em segmentos
+### Each condition written in segments
 
-Um chip é a frase da condição em segmentos: o campo com o seu glifo, o operador mais leve, o valor, e o X. O operador abre um menu, o valor um popover só com o operando — mudar a comparação não reabre os valores. Uma lista longa escreve dois valores e o resto em número (Paid, Refunded +2), inteira no nome e no title; uma lista de um lê-se como igualdade. Add filter cria o chip de imediato, tracejado até ter valor, e fora do valor emitido até lá. Além de chipLimit os chips dobram atrás de +n more.
+A chip is the condition’s phrase in segments: the field with its glyph, the lighter operator, the value, and the X. The operator opens a menu, the value a popover with the operand only — changing the comparison does not reopen the values. A long list writes two values and the rest as a number (Paid, Refunded +2), whole in the name and the title; a list of one reads as equality. Add filter creates the chip at once, dashed until it has a value, and left out of the emitted value until then. Beyond chipLimit the chips fold behind +n more.
 
 Excerpt — not a complete module
 
@@ -178,9 +178,9 @@ Excerpt — not a complete module
 <FilterBar chipLimit={6} defaultRevealed={false} fields={FIELDS} value={filter} />;
 ```
 
-### O construtor num drawer
+### The builder in a drawer
 
-Add filter, um chip de grupo ou Filters (n) abrem a árvore inteira num drawer; num telefone o drawer sobe de baixo como uma folha. Com mais de 30rem cada regra é uma linha de campo, operador, operando e X; com menos, um cartão com a frase que se expande no lugar, um de cada vez. Apply pede a árvore com a razão submit, Cancel e Escape descartam.
+Add filter, a group chip or Filters (n) open the whole tree in a drawer; on a phone the drawer rises from the bottom as a sheet. Wider than 30rem each rule is a row of field, operator, operand and X; narrower, a card with the phrase that expands in place, one at a time. Apply requests the tree with the reason submit, Cancel and Escape discard.
 
 Excerpt — not a complete module
 
@@ -195,9 +195,9 @@ const bar = useRef<FilterBarHandle>(null);
 bar.current?.open();
 ```
 
-### Grupos E/OU aninhados
+### Nested AND/OR groups
 
-Um grupo dentro de um grupo é uma caixa sobre a superfície afundada, com a junção oposta e o caixote que o remove; num construtor estreito passa a um trilho na aresta inicial, que custa dez pixels por nível em vez de oitenta. Na barra aparece como um chip só, com a frase entre parênteses, que abre o construtor.
+A group inside a group is a box over the sunken surface, with the opposite join and the trash that removes it; in a narrow builder it becomes a rail on the start edge, which costs ten pixels per level instead of eighty. On the bar it appears as a single chip, with the phrase in parentheses, that opens the builder.
 
 Excerpt — not a complete module
 
@@ -227,9 +227,9 @@ const filter = {
 };
 ```
 
-### Aplicar em lote
+### Applying in a batch
 
-Com apply="manual" cada edição vai a um rascunho: a raiz fica data-dirty, Reset descarta, Apply pede a árvore e a query com a razão submit. Enter num operando aplica. É o Go do Fiori e o batch do Carbon.
+With apply="manual" each edit goes to a draft: the root becomes data-dirty, Reset discards, Apply requests the tree and the query with the reason submit. Enter on an operand applies. It is the Go of Fiori and the batch of Carbon.
 
 Excerpt — not a complete module
 
@@ -242,9 +242,9 @@ Excerpt — not a complete module
 />;
 ```
 
-### Um campo obrigatório com default
+### A required field with a default
 
-required fixa o campo e dá-lhe um defaultValue: Clear devolve-o ao default em vez de o apagar, o chip não tem X, e um Apply com o campo sem valor é recusado — o chip fica tracejado e data-invalid, a mensagem é anunciada.
+required pins the field and gives it a defaultValue: Clear returns it to the default instead of erasing it, the chip has no X, and an Apply with the field empty is refused — the chip stays dashed and data-invalid, and the message is announced.
 
 Excerpt — not a complete module
 
@@ -259,9 +259,9 @@ const company = {
 };
 ```
 
-### Vistas guardadas
+### Saved views
 
-presets aparece como um select no fim da barra: escolher uma substitui a árvore com a razão select; editar depois mantém a vista escolhida e marca a raiz data-dirty. Guardar é da aplicação — onPresetSave entrega a árvore, o nome é ela que pergunta.
+presets appears as a select at the end of the bar: choosing one replaces the tree with the reason select; editing afterwards keeps the chosen view and marks the root data-dirty. Saving belongs to the application — onPresetSave hands over the tree, and the application asks for the name.
 
 Excerpt — not a complete module
 
@@ -275,9 +275,9 @@ Excerpt — not a complete module
 />;
 ```
 
-### A busca global
+### The global search
 
-A query é o único campo que não pertence a nenhuma coluna. Debounced por queryDelay sob live; Escape limpa com a razão clear; shortcut é a tecla do documento que chega ao campo, desenhada dentro dele com kbd — e escondida onde a entrada primária é um ecrã táctil, onde não há tecla para carregar.
+The query is the only field that belongs to no column. Debounced by queryDelay under live; Escape clears with the reason clear; shortcut is the document key that reaches the field, drawn inside it with kbd — and hidden where the primary input is a touch screen, where there is no key to press.
 
 Excerpt — not a complete module
 
@@ -285,9 +285,9 @@ Excerpt — not a complete module
 <FilterBar fields={FIELDS} onQueryChange={setQuery} query={query} queryDelay={120} shortcut="/" />;
 ```
 
-### O estado numa URL
+### The state in a URL
 
-toFilterBarParams escreve f=and(…) e q=; fromFilterBarParams lê-os de volta, e um f.<coluna> escrito por uma tabela sem barra vira um grupo de primeiro nível. parseFilterGroup é total: um marcador de uma versão antiga degrada para nenhum filtro.
+toFilterBarParams writes f=and(…) and q=; fromFilterBarParams reads them back, and an f.<column> written by a table without a bar becomes a top-level group. parseFilterGroup is total: a marker from an older version degrades to no filter.
 
 Excerpt — not a complete module
 
@@ -297,9 +297,9 @@ history.replaceState(null, '', `?${params}`);
 const restored = fromFilterBarParams(location.search);
 ```
 
-### A contagem como região viva
+### The count as a live region
 
-count e total são os números do consumidor, escritos nas figuras da língua em vigor. A parte é aria-live="polite", por isso uma mudança no filtro é ouvida como o seu efeito; com loading a contagem dá lugar a um spinner e aria-busy.
+count and total are the consumer’s numbers, written in the figures of the current locale. The part is aria-live="polite", so a change in the filter is heard as its effect; with loading the count gives way to a spinner and aria-busy.
 
 Excerpt — not a complete module
 
@@ -307,9 +307,9 @@ Excerpt — not a complete module
 <FilterBar count={128} fields={FIELDS} loading={fetching} total={3412} />;
 ```
 
-### Num telefone: uma linha que desliza e uma folha
+### On a phone: a row that scrolls sideways and a sheet
 
-Abaixo de 36rem a busca fica em cima e a barra passa a uma linha que desliza: Filters (n) primeiro, todos os chips — também os dobrados —, depois os pills vazios; o chip cortado na borda diz que a linha continua. Cada chip tem três alvos: o campo, o valor com as palavras do operador, o X. Tocar num valor, num pill ou em Filters abre o construtor como folha, com o cartão da regra aberto. Redimensione o palco.
+Below 36rem the search sits on top and the bar becomes a row that scrolls sideways: Filters (n) first, every chip — the folded ones too —, then the empty pills; the chip cut at the edge says the row continues. Each chip has three targets: the field, the value with the operator’s words, the X. Tapping a value, a pill or Filters opens the builder as a sheet, with the rule’s card open. Resize the stage.
 
 Excerpt — not a complete module
 
@@ -319,9 +319,9 @@ Excerpt — not a complete module
 </div>;
 ```
 
-### Colada sob o cabeçalho da página
+### Stuck under the page header
 
-sticky lê --slotted-page-sticky-top, cola a barra aí, e soma a própria altura à propriedade no elemento pai para o que vem a seguir — uma tabela com cabeçalho colado para debaixo da barra, não debaixo do título.
+sticky reads --slotted-page-sticky-top, sticks the bar there, and adds its own height to the property on the parent element for what comes next — a table with a sticky header sticks below the bar, not below the title.
 
 Excerpt — not a complete module
 
@@ -332,9 +332,9 @@ Excerpt — not a complete module
 </>;
 ```
 
-### Desabilitada, a carregar, só leitura
+### Disabled, loading, read only
 
-disabled desliga todos os controles e mantém a largura; loading mantém os controles, desliga Apply e põe o spinner no lugar da contagem; readOnly deixa cada condição alcançável e legível — os segmentos guardam a paragem com aria-disabled — e não desenha X, add, clear nem pills vazios.
+disabled turns off every control and keeps the width; loading keeps the controls, turns off Apply and puts the spinner in place of the count; readOnly leaves every condition reachable and readable — the segments keep their stop with aria-disabled — and draws no X, add, clear or empty pills.
 
 Excerpt — not a complete module
 
@@ -346,9 +346,9 @@ Excerpt — not a complete module
 </>;
 ```
 
-### Conteúdo que a família não escolheu
+### Content the family did not choose
 
-Um valor de onze itens escreve dois e o resto em número, inteiro no title e no nome acessível; um valor longo trunca a 12rem; um rótulo árabe ao lado de uma data ISO não reordena a data, porque campo, operador e valor são corridas isoladas; um campo desconhecido é um chip inválido, removível.
+A value of eleven items writes two and the rest as a number, whole in the title and in the accessible name; a long value truncates at 12rem; an Arabic label next to an ISO date does not reorder the date, because field, operator and value are isolated runs; an unknown field is an invalid, removable chip.
 
 Excerpt — not a complete module
 
@@ -360,14 +360,14 @@ Excerpt — not a complete module
 />;
 ```
 
-### Teclado
+### Keyboard
 
-Tab: a busca, depois a barra — duas paragens. As setas percorrem cada controle da barra, segmento a segmento, de linha em linha e espelhadas em RTL; Home e End nas pontas. Enter no operador abre o menu, no valor o popover; Delete em qualquer segmento remove a condição com a razão remove e o foco vai ao mesmo segmento do chip seguinte; Escape limpa a busca ou fecha a superfície.
+Tab: the search, then the bar — two stops. The arrows move through every control of the bar, segment by segment, from row to row and mirrored in RTL; Home and End at the ends. Enter on the operator opens the menu, on the value the popover; Delete on any segment removes the condition with the reason remove and focus goes to the same segment of the next chip; Escape clears the search or closes the surface.
 
 Excerpt — not a complete module
 
 ```tsx
-// "Amount filter removed" — e o foco segue para o chip seguinte, ou para
-// Add filter quando não sobra nenhum.
+// "Amount filter removed" — and focus moves to the next chip, or to
+// Add filter when none is left.
 <FilterBar fields={FIELDS} onValueChange={(next, request) => request.reason === 'remove'} />;
 ```

package/dist/docs/form.json

@@ -278,6 +278,7 @@
     "--slotted-font-family-sans",
     "--slotted-font-weight-semibold",
     "--slotted-form-color",
+    "--slotted-form-field-gap",
     "--slotted-form-summary-background",
     "--slotted-form-summary-border-color",
     "--slotted-form-summary-color",
@@ -302,7 +303,7 @@
     {
       "id": "playground",
       "title": "Playground",
-      "note": "A form of two fields with the family’s whole lifecycle on it. Submit it empty: the platform’s own messages appear in the summary, focus moves there, and each link jumps to the field it names.",
+      "note": "A form of two fields with the family’s whole lifecycle on it. Submit it empty: the platform’s own messages appear in the summary, focus moves there, and each link jumps to the field it names. Two fields written one after the other inside the form stand apart by --slotted-form-field-gap (space-6 by default); a layout the page draws itself — a Grid, a Stack — keeps its own gap.",
       "language": "tsx",
       "source": "<Form onSubmit={(values) => save(values)}>\n  <Field>\n    <FieldLabel>Nome completo</FieldLabel>\n    <TextField name=\"nome\" required />\n  </Field>\n  <FormActions>\n    <Button type=\"submit\">Salvar</Button>\n  </FormActions>\n</Form>;\n",
       "verdict": "excerpt"

package/dist/docs/form.md

@@ -87,7 +87,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-width-thick`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-weight-semibold`, `--slotted-form-color`, `--slotted-form-summary-background`, `--slotted-form-summary-border-color`, `--slotted-form-summary-color`, `--slotted-form-summary-radius`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-radius-md`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`
+`--slotted-border-width-thick`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-weight-semibold`, `--slotted-form-color`, `--slotted-form-field-gap`, `--slotted-form-summary-background`, `--slotted-form-summary-border-color`, `--slotted-form-summary-color`, `--slotted-form-summary-radius`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-radius-md`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`
 
 ## Examples
 

package/dist/docs/guidelines/README.md

@@ -0,0 +1,27 @@
+# Guidelines
+
+Rules for composing screens from the Slotted families: what the reference
+pages do not state. A family's page states what it is — its parts, states,
+tokens and keyboard. It does not state where a pager stands, what a region
+shows before its first answer, or which family a bar's search slot is for.
+
+## Reading protocol
+
+For a reader with a task — a person or a model about to write or review a
+screen:
+
+1. Read `index.md`: every active rule in one line, with its level and its file.
+2. Match the task against the `triggers` in each topic file's front matter.
+   Read the topic files that match, and `composition.md` always.
+3. Before writing an element beside a family, read that family's page in
+   `..`. Before writing an element no family draws, read
+   `own-elements.md` and `../tokens.md`.
+4. Apply the rules by level: a `MUST` broken is a defect, a `SHOULD` broken is
+   stated with its reason, a `MAY` is a permission.
+5. A screen is done when each `Check` of the rules read passes.
+
+## Rule identity
+
+An id (`AF-03`) never changes meaning. A rule whose meaning or level changes
+is retired, keeps its heading with `Status: retired`, and is rewritten under a
+new id. The release notes of each version list the ids added and retired.

package/dist/docs/guidelines/async-feedback.md

@@ -0,0 +1,129 @@
+---
+topic: async feedback
+prefix: AF
+triggers:
+  [
+    loading,
+    pending,
+    busy,
+    empty,
+    skeleton,
+    placeholder,
+    request,
+    fetch,
+    mutation,
+    tab,
+    view,
+    page,
+    pagination,
+    popover,
+    refresh,
+    latency,
+    spinner,
+    submit,
+    action,
+  ]
+families:
+  [
+    skeleton,
+    button,
+    popover,
+    list,
+    list-item,
+    notification-center,
+    tabs,
+    pagination,
+    result-state,
+    page-header,
+  ]
+---
+
+# Async feedback
+
+What a screen shows between a request starting and its answer arriving. The
+library gives the states — `skeleton` for a region, `loading` on a control,
+`data-loading` and `aria-busy` on the families that fill themselves — and does
+not say which one a screen owes at which moment. A request answers within a
+second on a fast network and takes several on a slow one; a screen that shows
+nothing for that long reads as a stall, and a screen that shows its empty
+state reads as an answer.
+
+### AF-01 · Pending is not empty
+
+Level: MUST
+Applies to: any region filled by a request — a `popover` body, a `list`, a `data-grid`, a `notification-center` feed, a page section
+Rule: A region whose first answer has not arrived shows its pending state; the empty state appears only after an answer holding zero items.
+Why: An empty state is a statement about the data, and before the answer there is no data to state anything about.
+Do: Keep a loading fact beside the items, set before the request and cleared after it. Render placeholders while the fact is true and the items are none; render the empty state while the fact is false and the items are none.
+Don't: Branch on the items alone. A region that opens on "Nothing waiting for you" while the request is in flight tells the reader the queue is clear, for as long as the request takes.
+Check: Throttle the network to a slow profile and open the region cold; the empty words do not appear before the answer.
+
+### AF-02 · First answer draws placeholders, later answers keep the rows
+
+Level: SHOULD
+Applies to: every region under AF-01 that is filled more than once — a panel opened again, a list read back after a mutation
+Rule: A region with no items yet draws placeholders; a region that already shows items keeps them on screen and marks itself busy while a newer answer is on its way.
+Why: Placeholders in place of rows the reader was looking at erase their place; rows silently replaced give no sign anything happened.
+Do: Placeholders are the family `skeleton`: a region carrying the state and, inside it, the rows' own boxes — the mark, the label line, the description line — so the answer lands without a layout shift. A placeholder line is a fraction of its row, never a length: a length wider than a phone's row overflows the page and scrolls it sideways. While items are shown and a request runs, the list carries `aria-busy` and the rows stay.
+Don't: Draw placeholders on every request, or clear the items before every request. Reading a list back after marking one row is a refresh, not a first load.
+Check: Open the region twice with the network throttled to a slow profile: placeholders on the first open, the previous rows and no placeholders on the second.
+
+### AF-03 · The control that starts a request waits on it
+
+Level: MUST
+Applies to: any `button` member — button, icon button, toggle button — whose activation runs a request — mark as read, archive, approve, save, submit — except a control whose request reloads the whole page; the page header's progress bar answers that wait (AF-07)
+Rule: From activation until the answer, the control is in its `loading` state: it refuses a second activation and shows the family's indicator.
+Why: A control that looks idle invites a second press, and the second request is a duplicate the backend has to refuse or the reader has to undo.
+Do: Keep, beside the data, the identity of what is in flight — the row's key for a row action, one fact for a list-wide action — and bind the control's `loading` to it. The family refuses activation on its own and names the wait for assistive technology through its loading label.
+Don't: Disable the control by hand, hide it, or leave it as it was until the row disappears. Disabled says "not allowed"; loading says "working on it".
+Check: Press the control with the network throttled to a slow profile: the indicator appears, a second press does nothing, the row changes once.
+
+### AF-04 · A change of view or page draws placeholders
+
+Level: SHOULD
+Applies to: `tabs` that switch the content of a region, `pagination`, any filter whose answer replaces the rows rather than refreshing them
+Rule: When the reader asks for different rows, the rows on screen are removed and placeholders stand in their place until the answer arrives.
+Why: The rows on screen are the previous answer; leaving them under the new tab says the tab did nothing until, half a second later, it does.
+Do: Empty the items on the change and let AF-01 draw the placeholders. Keep what does not change — the tab strip, the pager, the header — where it is.
+Don't: Keep the old rows until the new ones arrive, or replace the whole region including the tab strip with a placeholder block.
+Check: Switch the view with the network throttled to a slow profile: placeholders at once, the tab strip and the pager still in place, rows on the answer.
+
+### AF-05 · An indicator may wait for the request to be slow
+
+Level: MAY
+Applies to: a control under AF-03 whose request usually answers under the indicator's own entrance
+Rule: A control's indicator may be delayed by the family's loading delay, so a request that answers first shows no indicator; a region's placeholders are never delayed.
+Why: An indicator that appears and leaves within one frame is a flicker, and a region with nothing in it is a stall from the first frame.
+Do: Use the family's delay on a control whose request is short in the normal case and leave the control refusing activation from the first instant, which the family does regardless of the delay.
+Don't: Delay a region's placeholders, or delay a control's refusal of activation.
+Check: On an unthrottled network a short request shows no indicator and still ignores a second press; with the network throttled to a slow profile, the indicator appears.
+
+### AF-06 · Placeholders are held once they are drawn
+
+Level: SHOULD
+Applies to: every region under AF-01, through the application's own defaults for the family
+Rule: The application states one minimum duration for the whole product: once placeholders are painted they stay for it, even when the answer has already arrived.
+Why: A request on a fast network answers within a few hundred milliseconds, so an undelayed region paints and is replaced inside a few frames — a blink the reader reads as a fault rather than as a wait.
+Do: State the minimum where the application states its other family defaults, and leave the delay at nothing: AF-05 keeps a region's placeholders undelayed, and the minimum is the other half of the same decision.
+Don't: Set the minimum per screen, or reach for a delay to stop the blink — a delay is a region showing nothing for as long as it lasts.
+Check: On an unthrottled network, open a screen of placeholders twice: the placeholders are visible on both, and no region paints and empties within one frame.
+
+### AF-07 · A record another actor changes offers Refresh
+
+Level: SHOULD
+Applies to: a record page, or a list, whose data another person or process can change while it is open — an order, an invoice, a customer another writer edits
+Rule: The page offers Refresh among the header's actions, and a refresh keeps the values on screen, marks the page busy and replaces them when the answer arrives.
+Why: Without it the reader reloads the browser, which loses the scroll, the open tab and any draft, and a refresh that blanks the record flickers what was already read.
+Do: Put an icon button named "Refresh" in the header's actions toolbar with its menu counterpart. The wait is the page's, not the button's: the `page-header` progress part shows it, with `loading` bound to "reading again while data is shown", over the header's closing line; the button draws no indicator of its own, and a second press while the read runs starts nothing — the read in flight answers it. The body keeps its rows and draws no placeholder.
+Don't: Offer Refresh on a record nothing else writes, or clear the record and draw its skeleton on every read after the first.
+Check: Press Refresh: the header's bar runs over the closing line, the button shows no spinner and ignores a second press, the values stay.
+
+### AF-08 · A write refreshes every view it changed
+
+Level: MUST
+Applies to: every control that writes — a create, an edit, a delete, a categorisation — and every region on any screen whose figures the write can change
+Rule: A successful write marks stale every query whose answer the write can change, and the regions on screen read again; an application that cannot list them marks every query stale; a region that reads again keeps its rows and dims them (LP-06).
+Why: Categorising a transaction left the category totals and the rules' coverage at their old figures until a reload, and the reader reloaded after every action to trust the screen.
+Do: Beside each write, list the queries its answer changes — the record, the lists it appears in, the totals and counts over them — and invalidate them on success; where the list cannot be stated, invalidate every query after a successful write.
+Don't: Refresh only the region the control stands in, or rely on the next navigation to read the other figures again.
+Check: Perform each write: every figure on screen that the write changes shows the new value without a reload.