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

package/docs/timeline.md

@@ -0,0 +1,401 @@
+<!-- index: ./index.md -->
+# timeline
+
+`data-ui="timeline"` · Events in time order with markers.
+
+## Import
+
+```ts
+import {
+  SlTimeline,
+  SlTimelineActions,
+  SlTimelineActor,
+  SlTimelineDescription,
+  SlTimelineGroup,
+  SlTimelineGroupList,
+  SlTimelineItem,
+  SlTimelineList,
+  SlTimelineMarker,
+  SlTimelineOpposite,
+  SlTimelineTime,
+  SlTimelineTitle,
+  provideTimelineDefaults,
+} from '@slotted/angular/timeline';
+```
+
+Selector: `[slTimeline], ol[slTimelineList] ou div[slTimelineList], li[slTimelineGroup] ou div[slTimelineGroup], ol[slTimelineGroupList] ou div[slTimelineGroupList], li[slTimelineItem] ou article[slTimelineItem], time[slTimelineTime], [slTimelineTitle], [slTimelineActor], [slTimelineDescription], [slTimelineActions], [slTimelineOpposite], [slTimelineMarker], [slTimelineEmpty]` · exportAs: `slTimeline, slTimelineList, slTimelineGroup, slTimelineGroupList, slTimelineItem, slTimelineTime`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline label="Atividade da fatura" locale="pt-BR" timeZone="America/Sao_Paulo">
+  <ol slTimelineList>
+    <li
+      slTimelineItem
+      actor="Ana Ribeiro"
+      description="Rascunho INV-4821 para Solaris Fretes."
+      time="2026-09-08T09:12:00Z"
+      title="Fatura criada"
+    ></li>
+    <li slTimelineItem current time="2026-09-14T10:32:00Z" title="Paga" tone="success"></li>
+  </ol>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `fresh` | button | no |
+| `list` | ol, ou div com role="feed" | yes |
+| `group` | li, ou div no feed | no |
+| `group-label` | h2 a h6, por level | no |
+| `group-trigger` | button | no |
+| `group-indicator` | span | no |
+| `group-list` | ol, ou div no feed | no |
+| `item` | li, ou article no feed | yes |
+| `opposite` | div | no |
+| `rail` | div | yes |
+| `marker` | span | yes |
+| `connector` | span | no |
+| `content` | div | yes |
+| `title` | div | no |
+| `actor` | div | no |
+| `time` | time | no |
+| `description` | div | no |
+| `actions` | div | no |
+| `more` | button, ou div enquanto carrega | no |
+| `empty` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `mode` | `'list' \| 'feed'` | list | Timeline | Uma lista ordenada, ou o padrão Feed do APG |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | Timeline | Uma coluna, ou uma fila que rola e reflui |
+| `placement` | `'end' \| 'start' \| 'alternate'` | end | Timeline | De que lado da linha o corpo vive |
+| `order` | `'oldest-first' \| 'newest-first'` | oldest-first | Timeline | O que a lista é; decide onde autoComplete corta. Nunca reordena o array |
+| `variant` | `'solid' \| 'outline' \| 'subtle' \| 'plain'` | subtle | Timeline | A aparência do marcador, herdada pelos eventos |
+| `tone` | `'secondary' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | secondary | Timeline | O tom do marcador, herdado pelos eventos |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Timeline | O passo do marcador e do tipo |
+| `growing` | `'none' \| 'button' \| 'scroll'` | none | Timeline | Como o fim do carregado pede mais |
+| `timeFormat` | `'absolute' \| 'relative'` | absolute | Timeline | Como a hora é escrita; relative guarda o absoluto em title |
+| `locale` | `string` | — | Timeline | BCP 47 para as horas; sem ele, o da língua em vigor (provideSlotted) |
+| `timeZone` | `string` | — | Timeline | O fuso em que um instante é escrito; sem ele, o do runtime |
+| `now` | `number` | — | Timeline | O instante de que uma leitura relativa conta, em milissegundos de época; sem ele, o relógio na renderização |
+| `level` | `2 \| 3 \| 4 \| 5 \| 6` | 3 | Timeline | O nível dos headings dos grupos |
+| `reflow` | `boolean` | true | Timeline | Se horizontal e alternate refluem abaixo de trinta rems |
+| `autoComplete` | `boolean` | false | Timeline | Marca concluídos os eventos do lado passado do atual, e traceja o futuro |
+| `loading` | `boolean` | false | Timeline | Mais eventos a caminho: aria-busy no feed, anel no fim |
+| `freshCount` | `number` | 0 | Timeline | Quantos eventos novos a pílula segura |
+| `count` | `number` | — | Timeline | O total, para aria-setsize; sem ele, -1 enquanto pode crescer |
+| `label` | `string` | — | Timeline | O nome acessível da lista |
+| `aria-label` | `atributo` | — | ol[slTimelineList] | Um nome escrito na lista sobrevive ao da raiz |
+| `messages` | `PartialMessages<TimelineMessages>` | — | Timeline | Palavras sobre o catálogo da língua em vigor, chave a chave: as sete mensagens da família |
+| `label` | `string` | — | TimelineGroup | O nome do período, como heading |
+| `collapsible` | `boolean` | false | TimelineGroup | Se o heading é um botão que dobra o grupo |
+| `open` | `model<boolean \| undefined>` | — | TimelineGroup | [(open)]: presente é controlado, para a vida do grupo |
+| `defaultOpen` | `boolean` | true | TimelineGroup | Onde um grupo não controlado começa, lido uma vez |
+| `level` | `2 \| 3 \| 4 \| 5 \| 6` | — | TimelineGroup | O nível deste heading, sobre o da raiz |
+| `title` | `string` | — | TimelineItem | O nome do evento; ou um elemento [slTimelineTitle] projetado |
+| `description` | `string` | — | TimelineItem | A segunda linha; ou [slTimelineDescription] projetado |
+| `actor` | `string` | — | TimelineItem | Quem o fez; ou [slTimelineActor] projetado |
+| `time` | `PlainDateTime \| string` | — | TimelineItem | Quando: instante ISO ou valor de parede |
+| `timeLabel` | `string` | — | TimelineItem | O texto no lugar da hora formatada |
+| `[slTimelineMarker]` | `projeção` | — | TimelineItem | O que o marcador segura no lugar do ponto |
+| `[slTimelineOpposite]` | `projeção` | — | TimelineItem | O outro lado da linha |
+| `[slTimelineActions]` | `projeção` | — | TimelineItem | A fila de controlos |
+| `current` | `boolean` | false | TimelineItem | O evento em que o leitor está: aria-current |
+| `complete` | `boolean` | — | TimelineItem | Concluído; vence a derivação |
+| `loading` | `boolean` | false | TimelineItem | Ainda a chegar: o marcador roda o anel |
+| `connector` | `'solid' \| 'dashed' \| 'none'` | — | TimelineItem | A linha depois deste evento |
+| `side` | `'start' \| 'end'` | — | TimelineItem | O lado em alternate; paridade sem ele |
+| `tone` | `TimelineTone` | — | TimelineItem | O tom deste evento, sobre o da raiz |
+| `variant` | `TimelineVariant` | — | TimelineItem | A aparência deste evento, sobre a da raiz |
+| `value` | `PlainDateTime \| string` | — | TimelineTime | O valor de máquina, escrito em datetime |
+| `exportAs` | `slTimeline \| slTimelineList \| slTimelineGroup \| slTimelineItem \| slTimelineTime` | — | cada parte | Alcança a instância a partir da template: #list="slTimelineList" e list.focusItem(2) move o foco a um artigo do feed |
+| `ng-content` | `[slTimelineTitle] \| [slTimelineActor] \| [slTimelineDescription] \| [slTimelineActions] \| [slTimelineOpposite] \| [slTimelineMarker] \| [slTimelineEmpty]` | — | TimelineItem, Timeline | Cada parte do corpo como elemento do consumidor, com data-part e id escritos pela diretiva |
+| `time[slTimelineTime]` | `{ value, format, locale, timeZone, now }` | — | em qualquer sítio | A parte time sozinha, para uma coluna opposite ou uma célula de tabela; lê a raiz quando há uma |
+| `provideTimelineDefaults()` | `mode \| orientation \| placement \| order \| variant \| tone \| size \| growing \| timeFormat \| timeZone \| now \| level` | — | Injector | Decide os catorze uma vez para tudo por baixo; um input na linha do tempo ganha |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(openRequest)` | `ChangeRequest<boolean>` | Em slTimelineGroup, antes de o grupo abrir ou fechar; [(open)] é a outra metade, o valor. O pedido leva o valor anterior, a razão — pointer, keyboard ou programmatic — e o evento de origem; cancelá-lo não move nada. |
+| `(loadMoreRequest)` | `{ reason: "pointer" \| "keyboard" \| "scroll"; event?: Event }` | Quando o leitor pressiona o botão de carregar mais, ou quando a sentinela entra no rolador em growing="scroll". Não há valor a segurar: o consumidor acrescenta ao array. |
+| `(revealRequest)` | `{ reason: "pointer" \| "keyboard"; event?: Event }` | Quando o leitor pressiona a pílula de eventos novos. O consumidor junta os eventos que segurava ao array e põe freshCount a zero. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `mode` | `list`, `feed` | `list` |
+| `orientation` | `vertical`, `horizontal` | `vertical` |
+| `placement` | `end`, `start`, `alternate` | `end` |
+| `order` | `oldest-first`, `newest-first` | `oldest-first` |
+| `variant` | `solid`, `outline`, `subtle`, `plain` | `subtle` |
+| `tone` | `secondary`, `accent`, `success`, `warning`, `danger` | `secondary` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `connector` | `solid`, `dashed`, `none` | — |
+| `growing` | `none`, `button`, `scroll` | `none` |
+| `timeFormat` | `absolute`, `relative` | `absolute` |
+| `level` | `2`, `3`, `4`, `5`, `6` | `3` |
+
+## Rules
+
+- Em list a lista é uma ol e cada evento um li: a sequência e o tamanho do conjunto vêm da plataforma sem uma linha de ARIA, e o teclado é o dos links e botões que o consumidor escrever. Não há papel inventado numa lista que não cresce.
+- Em feed a lista é role="feed" e cada evento um article com tabindex="0", aria-posinset, aria-setsize — o total declarado, o carregado quando não cresce, -1 quando pode crescer — aria-labelledby com título, ator e hora por esta ordem, e aria-describedby com a descrição. É o padrão Feed do APG item a item, e um li não admite o papel article: por isso o elemento muda com o modo.
+- O evento atual leva aria-current="true" e uma visually-hidden com a mensagem current a seguir ao título, porque nem todo leitor de ecrã diz aria-current dentro de um artigo. Concluído e a carregar são formas — um disco com check, o anel do spinner — e não só cores.
+- Um grupo collapsible é o padrão Disclosure: o heading contém um button com aria-expanded e aria-controls, e a lista fechada recebe hidden sem sair do DOM. O nome do botão é o período seguido de ", Show events" ou ", Hide events": as mensagens expand e collapse trazem o seu próprio separador.
+- A hora é sempre um elemento time com datetime, o valor que o leitor de ecrã e o motor de busca leem; o texto é do locale e do fuso declarados, e uma leitura relativa deixa a absoluta em title.
+- Os eventos novos são anunciados em polite uma vez por mudança de contagem, e ficam atrás de um botão até o leitor os pedir, para nada se mover debaixo do que está a ser lido.
+
+## Tokens
+
+`--slotted-avatar-size-xs`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--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-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-line-height`, `--slotted-control-padding-inline-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-duration-instant`, `--slotted-duration-medium`, `--slotted-easing-standard`, `--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-semibold`, `--slotted-line-height-md`, `--slotted-radius-full`, `--slotted-space-1`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-surface`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-timeline-color`, `--slotted-timeline-color-muted`, `--slotted-timeline-connector-color`, `--slotted-timeline-connector-thickness`, `--slotted-timeline-content-gap`, `--slotted-timeline-core-ratio`, `--slotted-timeline-font-family`, `--slotted-timeline-font-size`, `--slotted-timeline-gap`, `--slotted-timeline-group-gap`, `--slotted-timeline-group-weight`, `--slotted-timeline-item-gap`, `--slotted-timeline-line-gap`, `--slotted-timeline-line-height`, `--slotted-timeline-marker-border`, `--slotted-timeline-marker-surface`, `--slotted-timeline-meta-font-size`, `--slotted-timeline-opposite-size`, `--slotted-timeline-radius`, `--slotted-timeline-state-layer-active`, `--slotted-timeline-state-layer-hover`, `--slotted-timeline-time-font-size`, `--slotted-timeline-title-weight`, `--slotted-timeline-track-min`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Um feed que é um feed
+
+Com mode="feed" a lista é role="feed" e cada evento um article com aria-posinset, aria-setsize e o rótulo lido do título, do ator e da hora. Tab para em cada artigo; PageDown e PageUp saltam entre eles.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slTimeline
+  mode="feed"
+  growing="button"
+  label="Atividade"
+  [count]="120"
+  (loadMoreRequest)="load()"
+>
+  <div slTimelineList>
+    @for (event of events; track event.id) {
+      <article slTimelineItem [title]="event.title" [time]="event.time"></article>
+    }
+  </div>
+</div>
+```
+
+### De que lado da linha
+
+end é a omissão; start espelha a fila; alternate põe a linha ao meio e os eventos revezam-se. A parte opposite ocupa sempre o lado que o corpo não ocupa, e abaixo de trinta rems alternate volta a um lado só.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline placement="alternate">
+  <ol slTimelineList>
+    <li slTimelineItem title="2.12 — Faturas recorrentes">
+      <div slTimelineOpposite><time slTimelineTime value="2026-06-02T00:00:00Z"></time></div>
+    </li>
+  </ol>
+</div>
+```
+
+### Uma fila de eventos
+
+horizontal põe a linha de lado, com colunas iguais que rolam no eixo em linha quando há mais eventos do que largura. Abaixo de trinta rems da sua própria largura volta a ser uma coluna; reflow={false} desliga isso.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline orientation="horizontal" autoComplete>
+  <ol slTimelineList>
+    <li slTimelineItem title="Pedido confirmado"></li>
+    <li slTimelineItem current title="Em trânsito"></li>
+  </ol>
+</div>
+```
+
+### A ordem é declarada, nunca invertida
+
+order diz o que a lista é e não reordena o array: o consumidor ordena. É a ordem que decide onde autoComplete corta — em oldest-first o passado está antes do atual, em newest-first depois.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline order="newest-first" autoComplete>
+  <ol slTimelineList>
+    <li slTimelineItem title="Entregue"></li>
+    <li slTimelineItem current title="Em trânsito"></li>
+    <li slTimelineItem title="Embalado"></li>
+  </ol>
+</div>
+```
+
+### O que um evento pode ser
+
+Cada estado é uma forma além de uma cor: pendente é a forma do variant, atual é um disco cheio com um anel, concluído é um disco cheio com um check vazado, a carregar é o spinner do tamanho do ponto. autoComplete deriva concluído para o lado passado do atual e traceja o futuro.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline tone="accent" autoComplete>
+  <ol slTimelineList>
+    <li slTimelineItem title="Pedido confirmado"></li>
+    <li slTimelineItem current title="Em trânsito"></li>
+    <li slTimelineItem title="Saiu para entrega"></li>
+    <li slTimelineItem loading title="Entregue"></li>
+  </ol>
+</div>
+```
+
+### Aparência e tamanho
+
+variant na raiz ou por evento: outline separa o marcador da linha em qualquer esquema, solid enche, subtle é um fundo com aresta fina, plain é o ponto sem anel para uma fila de eventos pequenos. tone pinta o marcador com um dos cinco tons; size escolhe o passo.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline size="sm" variant="plain">
+  <ol slTimelineList>
+    <li slTimelineItem title="Commit 4f2a"></li>
+    <li slTimelineItem title="Falha nos testes" tone="danger" variant="solid"></li>
+  </ol>
+</div>
+```
+
+### Agrupar por período
+
+O consumidor agrupa, porque o período é do domínio. Um grupo é um heading do nível declarado sobre a sua própria lista; collapsible faz do heading um botão com aria-expanded, e a lista fechada fica no DOM com hidden.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline [level]="3">
+  <ol slTimelineList>
+    <li slTimelineGroup label="Hoje" collapsible>
+      <ol slTimelineGroupList>
+        <li slTimelineItem title="Paga"></li>
+      </ol>
+    </li>
+    <li slTimelineGroup label="Semana passada" collapsible [defaultOpen]="false">
+      <ol slTimelineGroupList>
+        <li slTimelineItem title="Enviada"></li>
+      </ol>
+    </li>
+  </ol>
+</div>
+```
+
+### Carregar mais
+
+growing="button" põe um botão no fim do carregado e pede com pointer ou keyboard; growing="scroll" pede com scroll quando o fim entra no rolador. Enquanto loading, o fim mostra o anel e a raiz fica aria-busy.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline growing="button" [loading]="pending" (loadMoreRequest)="fetchMore($event.reason)">
+  <ol slTimelineList>
+    @for (event of events; track event.id) {
+      <li slTimelineItem [title]="event.title"></li>
+    }
+  </ol>
+</div>
+```
+
+### Eventos novos enquanto o leitor lê
+
+Um feed que insere no topo empurra o que está a ser lido. Com freshCount, a família segura os novos atrás de uma pílula, anuncia a contagem em polite, e (revealRequest) é o momento em que o consumidor os junta ao array. A pílula sai com transição, e o foco que estava nela passa ao primeiro evento revelado.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline mode="feed" [freshCount]="held.length" (revealRequest)="reveal()">
+  <div slTimelineList>
+    @for (event of events; track event.id) {
+      <article slTimelineItem [title]="event.title"></article>
+    }
+  </div>
+</div>
+```
+
+### Hora de máquina, fuso explícito
+
+time aceita um instante ISO com designador de fuso, escrito no timeZone declarado, ou um valor de parede sem fuso, escrito como está. datetime leva sempre o valor de máquina; timeFormat="relative" escreve "há 2 horas" e guarda o absoluto em title.
+
+Excerpt — not a complete module
+
+```ts
+providers: [
+  provideSlotted({ locale: 'pt-BR' }),
+  provideTimelineDefaults({ now: Date.now(), timeZone: 'America/Sao_Paulo' }),
+];
+
+// <div slTimeline timeFormat="relative">
+//   <ol slTimelineList>
+//     <li slTimelineItem time="2026-09-14T10:32:00Z" title="Paga"></li>
+//   </ol>
+// </div>
+```
+
+### Conteúdo que a família não escolheu
+
+Um título de nove palavras, uma referência sem quebra, um título em árabe, um avatar no marcador, um evento sem título. O marcador nunca sai da primeira linha e a linha nunca sai do centro.
+
+Excerpt — not a complete module
+
+```html
+<li slTimelineItem title="Aprovou a cotação revista do programa de remessas">
+  <span slTimelineMarker slAvatar name="Ana Ribeiro"></span>
+</li>
+```
+
+### Composição
+
+O título é o que o consumidor lhe der — um Link — e as ações são botões da família button. Conteúdo expansível é um Collapsible dentro do corpo. exportAs alcança a lista e focusItem(index) para o feed, e provideTimelineDefaults decide uma vez para o injector.
+
+Excerpt — not a complete module
+
+```html
+<li slTimelineItem>
+  <a slTimelineTitle slLink href="/faturas/4821">Pagamento falhou</a>
+  <div slCollapsible variant="plain">
+    <h4 slCollapsibleHeader><button slCollapsibleTrigger>Ver resposta do emissor</button></h4>
+    <div slCollapsiblePanel>Código 05: não honrar.</div>
+  </div>
+  <div slTimelineActions><button slButton size="sm">Repetir</button></div>
+</li>
+```
+
+### Sem eventos
+
+Sem itens e sem loading, a parte empty toma o lugar da lista com a mensagem da família ou com o que o consumidor projetar — um result-state, por exemplo.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeline label="Atividade">
+  <ol slTimelineList></ol>
+  <div slTimelineEmpty slResultState status="empty">
+    <div slResultStateContent><p slResultStateTitle>Ainda sem eventos</p></div>
+  </div>
+</div>
+```
+
+### Teclado
+
+Em list o teclado é o da plataforma: Tab atravessa os links e botões do corpo. Em feed, Tab para em cada artigo, PageDown e PageUp saltam entre artigos, Control+End e Control+Home saem do feed para o focável seguinte ou anterior.
+
+Excerpt — not a complete module
+
+```html
+<!-- "Paga, Solaris Fretes, há 2 horas, artigo 1 de 3": título, ator e hora, e a posição. -->
+<div slTimeline mode="feed" label="Atividade">
+  <div slTimelineList>
+    <article
+      slTimelineItem
+      title="Paga"
+      actor="Solaris Fretes"
+      time="2026-09-14T13:32:00Z"
+    ></article>
+  </div>
+</div>
+```