@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/filter-bar.md

@@ -0,0 +1,380 @@
+<!-- index: ./index.md -->
+# filter-bar
+
+`data-ui="filter-bar"` · Search and filter chips that build a query.
+
+## Import
+
+```ts
+import {
+  SlFilterBar,
+  SlFilterBarEnd,
+  SlFilterBarOperand,
+  provideFilterBarDefaults,
+} from '@slotted/angular/filter-bar';
+import { createFilterGroupPredicate, createSearchPredicate } from '@slotted/core/filter';
+```
+
+Selector: `[slFilterBar], [slFilterBarEnd], ng-template[slFilterBarOperand]` · exportAs: `slFilterBar`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div
+  slFilterBar
+  [count]="kept().length"
+  [fields]="fields"
+  [total]="orders.length"
+  [(value)]="filter"
+></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `frame` | div | yes |
+| `search` | div | yes |
+| `bar` | div | yes |
+| `pill` | button | no |
+| `add` | button | yes |
+| `clear` | button | no |
+| `preset` | div | no |
+| `actions` | div | no |
+| `apply` | button | no |
+| `reset` | button | no |
+| `summary` | button | yes |
+| `end` | div | yes |
+| `chip` | div | no |
+| `chip-field` | span | no |
+| `chip-operator` | button | no |
+| `chip-value` | button | no |
+| `chip-remove` | button | no |
+| `more` | button | no |
+| `count` | p | no |
+| `builder` | div | yes |
+| `group` | fieldset | yes |
+| `join` | div | yes |
+| `rules` | div | yes |
+| `conjunction` | span | yes |
+| `rule` | div | no |
+| `rule-summary` | button | no |
+| `field` | div | no |
+| `operator` | div | no |
+| `operand` | div | no |
+| `remove` | button | no |
+| `add-rule` | button | yes |
+| `add-group` | button | yes |
+| `remove-group` | button | no |
+| `save-preset` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `fields` | `FilterBarField[]` | — | FilterBar | Os campos filtráveis: key, label, kind, icon (nome de glifo ou TemplateRef), operators, pinned, required, defaultValue, section, options, searchable |
+| `value` | `model<FilterGroup \| null \| undefined>` | — | FilterBar | [(value)]: 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` | `model<string \| undefined>` | — | FilterBar | [(query)]: a busca global |
+| `defaultQuery` | `string` |  | FilterBar | A busca com que uma barra não controlada começa |
+| `presets` | `FilterBarPreset[]` | — | FilterBar | As vistas guardadas: key, label, value |
+| `preset` | `model<string \| null \| undefined>` | — | FilterBar | [(preset)]: a vista corrente |
+| `defaultPreset` | `string \| null` | null | FilterBar | A vista com que começa |
+| `open` | `model<boolean \| undefined>` | — | FilterBar | [(open)]: se o construtor está aberto |
+| `defaultOpen` | `boolean` | false | FilterBar | Se começa aberto |
+| `revealed` | `model<boolean \| undefined>` | — | FilterBar | [(revealed)]: se os chips dobrados estão à vista |
+| `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 |
+| `savePresetEnabled` | `boolean` | false | FilterBar | Desenha "Save as view…" no construtor e emite savePreset |
+| `ng-template[slFilterBarOperand]` | `projeção` | — | FilterBar | Substitui o controle do operando do campo nomeado, ou de todos com "*" |
+| `[slFilterBarEnd]` | `projeção` | — | FilterBar | Os controles do consumidor no slot end |
+| `ng-template[slFilterBarOperand]` | `let-field, let-operator="operator", let-value="value", let-set="set", let-apply="apply"` | — | FilterBar | A costura que a rodada 12 usa em table: date-range-picker num between, tags-input num conjunto grande |
+| `[slFilterBarEnd]` | `ng-content` | — | FilterBar | O slot end: uma ordenação, um seletor de colunas, fora do anel da toolbar |
+| `exportAs` | `slFilterBar` | — | FilterBar | Alcança a instância a partir da template: #bar="slFilterBar" e bar.focusSearch() ou bar.openBuilder() |
+| `provideFilterBarDefaults()` | `apply \| chipLimit \| queryDelay \| shortcut \| size` | — | Injector | Decide uma vez para tudo por baixo; um input na barra ganha |
+| `id, aria-label, dir, data-*, (keydown)` | `atributos nativos` | — | FilterBar | Ficam no elemento host; aria-label dá nome ao landmark, o listener do consumidor corre a par do da família |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChangeRequest)` | `ChangeRequest<FilterGroup \| null>` | Antes de a árvore mover; [(value)] é a outra metade, o valor. 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. |
+| `(queryChangeRequest)` | `ChangeRequest<string>` | Depois de queryDelay sob live, ou com submit sob manual; clear quando Escape ou o X do campo a limpam. [(query)] é o valor. |
+| `(presetChangeRequest)` | `ChangeRequest<string \| null>` | Quando uma vista é escolhida no select, com select; clear quando o select é esvaziado. [(preset)] é o valor. |
+| `(savePreset)` | `FilterGroup \| null` | Quando o leitor pressiona "Save as view…" no construtor, desenhado por savePresetEnabled. A família não guarda: pergunta. |
+| `(openChangeRequest)` | `ChangeRequest<boolean>` | Antes de o construtor abrir ou fechar: pointer, keyboard, escape, outsidePress, dismiss, submit, programmatic. [(open)] é o valor. |
+| `(revealedChangeRequest)` | `ChangeRequest<boolean>` | Antes de os chips dobrados aparecerem ou voltarem a dobrar. [(revealed)] é o valor. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `apply` | `live`, `manual` | `live` |
+| `sticky` | `false`, `true` | `false` |
+| `size` | `sm`, `md`, `lg` | `md` |
+
+## 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.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--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-invalid-edge-width`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-standard`, `--slotted-filter-bar-chip-seam`, `--slotted-filter-bar-color`, `--slotted-filter-bar-color-muted`, `--slotted-filter-bar-editor-size`, `--slotted-filter-bar-font-family`, `--slotted-filter-bar-gap`, `--slotted-filter-bar-group-border`, `--slotted-filter-bar-group-surface`, `--slotted-filter-bar-join-size`, `--slotted-filter-bar-pill-border`, `--slotted-filter-bar-pill-radius`, `--slotted-filter-bar-search-max`, `--slotted-filter-bar-surface`, `--slotted-filter-bar-value-max`, `--slotted-filter-bar-value-max-narrow`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-danger-border`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-sticky`
+
+## Examples
+
+### A barra sobre a tabela, e a mesma regra nos dois sítios
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const kept = computed(() => {
+  const keep = createFilterGroupPredicate(filter(), (row, field) => row[field]);
+  const find = createSearchPredicate(query(), (row, field) => row[field], ['customer', 'id']);
+  return orders.filter((row) => keep(row) && find(row));
+});
+```
+
+### Campos fixados: um lugar tracejado que vira 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.
+
+Excerpt — not a complete module
+
+```ts
+const FIELDS: FilterBarField[] = [
+  {
+    key: 'status',
+    kind: 'set',
+    label: 'Status',
+    options: STATUSES,
+    pinned: true,
+  },
+  { key: 'customer', kind: 'text', label: 'Customer', pinned: true },
+  { key: 'amount', kind: 'number', label: 'Amount' },
+];
+```
+
+### Cada condição escrita em segmentos
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slFilterBar chipLimit="6" [fields]="fields" [value]="filter"></div>
+```
+
+### O construtor num 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.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slFilterBar
+  #bar="slFilterBar"
+  [fields]="fields"
+  (openChangeRequest)="log($event.reason)"
+></div>
+<button slButton type="button" (click)="bar.openBuilder()">Abrir o construtor</button>
+```
+
+### Grupos E/OU aninhados
+
+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.
+
+Excerpt — not a complete module
+
+```ts
+const filter: FilterGroup = {
+  join: 'and',
+  rules: [
+    { field: 'status', filter: setFilter(['paid']) },
+    {
+      join: 'or',
+      rules: [
+        {
+          field: 'amount',
+          filter: {
+            kind: 'number',
+            join: 'and',
+            conditions: [{ operator: 'greaterThan', value: 1000 }],
+          },
+        },
+        {
+          field: 'priority',
+          filter: { kind: 'boolean', join: 'and', conditions: [{ operator: 'is', value: true }] },
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Aplicar em lote
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slFilterBar
+  apply="manual"
+  [fields]="fields"
+  (queryChangeRequest)="$event.reason === 'submit' && fetch($event.value)"
+  (valueChangeRequest)="$event.reason === 'submit' && fetch($event.value)"
+></div>
+```
+
+### Um campo obrigatório com 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.
+
+Excerpt — not a complete module
+
+```ts
+const company: FilterBarField = {
+  key: 'company',
+  kind: 'set',
+  label: 'Company',
+  options: COMPANIES,
+  required: true,
+  defaultValue: setFilter(['acme']),
+};
+```
+
+### Vistas guardadas
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slFilterBar
+  [fields]="fields"
+  [(preset)]="view"
+  [presets]="[{ key: 'overdue', label: 'Overdue this month', value: overdue }]"
+  savePresetEnabled
+  (savePreset)="askForName($event)"
+></div>
+```
+
+### A busca global
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slFilterBar [fields]="fields" [(query)]="query" queryDelay="120" shortcut="/"></div>
+```
+
+### O estado numa 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.
+
+Excerpt — not a complete module
+
+```ts
+const params = toFilterBarParams({ filter, query });
+history.replaceState(null, '', `?${params}`);
+const restored = fromFilterBarParams(location.search);
+```
+
+### A contagem como região viva
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slFilterBar count="128" [fields]="fields" [loading]="fetching()" total="3412"></div>
+```
+
+### Num telefone: uma linha que desliza e uma folha
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div class="listing listing--narrow">
+  <div slFilterBar [fields]="fields" [value]="filter"></div>
+</div>
+```
+
+### Colada sob o cabeçalho da página
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slFilterBar [fields]="fields" sticky [value]="filter"></div>
+<table slTable stickyHeader>
+  …
+</table>
+```
+
+### Desabilitada, a carregar, só leitura
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slFilterBar disabled [fields]="fields"></div>
+<div slFilterBar [fields]="fields" loading></div>
+```
+
+### Conteúdo que a família não escolheu
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slFilterBar
+  dir="rtl"
+  [fields]="[{ key: 'city', kind: 'set', label: 'المدينة', options: cities }]"
+  [value]="filter"
+></div>
+```
+
+### Teclado
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- "Amount filter removed" — e o foco segue para o chip seguinte, ou para Add filter quando não sobra nenhum. -->
+<div slFilterBar [fields]="fields" (valueChangeRequest)="log($event.reason === 'remove')"></div>
+```