unmagic-components 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c204e77700223b87a5c4a2d019bb285de3dd24f9a9c1530aa54dd4b798f171a7
-  data.tar.gz: 91b9db1448f9a74a259a565e7d8ac0d4db6cb75927f3680a0914517666134011
+  metadata.gz: 9c4fbdc3dbc2a5dbba7758240b2c0fa271c81f46e00435e898ad179f23ce1937
+  data.tar.gz: 1ce6acc98aecc0153da190eca815d5ca469e6e46c0fe61bdd8b1fc75dd437e10
 SHA512:
-  metadata.gz: af2099fb9686c1b87742f79a07ee892a7dc3b8c984f93b684eb3a51355c82b793369230857ff9f8e5eff2ee24e7fda85d482f215126eb6ba7df59a3c62cd7aa9
-  data.tar.gz: a975d65b9b5575e6cbb2768dd22232f8c20291eecfcb7984fc075b6d6c2acefd1e56f558d3ca96a92329ae24588cc35042d780ecd1a2558d2fc7abe8e3aa3323
+  metadata.gz: 2cbcb4011c8504a0247e3a26d49042da521e22ccc658615049e7bdfc7ec9411fa86f984acb2abc9e59a99bc398c245dd03f99de30616f00c2a5ecc49ed688251
+  data.tar.gz: 6599c73d2d0c5846a8b5206e3df0071b31c8d958f88b3e21dcbdda761c48820c1f2a1854762c99ce09b6f360985be017a10c007be5887c26a5ae5c097ca4807a

data/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-16
+
+### Added
+
+- `Unmagic::Components::Browser::Engine`, a component browser a host mounts
+  (`mount Unmagic::Components::Browser::Engine => "/unmagic/components"`). It is
+  the preview app, moved into the gem: every component, its examples and their
+  source. It ships a prebuilt stylesheet and serves the components' JavaScript
+  and Turbo itself, so a host changes nothing else. It needs turbo-rails.
+  `bin/dev` now runs it from a one-file host.
+- `trailing` on the page header builder puts markup beside the title as it is —
+  a status partial, a row of badges a helper already returned. `badge` wraps what
+  it is given, so an already-rendered one routed through it came out as a badge
+  inside a badge; this is the counterpart to `leading`, and the two interleave in
+  call order.
+- `sortable_list` and `sortable_handle`: drag-and-drop ordering by pointer or
+  keyboard, extracted from hooops.
+  - Elements `<unmagic-sortable-list>`, `<unmagic-sortable-item>` and
+    `<unmagic-sortable-param>`.
+  - Keyboard reordering with announcements.
+  - Scrolling at the edges, Escape to cancel, and nested lists.
+  - A cancelable `unmagic-sortable:move` event.
+  - Touch: a long press lifts an item, so swipes still scroll and taps still
+    tap; a grip drags at once.
+  - `sortable-*` Tailwind variants.
+  - `config.sortable_item` and `config.sortable_url`, which the new
+    unmagic-sortable gem fills in.
+- `board`, a Trello-style board of reorderable columns and cards, with add-card
+  and add-list forms (`board.js`).
+
+- AI chat components, for rendering an agent's work. Designed from three
+  applications that each grew their own agent UI, and checked against
+  assistant-ui's primitives. Each has a design note in `docs/components/ai_chat`
+  and a page in the browser:
+  - `ai_chat`, the transcript: a polite log that follows new content while the
+    reader is at the bottom, with a jump-to-latest button and a welcome slot.
+  - `ai_chat_message`: a user's bubble or an assistant's prose, with reasoning,
+    actions, branches and attachments, and an optimistic template.
+  - `ai_chat_tool_call`: a row per tool call, joined into a timeline, with a
+    live clock, progress, partial-failure counts and folded payloads.
+  - `ai_chat_payload`, `ai_chat_reasoning`, `ai_chat_failure`, `ai_chat_plan`
+    and `ai_chat_workspace`.
+  - `ai_chat_request`, `ai_chat_permission` and `ai_chat_proposal`, for an agent
+    that stops to ask.
+  - `ai_chat_composer` (with `ai_chat_composer_action` and
+    `ai_chat_stop_form`), `ai_chat_slash_menu`, `ai_chat_welcome`,
+    `ai_chat_attachments` and `ai_chat_dropzone`.
+  - `ai_chat_citation`, `ai_chat_action_bar` and `ai_chat_branch_picker`.
+- `streaming_markdown_tag` and `turbo_stream.stream_markdown`: server-rendered
+  HTML revealed at a steady pace as fuller renders arrive
+  (`<unmagic-streaming-markdown>`).
+- `elapsed_tag`, a clock counting up from a time or down to one
+  (`<unmagic-elapsed>`).
+- `avatar` and `avatar_group`, with initials on a tint picked from the name.
+- `UnmagicProse`, styles for server-rendered Markdown.
+- `config.code_block`, the seam payloads and prose code blocks render through,
+  for a host's highlighter.
+- Custom elements `<unmagic-autoscroll>`, `<unmagic-optimistic>`,
+  `<unmagic-toolbar>`, `<unmagic-slash-menu>` and `<unmagic-dropzone>`.
+- The browser groups components under headings, with the AI chat components in
+  their own group. Its composer example posts for real and streams a reply.
+
+### Changed
+
+- The gem now depends on `unmagic-icon` and `unmagic-color`. Its glyphs are
+  Lucide SVGs shipped in `app/assets/icons/lucide` and rendered through
+  unmagic-icon, in place of the inline paths. The rendered `<svg>` gains
+  unmagic-icon's `unmagic-icon` class and `data-unmagic-icon` attribute, and the
+  modal's retry icon is Lucide's `rotate-cw`.
+- The `upsert` stream action's placement rule moved to
+  `unmagic/components/placement`, shared with `<unmagic-optimistic>`. Its
+  behaviour is unchanged.
+
+### Fixed
+
+- The browser's dialog page opens its modal examples in the modal again. The
+  "modal" example's section had the id `modal`, which shadowed the shared
+  modal's frame, so Turbo loaded the link as a full page. Example sections are
+  now named `<component>_<example>`. The composer examples' fields no longer
+  share the id `content` either.
+- `duration="0"` on `<unmagic-toasts>` now keeps a toast up until it is
+  dismissed, so "don't take this one away" is sayable — and a test asserting on a
+  toast can stop racing the timer. It used to fall back to the default, because
+  the guard was `duration > 0` and `Number(null)` is also `0`, so an absent
+  attribute and a deliberate zero were indistinguishable. Absent, empty, negative
+  and unparseable all still fall back rather than silently pinning every toast to
+  the screen.
+
+- The helpers reach `ActionView::TestCase` too, so a host helper that composes
+  one of them (`badge`, `button_classes`) can be exercised by the host's own
+  helper spec. The engine only ran the `:action_view` load hook, which mixes
+  into `ActionView::Base` — what a template renders through, and not what a
+  helper test calls its subject on. The symptom was a helper that worked in the
+  app and raised `NoMethodError` in its spec, which is a confusing place to send
+  someone.
+
 ## [0.3.0] - 2026-09-16
 
 ### Added
