unmagic-components 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e66d8f2c875d1c138f1a7921f52e7ec3e77a44b834eb6026025d40dec4ab9ab
-  data.tar.gz: c291912ef44869d6216760661a32b2046fa8820e718acffcd5a6d2cf7fbecc2a
+  metadata.gz: 73a26932047bf5f5019925414115576c98d199f51e434ebae9e614423ba67022
+  data.tar.gz: 93be93b5f8b3c9c42c8224a0ec229635a270a89f5319477e0b99970cb4ab4e8c
 SHA512:
-  metadata.gz: fe94b2574228893a83a514cdd07f6608e2541710494e10775926e784c6dced8c83d9e3f6f47f0ad4a51845e26d1c2255fadbc3c120955b8980829b2467c645ca
-  data.tar.gz: fe2a0c8fe420bf563d69d7ce8fc0cde4001decf52d141c57e91407b6666ad40b15862f846315232511400fbadddbdde88e3aa512029d8f77cc1834635ac2f3b4
+  metadata.gz: 1269dce8cd8dac1c5d3d8e9f0ac2437bf4b2bd25e2511d5dc8aee4010157dfb9156be984fc2976029995dc704d3bb4ac8b880ea2683f51571f9bc88edf3cac8d
+  data.tar.gz: 4a6e77ce020686fecbbe0c09247ab61769128b263ff47cea7df9549b3b360670e068400743bfae9a69d467250479f0768e57d57581d651927c686800ccefd868

data/CHANGELOG.md

@@ -7,8 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-16
+
 ### Added
 
+- Dialogs, each a native `<dialog>` sharing one panel (a titled header with a
+  close button, the body, and an optional footer):
+  - **The shared modal.** Mount it with `modal_frame`, point links at it with
+    `modal_link_to`, and render a `dialog` from the action. `form:` builds the
+    form around the whole panel. The `<unmagic-modal>` element opens on the
+    frame's request with a skeleton, and shows an error panel with a retry when
+    the load fails. It closes in the same render as a `turbo_stream.refresh`, so
+    the page repaints once. `Unmagic::Components::DialogResponder` provides the
+    `refresh_or_redirect` that sends that refresh, and `config.modal_frame_id`
+    renames the frame.
+  - **Dialogs already on the page:** `dialog_tag` and `dialog_button`.
+  - **A confirm dialog in place of `window.confirm`** for `data-turbo-confirm`
+    (`import "unmagic/components/confirm"`). `data-turbo-confirm-title`,
+    `-accept` and `-variant="danger"` customise it, and `confirm_dialog_template`
+    carries its words through I18n.
+- Page building blocks with no JavaScript:
+  - `page_header` shows a back link, a title with badges, a description and
+    actions.
+  - `card` has a header with actions and a tinted footer. `flush:` suits a table
+    that runs edge to edge, and `href:` makes the whole card one link.
+  - `badge` comes in neutral, good, warn, bad, info and accent tones.
+  - `callout` comes in neutral, good, warn, bad and info tones, each with an icon
+    and an optional title and badge.
+  - `empty_state` is now a helper you can call directly, still rendered through
+    the `empty_state` setting. A new `--unmagic-surface-3` token colours neutral
+    badges.
+- `local_time_tag` and `<unmagic-time>`. A timestamp the browser formats with
+  `Intl`, in the viewer's locale and time zone. The formats are short, medium,
+  long, full, date, time and relative. Relative times keep themselves current on
+  one shared, minute-aligned timer, and `compact: true` shortens them to "5m".
+- `tooltip` and `<unmagic-tooltip>`. A hint on hover or focus, drawn in the top
+  layer so nothing clips it. It flips to the other side when there isn't room,
+  stays on screen, and closes on Escape. Plain text is styled as a term. New
+  `--unmagic-tooltip` and `--unmagic-on-tooltip` tokens colour it.
+- `menu` and `<unmagic-menu>`. A dropdown built on `<details>` with `link`,
+  `button` and `divider` items. It closes on an outside click, Escape, choosing an
+  item, or a Turbo navigation, and supports keyboard navigation.
+- `tabs` and `<unmagic-tabs>`. Panels switched in the page using the ARIA tab
+  pattern with arrow-key navigation, including disabled tabs that show a reason.
+  With an `id:` the choice is remembered. With `href:`, tabs become a link bar
+  rendered on the server. A new `--unmagic-raised` token colours the selected tab.
+- `copy_button` and `<unmagic-clipboard>`. Copies text, or the contents of an
+  element given by `from:`, then briefly shows a check and announces it. It fires
+  `unmagic-clipboard:copy` and `unmagic-clipboard:error`.
+- `FormBuilder#autogrow_text_area` and `autogrow_text_area_tag`. A textarea that
+  grows from its rows to its CSS max-height, re-measuring as you type, on reset
+  and when its width changes.
+- `FormBuilder#uuid_field` and `uuid_input_tag`. A hidden field holding a UUIDv7,
+  generated on the server and again in the browser when the page loads and each
+  time the form resets.
+- Skeletons for blocking out an interface while it loads. `skeleton do |s|` yields
+  `s.text`, `s.circle`, `s.block` and `s.button`, arranged with your own markup
+  and announced once as "Loading…". `skeleton_text`, `skeleton_circle`,
+  `skeleton_block` and `skeleton_button` are the same shapes outside a block.
+  Shapes take their size from what they replace: a text line fills one line of
+  its font, and a button shape is a real button's height. `detail_list`,
+  `page_header` and `card` take `skeleton: true` to render a skeleton version of
+  themselves.
+- Toasts. `flash_toasts` turns the request's flashes into toasts that dismiss
+  themselves, pause while hovered or focused, and survive Drive visits and morph
+  refreshes. `turbo_stream.toast` shows one from a stream response.
+  `config.flash_tones` maps flash types to the good, warn, bad and info tones,
+  which take their colours from the new `--unmagic-good*` and `--unmagic-warn*`
+  tokens.
+- `button_classes`, with `:primary`, `:ghost`, `:danger` and `:icon` variants and
+  `:small` and `:large` sizes.
+- `import "unmagic/components"` imports every component. The engine pins each one
+  as `unmagic/components/<name>`.
+- `--unmagic-focus` and `--unmagic-backdrop` theme tokens.
 - `table_for` passes any option it doesn't recognise to the `<table>` element, so a
   view can set `class:`, `data:` or ARIA attributes without a wrapper. `id:` still
   names the deferred turbo frame.
