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

package/dist/docs/timeline.md

@@ -0,0 +1,346 @@
+<!-- index: ./index.md -->
+# timeline
+
+`data-ui="timeline"` · Events in time order with markers.
+
+## Import
+
+```tsx
+import {
+  Timeline,
+  TimelineDefaultsProvider,
+  TimelineGroup,
+  TimelineItem,
+  TimelineTime,
+  useTimeline,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Timeline label="Atividade da fatura" locale="pt-BR" timeZone="America/Sao_Paulo">
+  <TimelineItem
+    actor="Ana Ribeiro"
+    description="Rascunho INV-4821 para Solaris Fretes."
+    time="2026-09-08T09:12:00Z"
+    title="Fatura criada"
+  />
+  <TimelineItem current time="2026-09-14T10:32:00Z" title="Paga" tone="success" />
+</Timeline>;
+```
+
+## 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 (SlottedProvider) |
+| `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 |
+| `labelledBy` | `string` | — | Timeline | O id do elemento que nomeia a lista |
+| `empty` | `ReactNode` | — | Timeline | O que fica no lugar da lista vazia |
+| `messages` | `PartialMessages<TimelineMessages>` | — | Timeline | Palavras sobre o catálogo da língua em vigor, chave a chave: as sete mensagens da família |
+| `label` | `ReactNode` | — | TimelineGroup | O nome do período, como heading |
+| `collapsible` | `boolean` | false | TimelineGroup | Se o heading é um botão que dobra o grupo |
+| `open` | `boolean` | — | TimelineGroup | 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` | `ReactNode` | — | TimelineItem | O nome do evento |
+| `description` | `ReactNode` | — | TimelineItem | A segunda linha |
+| `actor` | `ReactNode` | — | TimelineItem | Quem o fez |
+| `time` | `PlainDateTime \| string` | — | TimelineItem | Quando: instante ISO ou valor de parede |
+| `timeLabel` | `ReactNode` | — | TimelineItem | O texto no lugar da hora formatada |
+| `marker` | `ReactNode` | — | TimelineItem | O que o marcador segura no lugar do ponto |
+| `opposite` | `ReactNode` | — | TimelineItem | O outro lado da linha |
+| `actions` | `ReactNode` | — | 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 |
+| `render` | `(props) => ReactNode` | — | Timeline, TimelineGroup, TimelineItem | Substitui o elemento renderizado. Todo atributo de dados é entregue, e um article do feed leva o seu role. |
+| `ref` | `Ref<HTMLElement>` | — | todas as partes | Alcança o elemento |
+| `useTimeline()` | `() => TimelineContextValue` | — | dentro de uma Timeline | Os eixos resolvidos, as mensagens, e focusItem(index) — mover o foco a um artigo do feed, a ação que uma prop não exprime |
+| `TimelineTime` | `{ 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 |
+| `TimelineDefaultsProvider` | `mode \| orientation \| placement \| order \| variant \| tone \| size \| growing \| timeFormat \| timeZone \| now \| level` | — | Aplicação | Decide os catorze uma vez para tudo por baixo; uma prop na linha do tempo ganha |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `(open: boolean, request: ChangeRequest<boolean>)` | Em TimelineGroup, antes de o grupo abrir ou fechar. O pedido leva o valor anterior, a razão — pointer, keyboard ou programmatic — e o evento de origem; cancelá-lo não move nada. |
+| `onLoadMore` | `(reason: "pointer" \| "keyboard" \| "scroll", 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. |
+| `onReveal` | `(reason: "pointer" \| "keyboard", 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
+
+```tsx
+<Timeline count={120} growing="button" label="Atividade" mode="feed" onLoadMore={load}>
+  {events.map((event) => (
+    <TimelineItem key={event.id} {...event} />
+  ))}
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline placement="alternate">
+  <TimelineItem
+    opposite={<TimelineTime value="2026-06-02T00:00:00Z" />}
+    title="2.12 — Faturas recorrentes"
+  />
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline autoComplete orientation="horizontal">
+  {stages}
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline autoComplete order="newest-first">
+  <TimelineItem title="Entregue" />
+  <TimelineItem current title="Em trânsito" />
+  <TimelineItem title="Embalado" />
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline autoComplete tone="accent">
+  <TimelineItem title="Pedido confirmado" />
+  <TimelineItem current title="Em trânsito" />
+  <TimelineItem title="Saiu para entrega" />
+  <TimelineItem loading title="Entregue" />
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline size="sm" variant="plain">
+  <TimelineItem title="Commit 4f2a" />
+  <TimelineItem title="Falha nos testes" tone="danger" variant="solid" />
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline level={3}>
+  <TimelineGroup collapsible label="Hoje">
+    <TimelineItem title="Paga" />
+  </TimelineGroup>
+  <TimelineGroup collapsible defaultOpen={false} label="Semana passada">
+    <TimelineItem title="Enviada" />
+  </TimelineGroup>
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<Timeline growing="button" loading={pending} onLoadMore={(reason) => fetchMore()}>
+  {events}
+</Timeline>;
+```
+
+### 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 onReveal é 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
+
+```tsx
+<Timeline freshCount={held.length} mode="feed" onReveal={() => setEvents([...held, ...events])}>
+  {events}
+</Timeline>;
+```
+
+### 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
+
+```tsx
+<SlottedProvider locale="pt-BR">
+  <TimelineDefaultsProvider now={Date.now()} timeZone="America/Sao_Paulo">
+    <Timeline timeFormat="relative">
+      <TimelineItem time="2026-09-14T10:32:00Z" title="Paga" />
+    </Timeline>
+  </TimelineDefaultsProvider>
+</SlottedProvider>;
+```
+
+### 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
+
+```tsx
+<TimelineItem
+  marker={<Avatar name="Ana Ribeiro" />}
+  title="Aprovou a cotação revista do programa de remessas"
+/>;
+```
+
+### 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. useTimeline() dá focusItem para o feed, e TimelineDefaultsProvider decide uma vez para a aplicação.
+
+Excerpt — not a complete module
+
+```tsx
+<TimelineItem
+  actions={<Button size="sm">Repetir</Button>}
+  title={<Link href="/faturas/4821">Pagamento falhou</Link>}
+>
+  <Collapsible variant="plain">
+    <Collapsible.Trigger>Ver resposta do emissor</Collapsible.Trigger>
+    <Collapsible.Panel>Código 05: não honrar.</Collapsible.Panel>
+  </Collapsible>
+</TimelineItem>;
+```
+
+### 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
+
+```tsx
+<Timeline empty={<ResultState status="empty" title="Ainda sem eventos" />} />;
+```
+
+### 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
+
+```tsx
+// "Paga, Solaris Fretes, há 2 horas, artigo 1 de 3" — título, ator e hora,
+// e a posição, porque cada artigo leva aria-labelledby e aria-posinset.
+<Timeline label="Atividade" mode="feed">
+  {events}
+</Timeline>;
+```