@@ -161,7 +257,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configurable empty-state, pagination and Pagy seams so the gem depends on neither
   Pagy nor any host helper.
 
-[Unreleased]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/unreasonable-magic/unmagic-components/releases/tag/v0.1.0

data/README.md

@@ -36,6 +36,14 @@ the spirit of `form_for`: describe the columns, get the chrome.
   the server with a skeleton, an error panel with retry, and a close that lands
   in the same render as the page's refresh; same-page dialogs; and a confirm
   dialog in place of `window.confirm`.
+- **AI chat components** for rendering an agent's work: a transcript, streamed
+  replies revealed at a steady pace, tool calls strung into a timeline,
+  reasoning, plans, workspaces, permission gates, questions, inline proposals,
+  citations and a composer with Send and Stop. See [AI chat](#ai-chat).
+- **Drag-and-drop ordering** by pointer or keyboard: sortable lists and a
+  Trello-style board, posting one-row moves that
+  [unmagic-sortable](https://github.com/unreasonable-magic/unmagic-sortable)
+  saves. See [Sortable lists and boards](#sortable-lists-and-boards).
 - **No hard dependency** on a pagination library or on any helper of yours.
 
 ## Installation
@@ -69,11 +77,42 @@ show unmagic-components` prints where the gem is installed:
 @import "/path/to/unmagic-components/app/assets/tailwind/unmagic_components/engine.css";
 ```
 
+The gem brings two of its siblings with it: `unmagic-icon`, which renders the
+glyphs, and `unmagic-color`, which picks avatar tints. The glyphs are a subset of
+Lucide shipped inside this gem, so there is no icon set to download; under Rails
+they are also available to your views as `unmagic_icon
+"unmagic_components:lucide/<name>"`.
+
 The engine mixes the helpers into ActionView automatically — no initializer
 needed to get started. The interactive components need their JavaScript too; with
 importmap-rails the engine pins it for you, so add `import "unmagic/components"`
 to your application.js (see [Dialogs](#dialogs)).
 
+### Browsing components
+
+`Unmagic::Components::Browser` is an engine for looking through every component,
+its examples and their source inside your own app. Mount it in your routes:
+
+```ruby
+mount Unmagic::Components::Browser::Engine => "/unmagic/components" if Rails.env.development?
+```
+
+It brings its own stylesheet, prebuilt with Tailwind's default theme, and loads
+the components' JavaScript and Turbo itself, so nothing in your CSS or JS
+changes. It needs `turbo-rails` in your bundle. It renders through your
+configuration, so a `control_class` pointed at your own classes leaves its form
+examples unstyled.
+
+Its controllers inherit `ActionController::Base`, so your authentication doesn't
+cover it. Its demo endpoints only write to the visitor's session, but mount it
+outside development only behind a constraint of your own:
+
+```ruby
+authenticate :user, ->(user) { user.admin? } do
+  mount Unmagic::Components::Browser::Engine => "/unmagic/components"
+end
+```
+
 ## Theming
 
 The components use Tailwind's own palette (neutral for surfaces, borders and
@@ -110,7 +149,7 @@ The gem's rules sit in `@layer components`, which Tailwind orders before
 
 ## Configuration
 
-Three seams, each with a working default. Point them at your own versions if you
+Seams, each with a working default. Point them at your own versions if you
 already own these concerns:
 
 ```ruby
@@ -130,6 +169,16 @@ Unmagic::Components.configure do |config|
   # renderer only needs something answering previous/next/page_url, so
   # geared_pagination or your own object works just as well.
   config.pagy_for = ->(view, collection) { view.table_pagy(collection) }
+
+  # A block of code: a tool call's payload, a failure's backtrace. Called with
+  # (view, source, language), where language is :json, :plaintext or whatever
+  # you passed; return markup. The default is an unhighlighted <pre><code>.
+  config.code_block = ->(view, source, language) { view.highlight_code(source, language: language) }
+
+  # What a sortable item carries for a record, and where drops post. The
+  # unmagic-sortable gem sets both to its signed keys and endpoint.
+  config.sortable_item = ->(view, record) { { key: record.to_param, rank: record.sortable_rank } }
+  config.sortable_url = ->(view) { view.reorder_path }
 end
 ```
 
@@ -829,6 +878,462 @@ Needs `import "unmagic/components/toasts"`, which `import "unmagic/components"`
 includes. The dismiss button's label is `unmagic.components.toast.dismiss`
 ("Dismiss").
 
+## Sortable lists and boards
+
+Drag-and-drop ordering, by pointer or keyboard. The server half — ranks, signed
+keys and the endpoint — is the
+[unmagic-sortable](https://github.com/unreasonable-magic/unmagic-sortable) gem,
+which configures these components when it's installed:
+
+```ruby
+class Card < ApplicationRecord
+  include Unmagic::Sortable
+  sortable_within :board_id
+  sortable_column :column_id
+end
+```
+
+### `sortable_list(namespace: nil, params: {}, url: nil, orientation: :vertical, label: nil, **options, &block)`
+
+```erb
+<%= sortable_list label: "Interview steps", class: "flex flex-col gap-2" do |list| %>
+  <% @steps.ordered.each do |step| %>
+    <%= list.item(step) do %>
+      <%= sortable_handle label: "Move #{step.name}" %>
+      <%= step.name %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+- **Items:** `list.item(record)` takes its key and rank from
+  `config.sortable_item`; `key:` and `rank:` set them directly, and `label:` is
+  what a screen reader calls it.
+- **Handles:** with a `sortable_handle` in an item, only the handle drags, so the
+  rest stays clickable, and the handle is the keyboard stop. Without one, the
+  whole item drags once the pointer moves, and the item takes focus.
+- **Touch:** a finger lifts an item with a long press, so a swipe still scrolls
+  and a tap still taps. A `sortable_handle` grip drags at once.
+- **Between lists:** lists sharing a `namespace:` exchange items. A drop posts
+  the destination list's `params:`.
+- **Keyboard:** Space or Enter picks an item up. The arrows along the list move
+  it (`orientation:` decides which) and the arrows across move it to the next
+  list. Space drops it; Escape, or tabbing away, puts it back. Each step is
+  announced, and Escape also cancels a pointer drag.
+- **Scrolling:** a drag near the edge of anything scrollable scrolls it.
+- **The drop** fires a cancelable `unmagic-sortable:move` with
+  `{ key, original, prev, next, params }`, then PATCHes `url:`
+  (`config.sortable_url`) with `moved`, `original`, `prev`, `next` and the params.
+  Without a url, the event is all there is.
+- **Styling:** `sortable-dragging:`, `sortable-placeholder:`, `sortable-lifted:`,
+  `sortable-active:` and `sortable-over:` variants decorate the drag states.
+
+Needs `import "unmagic/components/sortable"`. I18n under
+`unmagic.components.sortable`: `handle`, `instructions`, `picked`, `moved`,
+`dropped` and `cancelled`, with `{item}`, `{list}`, `{position}` and `{count}`.
+
+### `board(id:, url: nil, columns_url: nil, sortable_columns: true, label: nil, column_height: nil, **options, &block)`
+
+```erb
+<%= board id: "roadmap" do |board| %>
+  <% @columns.each do |column| %>
+    <% board.column column, title: column.name, params: { column_id: column.id } do |col| %>
+      <% col.actions { menu { |m| m.link "Rename", edit_column_path(column) } } %>
+      <% column.cards.ordered.each { |card| col.card(card) { render card } } %>
+      <% col.add url: cards_path, field: "card[title]", params: { "card[column_id]" => column.id } %>
+    <% end %>
+  <% end %>
+  <% board.add_column url: columns_path, field: "column[name]" %>
+<% end %>
+```
+
+- **Moving:** cards move within and between the board's columns, posting the
+  column's `params:`. Columns move along the board by their header, and the grip
+  in it is their keyboard stop. On a phone, press and hold a card or a header. `sortable_columns: false` fixes them in place.
+- **Forms:** `col.add` and `board.add_column` open into a one-field form. Enter
+  submits it, Escape closes it, and it stays open after adding, so several can be
+  added in a row.
+- **Size:** `column_height:` (default `75dvh`) is how tall a column grows before
+  its cards scroll.
+- **Where drops go:** `url:` is where they post; `columns_url:` sends column drops
+  elsewhere.
+
+Needs `import "unmagic/components/sortable"` and `"unmagic/components/board"`.
+I18n under `unmagic.components.board`: `label`, `add_card`, `add_card_submit`,
+`add_column`, `add_column_submit`, `cancel`, `move_column` and `cards`.
+
+## Avatars
+
+### `avatar(name, src: nil, size: :medium, shape: :circle, tint: true, skeleton: false, **options)`
+
+```erb
+<%= avatar "Ada Lovelace" %>
+<%= avatar @user.name, src: @user.avatar_url, size: :large %>
+<%= avatar "Acme Ltd", shape: :square %>
+
+<%= avatar_group max: 3, size: :small do |group| %>
+  <% @members.each { |member| group.avatar member.name, src: member.avatar_url } %>
+<% end %>
+```
+
+- **Initials** come from the first and last words ("Ada Lovelace" is "AL") and
+  always render. The image sits on top of them, so a broken image shows the
+  initials without any script.
+- **Tint:** the initials sit on one of six palette tints picked from the name
+  with `unmagic-color`'s stable string hash, so a person keeps their colour on
+  every page and every server. `tint: false` is neutral. Override
+  `UnmagicAvatar--tint-1` … `-6` to recolour them.
+- **Sizes:** `:small`, `:medium` and `:large` (1.5, 2 and 2.5rem).
+  `skeleton: true` renders a skeleton circle of the same size.
+- **Accessibility:** an avatar is `role="img"` named for the person. Pass
+  `"aria-hidden": true` when the name is written beside it.
+- **Groups:** `avatar_group` sets the size and shape for every avatar in it, and
+  collapses past `max:` into a "+N" whose title names the rest.
+
+I18n: `unmagic.components.avatar.group` ("%{count} people") and
+`unmagic.components.avatar.more` ("+%{count}").
+
+## Elapsed times
+
+### `elapsed_tag(time, direction: :up, **options)`
+
+```erb
+<%= elapsed_tag tool_call.started_at %>                    <%# 3m 5s, and counting %>
+<%= elapsed_tag session.expires_at, direction: :down %>    <%# 42s, and falling %>
+```
+
+A clock that counts up from a moment the server named, a second at a time, or
+down to one, stopping at zero and firing `unmagic-elapsed:end`. Work that takes a
+minute and work that has hung look the same behind a spinner; a number that keeps
+moving is the difference.
+
+The server renders the current reading, so it is right before the script loads.
+Readings are whole seconds — `2s`, `3m 5s`, `1h 4m 2s` — and a settled duration
+under a second is milliseconds (`640ms`). The words are the
+`unmagic.components.elapsed.*` keys (`milliseconds`, `seconds`, `minutes`,
+`hours`); the element writes the English forms as it ticks. A blank time renders
+an em dash. Needs `import "unmagic/components/elapsed"`.
+
+## AI chat
+
+Components for rendering an agent's work, in the spirit of
+[assistant-ui](https://www.assistant-ui.com) but server-rendered: the host renders
+each turn, Turbo Streams keep it live, and small custom elements pace the reveal.
+
+```erb
+<%= turbo_stream_from @chat %>
+
+<div id="transcript" class="h-[70dvh] overflow-y-auto">
+  <%= ai_chat id: "entries", scroller: "#transcript" do |chat| %>
+    <% chat.welcome do %>
+      <%= ai_chat_welcome heading: "What can I help with?" do |welcome| %>
+        <% welcome.suggestion "Who hasn't replied yet?" %>
+      <% end %>
+    <% end %>
+    <%= render @chat.entries %>
+  <% end %>
+</div>
+
+<%= form_with model: Message.new, url: chat_messages_path(@chat), id: "composer" do |form| %>
+  <%= ai_chat_composer form: form, field: :content, state: @chat.run_state do |composer| %>
+    <% composer.optimistic id: "message[client_id]", container: "#entries" %>
+  <% end %>
+<% end %>
+<%= ai_chat_stop_form chat_stop_path(@chat) %>
+```
+
+```erb
+<%# app/views/messages/_message.html.erb %>
+<%= ai_chat_message role: message.role.to_sym, id: dom_id(message), streaming: message.pending? do %>
+  <%= message.user? ? message.content : Markdown.render(message.content) %>
+<% end %>
+```
+
+They need Turbo and `import "unmagic/components"`, or the modules named below.
+
+### How the pieces fit
+
+- **Entries are upserted by id.** Broadcast each entry with the gem's `upsert`
+  action into the transcript's id. A record already on the page is replaced in
+  place; a new one is inserted in id order.
+
+  ```ruby
+  broadcast_action_to chat, action: :upsert, target: "entries", partial: "messages/message", locals: { message: self }
+  ```
+
+- **The question is drawn before the server has it.** `composer.optimistic`
+  renders an `<unmagic-uuid-input>` and a template of the question. On submit,
+  `<unmagic-optimistic>` draws the question, dimmed, under the minted id. Create
+  the record under that id (`message[client_id]`) and its broadcast replaces the
+  placeholder.
+- **Replies stream as whole renders.** While a reply is being written, send the
+  whole of it so far, rendered, to the body's id. `<unmagic-streaming-markdown>`
+  works out what's new and reveals it at the model's own average pace, so bursts
+  read as one stream. When the turn settles, upsert the whole message. The new
+  element picks up the reveal where the old one left off.
+
+  ```ruby
+  broadcast_action_to chat, action: :stream_markdown, target: "#{dom_id(self)}_content",
+    html: Markdown.render(content)
+  ```
+
+- **The gem never parses Markdown.** Hand it your own rendered, sanitised HTML.
+  `UnmagicProse` styles it, and code blocks, like tool payloads, go through
+  `config.code_block`.
+- **Only the composer's button changes with the turn's state.** Redraw it with
+  `ai_chat_composer_action` so a half-typed draft survives.
+- **Amber means waiting on a person.** A question, a permission request or a plan
+  step parked on someone is the one state that won't move on its own, so it is
+  the one in colour.
+
+### `ai_chat(id:, scroller: nil, follow: true, scroll_to_latest: true, **options, &block)`
+
+The scrolling region turns are rendered into: a polite `role="log"`. It renders
+no entries of its own; use a partial per entry type.
+
+- **Following:** it keeps the scroller (the page, or `scroller:`) at the bottom
+  while the reader is there, and stops when they scroll up. A jump-to-latest
+  button shows meanwhile (`scroll_to_latest: false` for none). `follow: false`
+  renders a bare log.
+- **Spacing:** turns are separated by a gap that hidden entries don't earn. Mark
+  hidden entries between two tool calls (a tool result's anchor) with
+  `data-ai-chat-timeline="gap"` so the run stays joined.
+- **Welcome:** `chat.welcome` shows while there are no entries, and hides as the
+  first one arrives.
+
+Needs `import "unmagic/components/autoscroll"`. I18n:
+`unmagic.components.ai_chat.transcript.label` ("Conversation") and `.latest`
+("Jump to latest"). The button's dock is sticky at `bottom-4`; lift it with
+`.UnmagicAIChat__latest { bottom: … }` if a sticky composer covers it.
+
+### `ai_chat_message(content = nil, role:, id: nil, streaming: false, final: false, optimistic: nil, **options, &block)`
+
+One turn. A user's turn is a bubble of plain text with its line breaks kept; an
+assistant's is unbubbled prose.
+
+- **The body** of an assistant turn with an id is an
+  `<unmagic-streaming-markdown id="#{id}_content">`. `streaming: true` shows a
+  thinking spinner until the first flush and marks the body busy. `final: true`
+  refuses any later flush, for a stopped or failed reply.
+- **Empty:** a settled assistant turn with nothing in it is `hidden`, keeping its
+  id for broadcasts.
+- **Parts:** `turn.reasoning(**options) { }` (see `ai_chat_reasoning`),
+  `turn.actions { }`, `turn.branches { }` and `turn.attachments { }` (above a
+  user's bubble).
+- **Optimistic:** `optimistic: { id:, text: }` renders the template a composer
+  fills from those fields, dimmed.
+
+I18n: `unmagic.components.ai_chat.message.user` ("You said"), `.assistant`
+("Assistant said") and `.thinking` ("Thinking"), for screen readers.
+
+### `streaming_markdown_tag(content = nil, id:, final: false, streaming: false, **options, &block)`
+
+The streaming body on its own. Send flushes with
+`turbo_stream.stream_markdown(target, html)`, each carrying the whole render so
+far. Under reduced motion each flush paints at once. It fires
+`unmagic-streaming-markdown:settle` when it has caught up. Needs
+`import "unmagic/components/streaming_markdown"`.
+
+### `ai_chat_reasoning(content = nil, title: nil, streaming: false, duration: nil, open: false, **options, &block)`
+
+The model's thinking, collapsed above its reply. `duration:` titles it "Thought
+for 12s"; `streaming: true` shows "Thinking…". `reasoning.block { }` adds a
+block. Blank content renders nothing. I18n:
+`unmagic.components.ai_chat.reasoning.title`, `.thinking` and `.duration`.
+
+### `ai_chat_tool_call(name:, state:, id: nil, icon: nil, open: false, timeline: true, **options, &block)`
+
+```erb
+<%= ai_chat_tool_call name: call.name, state: call.state, id: dom_id(call), icon: call.category_icon do |tool| %>
+  <% tool.summary call.summary %>
+  <% tool.timing started_at: call.started_at, duration: call.duration %>
+  <% tool.asked call.arguments %>
+  <% tool.answered call.response %>
+<% end %>
+```
+
+- **State:** `:queued`, `:running`, `:waiting`, `:done` or `:failed`. A running
+  call is busy, spins, and counts up with `elapsed_tag`. A done call shows
+  `icon:`, what it was about, in place of a column of identical ticks.
+- **Timeline:** consecutive calls are joined by a line, which runs down an open
+  call's body. `timeline: false` leaves a call out of the run.
+- **Parts:** `summary`, `timing`, `asked` and `answered` (payloads, in a
+  `<details>`, so no script and no state to restore after a redraw), `failures`
+  (a count for a batch that mostly worked), `progress` (a line with id
+  `"#{id}_progress"` to replace as the tool reports), and `made { }` (output
+  kept outside the fold).
+
+I18n under `unmagic.components.ai_chat.tool_call`: `queued`, `running`,
+`waiting`, `done`, `failed`, `asked`, `answered`, `failures`, `partly_failed`,
+`running_for` and `took`.
+
+### `ai_chat_payload(payload, label: nil, language: nil, duration: nil, copy: false, **options)`
+
+What went into a tool call or came back. A Hash, an Array, or a string holding
+JSON is laid out a key to a line as `:json`; anything else is `:plaintext`
+unless `language:` says otherwise. It renders through `config.code_block`,
+scrolls past a height, wraps long lines, and is reachable by keyboard. `copy:
+true` adds a copy button. `nil` renders nothing. I18n:
+`unmagic.components.ai_chat.payload.took` and `.label` ("Payload").
+
+### `ai_chat_composer(form:, field:, state: :idle, label: nil, stop_form: "stop_turn", placeholder: nil, rows: 2, **options, &block)`
+
+- **The form needs an `id:`.** Send names it with `form=`, and Stop names
+  `stop_form:`. Render `ai_chat_stop_form(url)` outside your form, since forms
+  can't nest.
+- **State** — `:idle`, `:running`, `:stopping` or `:waiting` — changes only the
+  button region (id `"#{form_id}_action"`, a polite live region). The field is
+  never disabled. Redraw the region alone with
+  `ai_chat_composer_action(form:, state:)`.
+- **Keys:** Enter sends and Shift+Enter makes a new line. Enter does nothing
+  while there's no Send button. A successful submit resets the form and keeps
+  focus in the field.
+- **Parts:** `composer.optimistic(id:, container:)`, `composer.attach { }`,
+  `composer.actions { }` and `composer.menu { }` (an `ai_chat_slash_menu`).
+- **The field** is the composer's own chrome, not a `control_class` control: the
+  box around it is the control and takes the focus ring.
+
+Needs `import "unmagic/components/ai_chat"`. I18n under
+`unmagic.components.ai_chat.composer`: `send`, `stop`, `stopping`, `waiting`
+and `label`.
+
+### `ai_chat_slash_menu(for: nil, id: nil, trigger: "/", above: false, insert: nil, **options, &block)`
+
+Commands offered on a slash. `menu.item(name, description:, arguments:)` for
+each; every item is rendered and typing filters them by prefix. Up and Down move,
+Enter or Tab takes one, Escape closes, and focus stays in the field (the combobox
+pattern). Picking writes `"/name "` at the cursor. `for:` defaults to the
+composer's field. Needs `import "unmagic/components/slash_menu"`. I18n:
+`unmagic.components.ai_chat.slash_menu.label` ("Commands").
+
+### `ai_chat_attachments(align: :start, **options, &block)` and `ai_chat_dropzone(input:, url: nil, field: nil, chips: nil, label: nil, **options, &block)`
+
+`ai_chat_attachments` lists the files a sent turn carries
+(`files.file name, size:, url:, thumbnail:`; `align: :end` for a user's turn).
+
+`ai_chat_dropzone` wraps a region that takes dropped and pasted files, with an
+overlay while dragging. `input:` is the file input the files join, which is also
+the way in for anyone who can't drag. Without `url:`, files wait on that input
+and post with the form. With `url:`, each file is POSTed on the spot as `file`,
+and the JSON response's `value` is posted with the message under `field:`.
+`chips:` is where attached files are listed: the composer's
+`[data-ai-chat-chips]`. It fires `unmagic-dropzone:attach` and `:error`. Needs
+`import "unmagic/components/dropzone"`. I18n under
+`unmagic.components.ai_chat.attachments`: `drop`, `attached`, `remove` and
+`failed`.
+
+### `ai_chat_welcome(heading:, heading_tag: :h2, composer: "composer", field: nil, **options, &block)`
+
+What an empty conversation says. `welcome.body(text)` and
+`welcome.suggestion(label, icon:, fill:, value:)`. Pressing a suggestion puts it
+in the composer form with id `composer:` and sends it, unless `fill: true` or a
+turn is running. Needs `import "unmagic/components/ai_chat"`.
+
+### `ai_chat_request(state:, url: nil, method: :patch, prompt: nil, label: nil, scope: :response, live: false, **options, &block)`
+
+```erb
+<%= ai_chat_request state: :waiting, url: answer_path(@chat), live: true do |request| %>
+  <% request.question "How should it sound?", header: "Tone" do |q| %>
+    <% q.option "Friendly", description: "A short, warm check-in" %>
+    <% q.option "Direct" %>
+  <% end %>
+<% end %>
+```
+
+- **Ask with questions** (`multiple: true` for checkboxes; answers post as
+  `answers[i][]`) **or with a form** (`request.form { |form| … }`), not both.
+  `request.decline` adds a Decline that skips validation.
+- **Answered states** — `:accepted`, `:declined`, `:cancelled`, `:timed_out` —
+  keep the questions and show what was picked (`question picked:`) or answered
+  (`request.answer label, value`). Declined and dropped cards dim.
+- **`live: true`** adds `role="alert"` and, if nothing else has focus, focuses
+  the first option.
+
+I18n under `unmagic.components.ai_chat.request`: `waiting`, `asked`, `answer`,
+`decline`, `accepted`, `declined`, `cancelled`, `timed_out` and `unanswered`.
+
+### `ai_chat_permission(tool:, state:, url: nil, live: false, outcome: nil, **options, &block)`
+
+```erb
+<%= ai_chat_permission tool: "delete_files", state: :waiting, url: permission_path(@call) do |ask| %>
+  <% ask.argument "paths", "drafts/*" %>
+  <% ask.summary { markdown(@call.summary) } %>
+  <% ask.allow confirm: "Delete these files? This can't be undone." %>
+  <% ask.allow "Allow for any chat", params: { widened: true } %>
+  <% ask.refuse %>
+<% end %>
+```
+
+- **The ask** — the tool's own name and its arguments — comes before the
+  reasoning, because it's what the decision is about.
+- **Actions:** the first `allow` is the prominent, red, consequential choice; a
+  later one is the wider grant. Offer that only when there is something to
+  widen. `allow` POSTs and `refuse` DELETEs to `url:`, each with `params:` and
+  `confirm:`.
+- **Focus** goes to the card when it arrives, never to Allow.
+- **Answered:** `:granted`, `:refused`, or `:lapsed` (answered in the chat,
+  nothing granted), with `outcome:` to reword the sentence.
+
+I18n under `unmagic.components.ai_chat.permission`: `waiting`, `asked`, `allow`,
+`refuse`, `granted`, `refused` and `lapsed`.
+
+### `ai_chat_proposal(state: :pending, icon: :lightbulb, id: nil, **options, &block)`
+
+An offer the agent made in passing, which doesn't stop the work: `offer.claim`,
+`offer.meta`, `offer.accept { }` and `offer.reject { }` while `:pending`; the
+outcome (`"Saved"`, `"Dismissed"`, or `offer.outcome`) once `:accepted` or
+`:rejected`. It is an `<aside>` named by its claim, and `not-prose` so it can sit
+inside a reply. I18n: `unmagic.components.ai_chat.proposal.accepted` and
+`.rejected`.
+
+### `ai_chat_citation(compact: false, **options, &block)`
+
+A quotation rendered from the record, not the model's paraphrase:
+`cite.avatar` (with no block, the gem's avatar for `who`), `cite.who`,
+`cite.when(time, url:)` and `cite.quote(text)`. The quote is escaped text with
+its line breaks kept. `compact: true` is one line, for a list of sources.
+
+### `ai_chat_failure(message = nil, live: false, **options, &block)`
+
+A turn that fell over. The sentence is for whoever asked. `failure.cause` sits
+above the fold; `failure.detail(label, payload, language:)` rows fold away for
+whoever works on the assistant; `failure.retry { }` holds your control. Render
+it below a turn's body, never in its place. `live: true` adds `role="alert"`.
+I18n: `unmagic.components.ai_chat.failure.details`.
+
+### `ai_chat_plan(**options, &block)` and `ai_chat_workspace(**options, &block)`
+
+Two sections of one side panel. Both are collapsible, open by default, and
+always render, empty or not, so a broadcast has something to replace.
+
+- **`plan.step(title, state:)`:** `:pending`, `:in_progress`, `:waiting` or
+  `:completed`, with an optional block for detail. The count reads
+  completed/total, or `completed:`/`total:` when a panel shows only some steps.
+- **`workspace.file(path, size:, url:, icon:)`:** a flat list of paths. A file
+  with a url is a link.
+- **Both take** `title:`, `open:`, `empty:`, `collapsible:` and `title_tag:`
+  (`:h2`). The workspace also takes `count:`.
+
+I18n under `unmagic.components.ai_chat`: `plan.title`, `plan.empty`,
+`plan.pending`, `plan.in_progress`, `plan.waiting`, `plan.completed`,
+`workspace.title` and `workspace.empty`.
+
+### `ai_chat_action_bar(for:, reveal: :hover, **options, &block)` and `ai_chat_branch_picker(index:, count:, previous: nil, next: nil, method: :get, **options)`
+
+The controls under a turn. `bar.copy(text)`, `bar.action(label, url, icon:,
+method:, confirm:)` and `bar.control { }` make a toolbar with one Tab stop and
+arrow keys between controls (`<unmagic-toolbar>`). `reveal: :hover` shows it on
+hover or focus, and always on touch screens; it is never hidden from the
+keyboard.
+
+`ai_chat_branch_picker` walks between versions of a turn: "Version 2 of 3",
+with a disabled end where there's nowhere to go. What a branch is stays your
+application's business, and one version renders nothing.
+
+Needs `import "unmagic/components/toolbar"` and `"unmagic/components/ai_chat"`.
+I18n: `unmagic.components.ai_chat.action_bar.label` and
+`unmagic.components.ai_chat.branch_picker.label`, `.previous` and `.next`.
+
 ## Development
 
 ```sh