@@ -49,5 +120,6 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/unreasonable-magic/unmagic-components/compare/v0.2.0...HEAD
+[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

@@ -32,6 +32,10 @@ the spirit of `form_for`: describe the columns, get the chrome.
 - **Companion detail rows** under any record, skipped per row when empty.
 - **Detail lists** in inline and stacked layouts, with blanks rendered as an em
   dash so call sites don't each need `.presence || "—"`.
+- **Dialogs** as native `<dialog>`s: a shared modal that loads its content from
+  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`.
 - **No hard dependency** on a pagination library or on any helper of yours.
 
 ## Installation
@@ -47,7 +51,9 @@ Add the stylesheet to your layout:
 ```
 
 The engine mixes the helpers into ActionView automatically — no initializer
-needed to get started.
+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)).
 
 ## Theming
 
@@ -59,6 +65,8 @@ To match your own design, set the `--unmagic-*` knobs wherever your theme lives:
 :root {
   --unmagic-surface:       var(--surface);
   --unmagic-surface-2:     var(--surface-2);
+  --unmagic-surface-3:     var(--surface-3);    /* neutral badges, tab tracks */
+  --unmagic-raised:        var(--surface);      /* the selected tab */
   --unmagic-hover:         var(--hover);
   --unmagic-border:        var(--border);
   --unmagic-border-strong: var(--border-strong);
@@ -66,9 +74,27 @@ To match your own design, set the `--unmagic-*` knobs wherever your theme lives:
   --unmagic-text-2:        var(--text-2);
   --unmagic-text-3:        var(--text-3);
   --unmagic-skeleton:      var(--surface-3);
+  --unmagic-accent:        var(--primary);      /* primary buttons */
+  --unmagic-on-accent:     var(--on-primary);
+  --unmagic-bad:           var(--danger);       /* errors, danger buttons */
+  --unmagic-bad-surface:   var(--danger-surface);
+  --unmagic-bad-border:    var(--danger-border);
+  --unmagic-good:          var(--success);      /* good toasts */
+  --unmagic-good-surface:  var(--success-surface);
+  --unmagic-good-border:   var(--success-border);
+  --unmagic-warn:          var(--warning);      /* warn toasts */
+  --unmagic-warn-surface:  var(--warning-surface);
+  --unmagic-warn-border:   var(--warning-border);
+  --unmagic-tooltip:       var(--inverse);      /* tooltips */
+  --unmagic-on-tooltip:    var(--on-inverse);
+  --unmagic-focus:         var(--focus-ring);
+  --unmagic-backdrop:      rgb(0 0 0 / 0.5);    /* behind dialogs */
 }
 ```
 
+In a dark theme, set `--unmagic-accent` too. Its fallback is near-black, which
+disappears against a dark dialog.
+
 Dark mode needs nothing extra. If your own tokens already flip, these flip with
 them — the gem ships no dark variant and makes no assumption about how you
 select a theme.
@@ -231,6 +257,17 @@ Set it as the default with `config.action_view.default_form_builder`, or pass
   your own button content, e.g. an icon.
 - `form_value_for` — the value to show, whether the object is a model or something
   hash-ish, preferring what the user actually typed.
+- `autogrow_text_area` — a textarea that grows as you type, from the height its
+  `rows` give it up to its CSS `max-height`, and then scrolls. Use it as a
+  field's control with `form.field :body, "Message", as: :autogrow_text_area`.
+  Outside a form builder, use `autogrow_text_area_tag`. Needs
+  `import "unmagic/components/autogrow"`.
+- `uuid_field` — a hidden field holding a fresh UUIDv7. Use it when the form
+  should submit an id the client already knows, such as the id of an element
+  rendered before the server replies. A new id is generated when the page loads
+  and every time the form resets; without JavaScript the server's own id is sent.
+  Outside a form builder, use `uuid_input_tag`. Needs
+  `import "unmagic/components/uuid_input"`.
 
 **What the control looks like is not decided here.** Apps style inputs in
 incompatible ways — a class on every input, or a bare-element rule — and a
@@ -319,6 +356,461 @@ by id. Give every row one prefix and the time-ordered id decides.
 The companion `details` row is not broadcast: a stream action carries one element,
 and the pair is a page-render concern.
 
+## Dialogs
+
+There are three kinds, all built on the same panel: a modal whose content loads
+from the server, a dialog that's already on the page, and a confirm that replaces
+`window.confirm`. Each is a native `<dialog>`, so the browser handles trapping
+focus, closing on Escape, and returning focus when it closes.
+
+Import the behaviour once:
+
+```js
+// app/javascript/application.js
+import "unmagic/components"        // every component, including the confirm dialog
+
+// ...or only the ones you want
+import "unmagic/components/modal"
+import "unmagic/components/confirm"
+```
+
+### The shared modal
+
+Mount it once, in the layout:
+
+```erb
+<%= modal_frame %>
+```
+
+Point a link at any action with `modal_link_to`. It takes `link_to`'s arguments:
+
+```erb
+<%= modal_link_to "Edit", edit_label_path(@label), class: button_classes %>
+```
+
+The action renders a `dialog`. It's the same template whether the page opens in
+the modal or is visited directly:
+
+```erb
+<%# labels/edit.html.erb %>
+<%= dialog title: "Edit label", form: { model: @label } do |dialog, form| %>
+  <%= form.field :name, "Name", required: true %>
+
+  <% dialog.footer do %>
+    <button type="button" class="<%= button_classes %>" data-unmagic-dialog-close>Cancel</button>
+    <%= form.submit "Save" %>
+  <% end %>
+<% end %>
+```
+
+```ruby
+class LabelsController < ApplicationController
+  include Unmagic::Components::DialogResponder
+
+  def update
+    if @label.update(label_params)
+      refresh_or_redirect labels_path, notice: "Label saved."
+    else
+      render :edit, status: :unprocessable_content
+    end
+  end
+end
+```
+
+What that gets you:
+
+- **Opening:** the dialog opens as soon as the request starts and shows a skeleton
+  until the response arrives. Turbo's hover prefetch doesn't open it.
+- **Failed loads:** a network error, an error status or an empty `head :forbidden`
+  all show an error panel with a Try again button, rather than Turbo's
+  "Content missing".
+- **Failed saves:** a `:unprocessable_content` render replaces the form inside the
+  dialog, errors and all.
+- **Successful saves:**
+  - `refresh_or_redirect`: the dialog stays up, with its submit button still
+    saying "Saving…". It closes in the same render as the morph refresh, so the
+    page repaints once, straight to its new state.
+  - A stream response that doesn't refresh: the dialog closes as soon as it's read.
+  - A plain `redirect_to`: the modal visits that page and closes.
+- **Multi-step forms:** a response that renders back into the frame, such as the
+  next step of a wizard, keeps the dialog open.
+- **Closing:** Escape, a click on the backdrop, or any
+  `[data-unmagic-dialog-close]`. A drag that starts in an input and ends over the
+  backdrop doesn't count, so selecting text never throws the form away.
+
+Build the form with `form:` rather than wrapping the dialog in `form_with`. On a
+request aimed at the modal the dialog wraps itself in the modal's turbo frame, and
+Turbo keeps only what is inside that frame. A form outside the dialog would be
+dropped.
+
+The dialog leaves overflow visible, so a dropdown inside a form isn't clipped. The
+catch is that a dialog's content has to be short enough to fit the screen.
+`config.modal_frame_id` (default `"modal"`) renames the frame.
+
+### A dialog already on the page
+
+```erb
+<%= dialog_button "What's a scope?", dialog: "scopes_help", class: button_classes(:ghost) %>
+
+<%= dialog_tag "scopes_help", title: "Scopes" do %>
+  <p>A scope limits what a token can do.</p>
+<% end %>
+```
+
+The block is yielded the panel, for a `footer`. Extra options go on the
+`<dialog>`.
+
+### Confirm
+
+Importing `unmagic/components/confirm` replaces the browser's confirm box for
+`data-turbo-confirm` with a dialog in the same chrome:
+
+```erb
+<%= button_to "Delete", label_path(@label), method: :delete, class: button_classes(:danger),
+      form: { data: { turbo_confirm: "Delete this label?",
+                      turbo_confirm_accept: "Delete",
+                      turbo_confirm_variant: "danger" } } %>
+```
+
+- `data-turbo-confirm-title` sets the heading.
+- `data-turbo-confirm-accept` sets the confirming button's label.
+- `data-turbo-confirm-variant="danger"` makes that button red and focuses Cancel
+  instead, so a destructive action is never one Enter away.
+
+These attributes are read from the submitter, then the form. A link with
+`data-turbo-method` doesn't pass them on: Turbo builds a form for it and copies
+only `data-turbo-confirm` onto it. Use `button_to` when you need them.
+
+### Buttons
+
+`button_classes(variant = :default, size: nil)` returns the class string, so the
+look works with `link_to`, `button_to` and `form.submit` alike. The variants are
+`:default`, `:primary`, `:ghost`, `:danger` and `:icon`; the sizes are `:small`
+and `:large`.
+
+### Translations
+
+The words in these components go through I18n, with English defaults. The confirm
+dialog is built in the browser, so render `<%= confirm_dialog_template %>` once in
+your layout to translate it.
+
+| Key | Default |
+|---|---|
+| `unmagic.components.dialog.close` | Close |
+| `unmagic.components.modal.loading` | Loading… |
+| `unmagic.components.modal.error_title` | Couldn’t load |
+| `unmagic.components.modal.error_message` | Something went wrong loading this. Check your connection and try again. |
+| `unmagic.components.modal.retry` | Try again |
+| `unmagic.components.confirm.title` | Are you sure? |
+| `unmagic.components.confirm.accept` | Confirm |
+| `unmagic.components.confirm.cancel` | Cancel |
+
+## Page building blocks
+
+Plain Ruby and CSS, with no JavaScript.
+
+### `page_header(title:, description:, back:, **options, &block)`
+
+```erb
+<%= page_header title: @label.name, description: "Applied to 12 issues.",
+      back: { text: "Labels", path: labels_path } do |header| %>
+  <% header.badge "Archived", tone: :warn if @label.archived? %>
+  <%= modal_link_to "Edit", edit_label_path(@label), class: button_classes %>
+<% end %>
+```
+
+The block's output becomes the actions on the right. Its builder also takes
+`title { }` and `description { }` for markup, and `leading { }` for something
+before the title, such as an avatar. The actions drop below the title when there
+isn't room beside it.
+
+### `card(title:, href:, flush:, **options, &block)`
+
+```erb
+<%= card title: "Members" do |card| %>
+  <% card.actions { link_to "Invite", new_invitation_path, class: button_classes(size: :small) } %>
+  Ada, Grace and Katherine can see everything.
+  <% card.footer { "3 of 5 seats used" } %>
+<% end %>
+```
+
+- `flush: true` removes the body's padding. A `table_tag` or `table_for` inside a
+  flush card uses the card's border instead of drawing its own.
+- `href:` makes the whole card one link, for a row that opens a record. Don't put
+  other links or buttons inside it.
+- A card doesn't clip its content, so a dropdown inside one isn't cut off.
+
+### `badge(content, tone: :neutral, **options)`
+
+```erb
+<%= badge "Draft" %>
+<%= badge "Overdue", tone: :bad %>
+```
+
+Tones are `:neutral`, `:good`, `:warn`, `:bad`, `:info` (outlined) and `:accent`.
+
+### `callout(title = nil, tone: :neutral, badge: nil, icon: true, **options, &block)`
+
+```erb
+<%= callout "DNS isn't verified", tone: :warn, badge: "Pending" do %>
+  Add the TXT record below, then check again.
+<% end %>
+```
+
+This is for the state of something in place, such as a health check or a warning
+above a form. Each tone except `:neutral` has an icon, and `icon: false` removes
+it. A badge takes the callout's tone.
+
+### `empty_state(content = nil, **options, &block)`
+
+```erb
+<%= empty_state "No invitations yet." %>
+```
+
+This is the same blank slate tables use. It renders through the `empty_state`
+setting, so if your app replaces it, both change.
+
+## Times and tooltips
+
+### `local_time_tag(time, format: :medium, compact: false, **options)`
+
+```erb
+<%= local_time_tag comment.created_at, format: :relative %>   <%# "3 hours ago" %>
+<%= local_time_tag invoice.due_at, format: :date %>           <%# "16 Sept 2026" %>
+<%= local_time_tag event.starts_at %>                         <%# "16 Sept 2026, 4:33 pm" %>
+```
+
+The browser formats the time with `Intl`, in the viewer's own locale and time
+zone, so there's nothing to translate and no time zone to look up for the user.
+Until the script runs, the server's own rendering (in `Time.zone`) shows instead.
+
+| `format:` | Shows |
+|---|---|
+| `:short`, `:medium`, `:long`, `:full` | A date and time, in increasing detail |
+| `:date`, `:time` | Just one of them |
+| `:relative` | "now", "5 minutes ago", "yesterday", "in 3 days" |
+
+- **Relative times stay current.** Every relative time on the page updates on one
+  shared timer, once a minute, and the full time shows on hover.
+- **Days follow the calendar.** A relative time counts days by midnight, so
+  something from 11pm reads "yesterday" at 2am.
+- **Old dates settle.** Past a week a relative time becomes a plain date and stops
+  updating.
+- **Compact form:** `compact: true` shortens a relative time to "5m" or "3h".
+- **Blank values:** a `nil` time renders an em dash.
+
+### `tooltip(content = nil, text:, placement: :top, term: nil, **options, &block)`
+
+```erb
+Every page declares a <%= tooltip "canonical URL", text: "The address search engines treat as the original." %>.
+
+<%= tooltip text: "Copy the key" do %>
+  <%= copy_button @key.secret %>
+<% end %>
+```
+
+- **Hover and focus:** the hint appears on hover after a short delay, or straight
+  away on focus. Escape dismisses it.
+- **Never clipped:** it's drawn in the browser's top layer, so a container's
+  overflow can't cut it off. It flips to the other side when there isn't room and
+  stays inside the screen.
+- **Terms:** plain text content gets a dashed underline and a help cursor, and
+  becomes focusable. Block content, such as a button or an icon, is left alone
+  and the hint describes its focusable element. `term:` overrides that choice.
+- **Placement:** `:top` or `:bottom`.
+
+Needs `import "unmagic/components/time"` and `"unmagic/components/tooltip"`, or
+`import "unmagic/components"`.
+
+## Menus, tabs and copy buttons
+
+### `menu(label = nil, align: :end, **options, &block)`
+
+```erb
+<%= menu do |menu| %>
+  <% menu.link "Edit", edit_job_path(@job) %>
+  <% menu.divider %>
+  <% menu.button "Delete", job_path(@job), method: :delete, tone: :danger,
+       form: { data: { turbo_confirm: "Delete this job?" } } %>
+<% end %>
+```
+
+- **Built on `<details>`:** the menu opens even before its script loads.
+- **Closing:** an outside click, Escape, choosing an item, or navigating away with
+  Turbo all close it.
+- **Keyboard:** the arrow keys, Home and End move between items. Opening the menu
+  with the keyboard focuses the first item.
+- **Trigger:** with no label it's a ⋮ icon button labelled "More actions"
+  (`unmagic.components.menu.label`). Pass a label for a text button with a chevron.
+- **Items:** `link` and `button` take `link_to`'s and `button_to`'s arguments, plus
+  `tone: :danger`.
+- **Alignment:** `align: :start` lines the panel up with the trigger's left edge
+  instead of its right.
+
+### `tabs(id: nil, **options, &block)`
+
+```erb
+<%= tabs id: "response" do |tabs| %>
+  <% tabs.tab "Body" %>
+  <% tabs.tab "Headers" %>
+  <% tabs.tab "Preview", disabled: "HTML only" %>
+  <% tabs.panel do %>...<% end %>
+  <% tabs.panel do %>...<% end %>
+<% end %>
+```
+
+- **Accessible markup:** the server renders the full tab pattern with its ARIA
+  roles, so only the selected tab is in the tab order. The arrow keys, Home and
+  End switch tabs.
+- **Panels:** each panel pairs with an enabled tab, in order. A tab with
+  `disabled:` shows its reason and takes no panel, and `active: true` picks the
+  tab shown first.
+- **Remembering the choice:** give the tabs an `id:` and the chosen tab is kept
+  for that page until the browser tab closes, even across a morph refresh.
+  Each change fires `unmagic-tabs:change`.
+
+Give each tab an `href:` instead of panels and you get a bar of links to separate
+pages. It's rendered on the server with no script, and `active: true` marks the
+current page:
+
+```erb
+<%= tabs do |tabs| %>
+  <% tabs.tab "All", href: invitations_path, active: @status.nil? %>
+  <% tabs.tab "Replied", href: invitations_path(status: "replied"), active: @status == "replied" %>
+<% end %>
+```
+
+### `copy_button(text = nil, from: nil, label: nil, **options, &block)`
+
+```erb
+<%= copy_button @key.secret %>
+
+<code id="install_command">bundle add unmagic-components</code>
+<%= copy_button from: "install_command" do %>Copy command<% end %>
+```
+
+- **Feedback:** the copy icon briefly turns into a check, and screen readers hear
+  "Copied".
+- **Copying from the page:** `from:` copies the value of an input, or the text of
+  any element, with that id at the moment of the click. The text doesn't need to
+  be repeated in an attribute.
+- **Labels and options:** without a block it's an icon button labelled `label:`
+  ("Copy"). Other options go on the `<button>`.
+- **Events:** it fires `unmagic-clipboard:copy`, or `unmagic-clipboard:error` when
+  the browser refuses the write, so you can show a toast.
+
+Needs `import "unmagic/components/menu"`, `"unmagic/components/tabs"` and
+`"unmagic/components/clipboard"`, or `import "unmagic/components"`.
+
+## Skeletons
+
+Skeletons block out an interface while it loads. `skeleton` yields a builder,
+like `form_for` does. You arrange its shapes with your own markup:
+
+```erb
+<%= skeleton label: "Loading candidate" do |s| %>
+  <div class="flex items-center gap-3">
+    <%= s.circle size: "3rem" %>
+    <div class="flex-1">
+      <%= s.text width: "60%" %>
+      <%= s.text width: "40%" %>
+    </div>
+  </div>
+  <%= s.text lines: 2 %>
+<% end %>
+```
+
+| Shape | Stands in for |
+|---|---|
+| `s.text(width:, lines:)` | A line of text in the surrounding font. `lines:` makes a paragraph with a shorter last line. |
+| `s.circle(size:)` | An avatar or round icon (default `2.5rem`). |
+| `s.block(height:, width:)` | An image, chart or map (default `8rem` tall, full width). |
+| `s.button(size:, width:)` | A `button_classes` button, `size: :small` or `:large`. |
+
+- **Nothing moves when content arrives.** Each shape is sized from what it
+  replaces: a text line fills exactly one line of the font it sits in, so a line
+  inside an `<h1>` is heading-sized, and a button shape matches a real button's
+  height.
+- **Styling:** every shape also takes `class:` and `style:`.
+- **Screen readers:** the shapes are hidden from them. They hear `label:`
+  ("Loading…", `unmagic.components.skeleton.loading`) once for the whole group.
+
+Outside a block, the same shapes are `skeleton_text`, `skeleton_circle`,
+`skeleton_block` and `skeleton_button`.
+
+Some components render a skeleton version of themselves, so it matches the real
+one:
+
+```erb
+<%= detail_list skeleton: true do |list| %>
+  <% list.item "Created" %>
+  <% list.item "Salary" %>
+<% end %>
+
+<%= page_header skeleton: true %>
+<%= card title: "Members", skeleton: true %>
+```
+
+Anything you pass still renders for real, and the rest becomes shapes:
+
+- **`detail_list`** keeps its labels and shows a bar for each value.
+- **`page_header`** shows a title bar, a description line and a button.
+  `description: false` leaves out the line.
+- **`card`** keeps its title. An empty body becomes three lines, or you can pass
+  a block to block out the body yourself.
+
+A skeleton pairs well with a lazy Turbo Frame:
+
+```erb
+<%= turbo_frame_tag "stats", src: stats_path, loading: :lazy do %>
+  <%= detail_list skeleton: true do |list| %>...<% end %>
+<% end %>
+```
+
+## Toasts
+
+Mount them once, in the layout:
+
+```erb
+<%= flash_toasts %>
+```
+
+Then set a flash as usual:
+
+```ruby
+redirect_to labels_path, notice: "Label saved."
+```
+
+The toast shows in the top-right corner and dismisses itself after five seconds
+(`duration:`, in milliseconds). It also has a dismiss button.
+
+- **Holding it open:** hovering or focusing a toast pauses its countdown. Letting
+  go resumes it, with at least a second left.
+- **Staying put:** the stack is `data-turbo-permanent`, so a toast on screen
+  survives a Drive visit or a morph refresh. A flash set before
+  `refresh_or_redirect` arrives with the refresh.
+- **Tone:** set by `config.flash_tones`. `notice` and `success` are good, `alert`
+  and `error` are bad, `warning` is warn, and anything else is info. A bad toast
+  interrupts screen readers with `role="alert"`; the rest are announced politely.
+- **Filtering:** pass the flashes to show when some aren't meant for the user:
+  `flash_toasts flash.to_hash.except("copy_link")`.
+
+To show a toast from a stream response, where there's no redirect to carry a
+flash:
+
+```ruby
+render turbo_stream: turbo_stream.toast("Invitation sent.")
+render turbo_stream: turbo_stream.toast("Couldn't reach Slack.", tone: :bad)
+```
+
+The stack sits in the browser's top layer, so a toast shows above an open dialog.
+It can't be hovered or dismissed until that dialog closes, because a modal dialog
+makes the rest of the page inert, but it still times out on its own.
+
+Needs `import "unmagic/components/toasts"`, which `import "unmagic/components"`
+includes. The dismiss button's label is `unmagic.components.toast.dismiss`
+("Dismiss").
+
 ## Development
 
 ```sh