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

package/dist/docs/message.md

@@ -0,0 +1,479 @@
+<!-- index: ./index.md -->
+# message
+
+`data-ui="message"` · Chat message with author, bubble and actions.
+
+## Import
+
+```tsx
+import { Bubble, BubbleCaret, BubbleContent, BubbleMeta, BubbleQuote, BubbleReaction, BubbleReactions, BubbleRetry, BubbleStream, BubbleTyping, Message, MessageActions, MessageActivity, MessageActivityStep, MessageAuthor, MessageAvatar, MessageBody, MessageDefaultsProvider, MessageFooter, MessageGroup, MessageHeader, MessageReceipt, MessageTime, MessageVersions } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Message align="start" status="read">
+  <MessageBody>
+    <Bubble>
+      <BubbleContent>O payout de terça voltou com o erro R03.</BubbleContent>
+    </Bubble>
+  </MessageBody>
+</Message>;
+```
+
+## Anatomy
+
+### message
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | article | yes |
+| `group` | div | no |
+| `avatar` | div | no |
+| `body` | div | yes |
+| `header` | div | no |
+| `author` | span | no |
+| `time` | time | no |
+| `footer` | div | no |
+| `receipt` | span | no |
+| `actions` | div | no |
+| `activity` | div | no |
+| `activity-step` | div | no |
+| `versions` | div | no |
+| `version-previous` | button | no |
+| `version-label` | span | no |
+| `version-next` | button | no |
+
+### bubble
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `content` | div, button or a | yes |
+| `meta` | span | no |
+| `quote` | div or button | no |
+| `quote-author` | span | no |
+| `more` | button | no |
+| `stream` | span | no |
+| `stream-chunk` | span | no |
+| `caret` | span | no |
+| `typing` | span | no |
+| `retry` | button | no |
+| `reactions` | div | no |
+| `reaction` | button | no |
+| `reaction-count` | span | no |
+
+## Props
+
+### message
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `align` | `'start' \| 'end'` | start | Message | The sender’s side; end is the reader’s own message |
+| `layout` | `'bubble' \| 'thread'` | bubble | Message, MessageGroup | Bubbles, or rows of a comment thread. Falls back to the group, then the provider |
+| `actionsVisibility` | `'always' \| 'hover'` | hover | Message | Actions at rest, or revealed by pointer, focus and on touch |
+| `status` | `'sending' \| 'sent' \| 'delivered' \| 'read' \| 'failed' \| 'streaming'` | — | Message | Delivery: aria-busy and data-loading while sending or streaming, data-invalid when failed, data-read when read |
+| `version` | `number` | — | Message | The version on screen, from 0. Present means controlled |
+| `defaultVersion` | `number` | 0 | Message | The version an uncontrolled message starts on |
+| `versionCount` | `number` | 1 | Message | How many versions exist; the pager draws with two or more |
+| `onRetry` | `(request) => void` | — | Message | Asks to send the message again; BubbleRetry calls it |
+| `messages` | `PartialMessages<MessageMessages>` | — | Message | Words laid over the language in force, key by key, for the row and every part and bubble inside it; a bubble outside a row speaks the language in force |
+| `status` | `'sending' \| 'sent' \| 'delivered' \| 'read' \| 'failed'` | the row’s | MessageReceipt | The receipt’s own status |
+| `status` | `'complete' \| 'current' \| 'pending'` | current | MessageActivityStep | Done with a tick, in progress with the ring, or waiting |
+| `dateTime` | `string` | — | MessageTime | The time element’s own machine-readable value |
+| `render` | `(props) => ReactNode` | — | every part | Renders the wiring into another element; spread it |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the native element |
+| `MessageDefaultsProvider` | `{ layout, actionsVisibility, variant, tone }` | — | a subtree | Sets them once; a group, a row or a bubble still wins |
+| `aria-label` | `string` | — | Message | Replaces the author as the article’s name |
+| `render` | `(props) => ReactNode` | — | every part | The consumer element receives data-part and the wiring |
+| `onKeyDown` | `handler` | — | MessageVersions | Composed: preventDefault keeps the arrow from the pager |
+
+### bubble
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `variant` | `'solid' \| 'soft' \| 'outline' \| 'plain'` | soft | Bubble | The painting. Falls back to the row (end is solid, thread is plain), then the provider |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | secondary | Bubble | The tone. Falls back to the row (end is accent), then the provider |
+| `maxLines` | `number` | — | Bubble | Lines shown before the text is clamped behind “Show more” |
+| `revealed` | `boolean` | — | Bubble | The clamped text shown whole. Present means controlled |
+| `defaultRevealed` | `boolean` | false | Bubble | Whether an uncontrolled clamp starts open |
+| `pressed` | `boolean` | — | BubbleReaction | The reader’s own reaction. Present means controlled |
+| `defaultPressed` | `boolean` | false | BubbleReaction | Whether an uncontrolled reaction starts pressed |
+| `count` | `number` | — | BubbleReaction | The count the consumer’s store holds |
+| `text` | `string` | — | BubbleStream | The whole reply received so far; text that extends it enters word by word |
+| `animate` | `boolean` | the row is streaming | BubbleStream | Let arrivals enter; the arrival that ends the stream enters too |
+| `disabled` | `boolean` | false | BubbleReaction | The native disabled; the reaction stays legible |
+| `author` | `ReactNode` | — | BubbleQuote | The quoted message’s author |
+| `onJump` | `(event) => void` | — | BubbleQuote | Makes the quote a button that jumps to the quoted message |
+| `aria-label` | `string` | typing message | BubbleTyping | The dots’ accessible name; the typing message when absent |
+| `render` | `(props) => ReactNode` | — | Bubble, BubbleContent, BubbleMeta, BubbleQuote, BubbleStream, BubbleCaret, BubbleRetry, BubbleReactions | Renders the wiring into another element — the surface as a button or a link |
+| `MessageDefaultsProvider` | `{ variant, tone }` | — | a subtree | The painting of a bubble nothing infers |
+| `render` | `(props) => ReactNode` | — | BubbleContent | A button or an a keeps the painting, the states and the ring |
+| `onClick` | `handler` | — | BubbleRetry, BubbleReaction | Composed: runs first, preventDefault refuses the family’s request |
+
+## Events
+
+### message
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onVersionChange` | `(version: number, request: ChangeRequest<number>)` | Before the version moves, bounded to the range. reason is pointer for a press and keyboard for Enter, Space or an arrow. cancel() keeps the version. |
+| `onRetry` | `(request: { reason, source })` | When BubbleRetry is pressed, after the consumer’s own onClick; nothing is committed, the message is the consumer’s to send again. |
+
+### bubble
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onRevealedChange` | `(revealed: boolean, request: ChangeRequest<boolean>)` | Before a clamped text opens or closes, from the more control. reason is pointer or keyboard; cancel() keeps it. |
+| `onPressedChange` | `(pressed: boolean, request: ChangeRequest<boolean>)` | On BubbleReaction, before the reader’s own reaction toggles. The count stays the consumer’s. |
+| `onJump` | `(event)` | On BubbleQuote, when the quote is pressed; the page scrolls to the quoted message. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `align` | `start`, `end` | `start` |
+| `layout` | `bubble`, `thread` | `bubble` |
+| `actionsVisibility` | `always`, `hover` | `hover` |
+| `status` | `sending`, `sent`, `delivered`, `read`, `failed`, `streaming` | — |
+| `variant` | `solid`, `soft`, `outline`, `plain` | `soft` |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `secondary` |
+
+## Rules
+
+- Each message is an article labelled by its author, so a screen reader that moves between articles hears who spoke; an aria-label on the row replaces the author.
+- Delivery is said three ways: a state attribute for styling, a mark for the eye, and a word for assistive technology — the word inside a bubble’s meta is visually hidden, and outside a bubble it is the only thing drawn.
+- A message that is sending or streaming is aria-busy, so its words are not announced as they land; the scroller’s log announces the finished row once.
+- The actions are a toolbar named Message actions; revealed by hover, they also appear on focus inside the row and are always painted where the pointer cannot hover.
+- The activity is a status region; the current step carries aria-current="step", and its travelling band stops under reduced motion.
+- The version pager is a group with two named buttons and a polite live label; the buttons disable at the ends rather than wrapping.
+- A bubble paints; it adds no role. A surface rendered as a button or an a is that element, so its name is its words and it keeps the platform’s keys.
+- Painting is never the only signal: a danger bubble says its failure in words, the reader’s own side is the row’s alignment, and a reaction’s pressed state is aria-pressed.
+- “Show more” is a button with aria-expanded and aria-controls on the surface; the clamped text is never removed from the DOM.
+- The typing dots are one image with a name, and the caret is aria-hidden: neither is read as characters.
+- The retry control is named Try sending again and sits beside the surface it resends, after it in the reading order.
+
+## Tokens
+
+`--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-gap-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-md`, `--slotted-control-radius`, `--slotted-disabled-foreground`, `--slotted-duration-long`, `--slotted-duration-loop`, `--slotted-duration-loop-slow`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-emphasized`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--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-regular`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-message-avatar-size`, `--slotted-message-bubble-padding-block`, `--slotted-message-bubble-padding-inline`, `--slotted-message-bubble-radius`, `--slotted-message-bubble-radius-joined`, `--slotted-message-bubble-share`, `--slotted-message-column-gap`, `--slotted-message-retry-state-layer`, `--slotted-message-run-gap`, `--slotted-message-stack-gap`, `--slotted-message-state-layer-active`, `--slotted-message-state-layer-hover`, `--slotted-message-thread-avatar-size`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-shadow-sm`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-surface`, `--slotted-surface-raised`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--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-solid-active`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--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-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
+
+### Two sides, asked once
+
+align lives on the row. A bubble in an end row paints the accent’s fill by itself; a bubble in a start row the secondary tint. Nothing is repeated on the bubble.
+
+Excerpt — not a complete module
+
+```tsx
+<Message align="end">
+  <MessageBody>
+    <Bubble>
+      <BubbleContent>Ótimo. Reenvio assim que chegar.</BubbleContent>
+    </Bubble>
+  </MessageBody>
+</Message>;
+```
+
+### The avatar at the foot of the words
+
+The avatar sits on the line of the last bubble, not of the footer under it, and moves to the end side with the row. It is the avatar family’s small step, so it follows the density.
+
+Excerpt — not a complete module
+
+```tsx
+<Message>
+  <MessageAvatar>
+    <Avatar name="Marta Silva" size="sm" />
+  </MessageAvatar>
+  <MessageBody>
+    <Bubble>
+      <BubbleContent>Chega hoje à tarde.</BubbleContent>
+    </Bubble>
+  </MessageBody>
+</Message>;
+```
+
+### A run from one sender
+
+Three rows, one avatar on the last. The rows stand two pixels apart and the corners facing each other on the sender’s side draw in to four; the earlier rows keep the avatar column without an empty slot.
+
+Excerpt — not a complete module
+
+```tsx
+<MessageGroup>
+  <Message>
+    <MessageBody>
+      <Bubble>
+        <BubbleContent>O payout de terça voltou com o erro R03.</BubbleContent>
+      </Bubble>
+    </MessageBody>
+  </Message>
+  <Message>
+    <MessageAvatar>
+      <Avatar name="Marta Silva" size="sm" />
+    </MessageAvatar>
+    <MessageBody>
+      <Bubble>
+        <BubbleContent>Chega hoje à tarde.</BubbleContent>
+      </Bubble>
+    </MessageBody>
+  </Message>
+</MessageGroup>;
+```
+
+### Who spoke, and when
+
+The header sets the name on the inset of the words, so the name stands over the first letter it names. The dot between name and hour is drawn by the stylesheet and never read aloud.
+
+Excerpt — not a complete module
+
+```tsx
+<MessageHeader>
+  <MessageAuthor>Marta Silva</MessageAuthor>
+  <MessageTime dateTime="2026-09-30T09:38">09:38</MessageTime>
+</MessageHeader>;
+```
+
+### Where a message is in its delivery
+
+Inside the bubble the hour and the mark ride at the end of the last line: a breathing clock while sending, one tick, two ticks, and two ticks in full ink once read. A message that did not go says so in a word under it, with the retry control beside it.
+
+Excerpt — not a complete module
+
+```tsx
+<Message align="end" status="read">
+  <MessageBody>
+    <Bubble>
+      <BubbleContent>
+        E marco a fatura como paga só depois do crédito.
+        <BubbleMeta>
+          <MessageTime dateTime="2026-09-30T09:41">09:41</MessageTime>
+          <MessageReceipt />
+        </BubbleMeta>
+      </BubbleContent>
+    </Bubble>
+  </MessageBody>
+</Message>;
+```
+
+### Actions the row reveals
+
+With actionsVisibility="hover" the toolbar keeps its room and appears under the pointer and on focus anywhere in the row; on a screen that cannot hover it is always painted. Tab into the row to see it arrive.
+
+Excerpt — not a complete module
+
+```tsx
+<MessageFooter>
+  <MessageActions>
+    <IconButton aria-label="Copiar" variant="ghost" size="sm">
+      <Icon>
+        <Glyph name="copy" />
+      </Icon>
+    </IconButton>
+  </MessageActions>
+</MessageFooter>;
+```
+
+### What a reply is doing before it has words
+
+Steps done carry a tick and step back into the muted ink; the current one carries the shared ring and a band of light across its words. Under reduced motion the band stops and the words stand in the plain ink.
+
+Excerpt — not a complete module
+
+```tsx
+<Message status="streaming">
+  <MessageBody>
+    <MessageActivity>
+      <MessageActivityStep status="complete">Li o registo das 14:00 às 14:10</MessageActivityStep>
+      <MessageActivityStep>A procurar a causa do p95…</MessageActivityStep>
+    </MessageActivity>
+  </MessageBody>
+</Message>;
+```
+
+### Versions of one reply
+
+The pager draws with two or more versions and stops at both ends. ArrowLeft and ArrowRight page from either control, mirrored in a right-to-left page; the label is a polite live region.
+
+Excerpt — not a complete module
+
+```tsx
+<Message versionCount={3} version={version} onVersionChange={setVersion}>
+  <MessageBody>
+    <Bubble>
+      <BubbleContent>{drafts[version]}</BubbleContent>
+    </Bubble>
+    <MessageFooter>
+      <MessageVersions />
+    </MessageFooter>
+  </MessageBody>
+</Message>;
+```
+
+### A comment thread
+
+layout="thread" sets every row at the start with the avatar at the top, the name inline, the words unframed and a band under the pointer; the actions float at the row’s top end on a raised plate.
+
+Excerpt — not a complete module
+
+```tsx
+<Message layout="thread">
+  <MessageAvatar>
+    <Avatar name="Emília Parker" />
+  </MessageAvatar>
+  <MessageBody>
+    <MessageHeader>
+      <MessageAuthor>Emília Parker</MessageAuthor>
+      <MessageTime dateTime="2026-09-30T09:12">há 4 minutos</MessageTime>
+    </MessageHeader>
+    <Bubble>
+      <BubbleContent>Podemos nomear o dono do SSO antes da revisão?</BubbleContent>
+    </Bubble>
+  </MessageBody>
+</Message>;
+```
+
+### Playground
+
+One bubble with its variant, tone and clamp on the controls. A bubble outside a row takes the provider’s painting; inside one it takes the row’s side.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble variant="soft" tone="secondary">
+  <BubbleContent>A conta de destino não existe no banco.</BubbleContent>
+</Bubble>;
+```
+
+### Four paintings
+
+solid is the tone’s fill, soft its tint with a rim that shows only in high contrast, outline its edge on the page, plain no box at all — the unframed answer that takes the whole row.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble variant="solid" tone="accent">
+  …
+</Bubble>;
+<Bubble variant="soft">…</Bubble>;
+<Bubble variant="outline">…</Bubble>;
+<Bubble variant="plain">…</Bubble>;
+```
+
+### Five tones
+
+accent and secondary write in the page’s ink; success, warning and danger in their own, because there the colour of the words is the point — and the words say it too.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble tone="danger">
+  <BubbleContent>O passo 5 falhou e o worker não voltou.</BubbleContent>
+</Bubble>;
+```
+
+### Quick replies and links
+
+render turns the surface itself into a button or an a, and it keeps the painting, the hover, a distinct press and the focus ring. A link keeps middle-click and its destination.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble tone="accent">
+  <BubbleContent render={(props) => <button type="button" {...props} onClick={retryAll} />}>
+    Reenviar as duas agora
+  </BubbleContent>
+</Bubble>;
+```
+
+### Replying to a message
+
+The quote heads the surface in a block tinted with the surface’s own ink, author over up to three lines. With onJump it is a button that asks the scroller to take the reader to the quoted message.
+
+Excerpt — not a complete module
+
+```tsx
+<BubbleContent>
+  <BubbleQuote
+    author="Marta Silva"
+    onJump={() => scroller.current?.scrollToMessage('m2', { highlight: true })}
+  >
+    A conta de destino não existe no banco.
+  </BubbleQuote>
+  Manda-me o IBAN quando chegar.
+</BubbleContent>;
+```
+
+### A long reply, clamped
+
+maxLines shows the first lines and draws “Show more” only while the text overflows. The whole text stays in the DOM for copying and finding in the page; the chevron turns as it opens.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble maxLines={3}>
+  <BubbleContent>{longAnswer}</BubbleContent>
+</Bubble>;
+```
+
+### A reply while it streams
+
+Words arrive in bursts. BubbleStream splits each arrival into words, and a burst enters as a wave of at most 320 ms, each word out of a blur; nothing is held back from the DOM. The dot breathes after the last word. The row is aria-busy, so the words are not read as they land. Under reduced motion every word lands settled and the dot stands lit.
+
+Excerpt — not a complete module
+
+```tsx
+<Message status="streaming">
+  <MessageBody>
+    <Bubble>
+      <BubbleContent>
+        <BubbleStream text={received} />
+        <BubbleCaret />
+      </BubbleContent>
+    </Bubble>
+  </MessageBody>
+</Message>;
+```
+
+### Someone is writing
+
+Three dots rise and brighten in a wave in the writer’s bubble, which trails two circles of its own fill and edge and arrives rising from them. It is one image named for assistive technology.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble>
+  <BubbleContent>
+    <BubbleTyping aria-label="Marta is typing" />
+  </BubbleContent>
+</Bubble>;
+```
+
+### Reactions
+
+The pill straddles the lower edge on the side away from the sender and rises into the surface by half its inset, clear of the words. The reader’s own reaction takes the accent’s tint and edge; a disabled one stays legible.
+
+Excerpt — not a complete module
+
+```tsx
+<BubbleReactions>
+  <BubbleReaction count={4} defaultPressed>
+    👍
+  </BubbleReaction>
+</BubbleReactions>;
+```
+
+### Content nobody chose
+
+A URL of a hundred characters breaks where it must instead of pushing the bubble past its share; an Arabic line in a Portuguese thread reads from its own side; a two-letter reply is still a bubble, not a pill.
+
+Excerpt — not a complete module
+
+```tsx
+<Bubble>
+  <BubbleContent>{text}</BubbleContent>
+</Bubble>;
+```