unmagic-components 0.3.0 → 0.4.0

data/lib/unmagic/components/browser/catalog/ai_chat_slash_menu.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :ai_chat_slash_menu,
+  name: "Slash menu",
+  group: "AI chat",
+  helper: "ai_chat_slash_menu",
+  import: "unmagic/components/slash_menu",
+  description: "Commands offered on a slash. Every command is rendered and the typing filters them, so what can be " \
+               "offered is only ever what exists. Focus stays in the field; the menu takes the arrow keys, Enter and " \
+               "Tab while open.",
+  examples: [
+    { key: :composer, title: "In a composer", layout: :full,
+      description: "Type / in the box. Try /in, then Enter." }
+  ]

data/lib/unmagic/components/browser/catalog/ai_chat_tool_call.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :ai_chat_tool_call,
+  name: "Tool call",
+  group: "AI chat",
+  helper: "ai_chat_tool_call",
+  description: "One reach for a tool, from the ask to the answer, as a row. A run of them is joined by a line into a " \
+               "timeline, because four calls in one breath are one stretch of work, not four events.",
+  examples: [
+    { key: :run, title: "A run of calls", layout: :full,
+      description: "Rows join up, counting the hidden gap markers between them. A done call's glyph says what it was " \
+                   "about." },
+    { key: :states, title: "Every state", layout: :full,
+      description: "Queued, running (with a live clock and progress), waiting on a person, done, and failed." },
+    { key: :made, title: "What a call made", layout: :full,
+      description: "made keeps the output outside the fold, with the line running beside it." }
+  ]

data/lib/unmagic/components/browser/catalog/ai_chat_welcome.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :ai_chat_welcome,
+  name: "Welcome",
+  group: "AI chat",
+  helper: "ai_chat_welcome",
+  import: "unmagic/components/ai_chat",
+  description: "What an empty conversation says, and suggestions that start one. A good suggestion is runnable, " \
+               "naming the reader's own data where there is some.",
+  examples: [
+    { key: :suggestions, title: "With suggestions", layout: :full,
+      description: "Pressing one fills the composer below and sends it; the last only fills it." }
+  ]

data/lib/unmagic/components/browser/catalog/ai_chat_workspace.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :ai_chat_workspace,
+  name: "Workspace",
+  group: "AI chat",
+  helper: "ai_chat_workspace",
+  description: "The files an agent has put aside while it works, so you can see what it actually produced. A flat " \
+               "list of paths for now; a nested tree waits on the gem's tree view.",
+  examples: [
+    { key: :files, title: "Files, beside a plan",
+      description: "Two sections of one panel, with a divider between them. A file with a url is a link." }
+  ]

data/lib/unmagic/components/browser/catalog/avatar.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :avatar,
+  name: "Avatar",
+  helper: "avatar",
+  description: "A person's or organisation's picture, falling back to initials on one of six tints picked from " \
+               "the name — the same tint for the same name on every page and every server.",
+  examples: [
+    { key: :sizes, title: "Sizes and fallbacks",
+      description: "Three sizes, with and without an image. A broken image shows the initials through it." },
+    { key: :tints, title: "Tints",
+      description: "The tint comes from the name, so each person keeps their colour. tint: false is neutral." },
+    { key: :group, title: "A group",
+      description: "avatar_group stacks them, collapsing past max: into a counter that names the rest." }
+  ]

data/lib/unmagic/components/browser/catalog/badge.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :badge,
+  name: "Badge",
+  helper: "badge",
+  import: nil,
+  description: "A small pill of text: a status, a count, a label.",
+  examples: [
+    { key: :tones, title: "Tones" },
+    { key: :in_context, title: "Beside the thing it describes" }
+  ]

data/lib/unmagic/components/browser/catalog/board.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :board,
+  name: "Board",
+  helper: "board",
+  import: "unmagic/components",
+  description: "A Trello-style board: columns of cards, both reorderable by pointer or keyboard, with a way to add " \
+               "to each. Drops post to one endpoint (unmagic-sortable's), and the page morphs to the saved order.",
+  examples: [
+    { key: :live, title: "A working board", layout: :full,
+      description: "Drag cards within and between columns, drag a column by its header, or add a card or a list. " \
+                   "It's saved in your session. On a phone, press and hold a card or a column's header to lift it. " \
+                   "With the keyboard: Tab to a card or a column's grip, Space to pick it up, arrows to move it, " \
+                   "Space to drop, Escape to cancel." },
+    { key: :handles, title: "Cards with handles", layout: :full,
+      description: "A sortable_handle in a card makes only the grip drag it, so the rest of the card stays a link, " \
+                   "and on a touch screen the grip drags at once, without the long press." }
+  ]

data/lib/unmagic/components/browser/catalog/button.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :button,
+  name: "Button",
+  helper: "button_classes",
+  import: nil,
+  description: "The class string for a button, so the look composes with link_to, button_to and form.submit " \
+               "alike. Pick a variant for its weight and a size to sit beside other controls.",
+  examples: [
+    { key: :variants, title: "Variants",
+      description: "Default, primary, ghost and danger. Danger keeps the default's shape; only the label and hover warn." },
+    { key: :sizes, title: "Sizes",
+      description: "Small, default and large, each matching an input of the same size." }
+  ]

data/lib/unmagic/components/browser/catalog/callout.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :callout,
+  name: "Callout",
+  helper: "callout",
+  import: nil,
+  description: "A tinted note stating the state of something in place: a health check, a warning above a form. " \
+               "Each tone brings its own icon, so meaning never rests on colour alone.",
+  examples: [
+    { key: :tones, title: "Tones", layout: :full },
+    { key: :neutral, title: "Neutral", layout: :full,
+      description: "A neutral callout has no icon; icon: false drops it from the other tones too." }
+  ]

data/lib/unmagic/components/browser/catalog/card.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :card,
+  name: "Card",
+  helper: "card",
+  import: nil,
+  description: "A bordered surface for a section of a page, with an optional title, header actions and a " \
+               "tinted footer.",
+  examples: [
+    { key: :actions_and_footer, title: "Title, actions and footer" },
+    { key: :link, title: "A card that is one link",
+      description: "href: makes the whole card a link, for a row that opens a record. Nothing inside should be " \
+                   "a link or button of its own." },
+    { key: :flush_table, title: "Flush, with a table", layout: :full,
+      description: "flush: true drops the body's padding, so a table runs edge to edge." }
+  ]

data/lib/unmagic/components/browser/catalog/confirm.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :confirm,
+  name: "Confirm",
+  helper: nil,
+  import: "unmagic/components/confirm",
+  description: "A dialog in place of window.confirm for data-turbo-confirm. data-turbo-confirm-title, -accept " \
+               "and -variant=\"danger\" customise it, and confirm_dialog_template carries its words through I18n.",
+  examples: [
+    { key: :danger, title: "Danger",
+      description: "A custom accept label and the danger variant, for an action that destroys something." },
+    { key: :plain, title: "Plain",
+      description: "Only data-turbo-confirm, so the dialog uses its default title and buttons." }
+  ]

data/lib/unmagic/components/browser/catalog/copy_button.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :copy_button,
+  name: "Copy button",
+  helper: "copy_button",
+  import: "unmagic/components/clipboard",
+  description: "A button that copies text to the clipboard, showing a check for a moment once it has, and " \
+               "announcing it to screen readers.",
+  examples: [
+    { key: :from_element, title: "Copy from an element",
+      description: "from: copies the text of the element (or the value of the input) with that id, at the " \
+                   "moment of the click, so the text isn't duplicated into an attribute." },
+    { key: :with_label, title: "With a label",
+      description: "A block replaces the icon button with your own content." }
+  ]

data/lib/unmagic/components/browser/catalog/detail_list.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :detail_list,
+  name: "Detail list",
+  helper: "detail_list",
+  import: nil,
+  description: "A <dl> of a record's fields, laid out inline or stacked. A blank value renders as an em dash, " \
+               "so call sites don't each need .presence || \"—\".",
+  examples: [
+    { key: :inline, title: "Inline", layout: :full,
+      description: "Labels beside values. Notes is blank, so it shows an em dash." },
+    { key: :stacked, title: "Stacked", layout: :full,
+      description: "Small uppercase labels above values, two columns on wide screens." }
+  ]

data/lib/unmagic/components/browser/catalog/dialog.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :dialog,
+  name: "Dialog",
+  helper: "dialog",
+  import: "unmagic/components/modal",
+  description: "Native <dialog>s sharing one panel: a titled header with a close button, the body, and an " \
+               "optional footer. Load one from the server into the shared modal, or put one on the page.",
+  examples: [
+    { key: :modal, title: "Loaded into the shared modal", layout: :full,
+      description: "Clear the name and save to see a 422 keep the dialog open. A good save closes it in the " \
+                   "same render as the morph refresh. Slow shows the skeleton; Forbidden shows the error panel." },
+    { key: :dialog_tag, title: "Already on the page",
+      description: "dialog_tag and dialog_button open a dialog with no request." }
+  ]

data/lib/unmagic/components/browser/catalog/elapsed.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :elapsed,
+  name: "Elapsed",
+  helper: "elapsed_tag",
+  import: "unmagic/components/elapsed",
+  description: "A clock counting up from a moment the server named, or down to one. Work that takes a minute and " \
+               "work that has hung look the same behind a spinner; a number that keeps moving is the difference.",
+  examples: [
+    { key: :running, title: "Counting up",
+      description: "The server renders the current reading and the element keeps it moving, a second at a time." },
+    { key: :countdown, title: "Counting down",
+      description: "direction: :down stops at zero and fires unmagic-elapsed:end." }
+  ]

data/lib/unmagic/components/browser/catalog/empty_state.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :empty_state,
+  name: "Empty state",
+  helper: "empty_state",
+  import: nil,
+  description: "The dashed blank slate a list or table shows when there is nothing in it. It renders through " \
+               "the same empty_state seam as a table's, so an app that replaces one gets both.",
+  examples: [
+    { key: :default, title: "Default", layout: :full }
+  ]

data/lib/unmagic/components/browser/catalog/forms.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :forms,
+  name: "Form builder",
+  helper: "FormBuilder",
+  import: nil,
+  description: "The chrome around a form control — the wrapper, the label and its required marker, the hint " \
+               "and the error line — and the look of the controls it builds, through config.control_class.",
+  examples: [
+    { key: :fields, title: "Fields", layout: :full,
+      description: "field builds its control from as:, or takes one from a block; group lays fields out in a row." },
+    { key: :states, title: "Invalid, disabled and read-only", layout: :full,
+      description: "An attribute with errors marks its control aria-invalid and reads the errors underneath." },
+    { key: :control_classes, title: "control_classes, outside a builder", layout: :full,
+      description: "A select_tag or a hand-written input wears the same classes, sized to sit level with buttons." },
+    { key: :autogrow, title: "Autogrowing textarea", layout: :full,
+      description: "Grows from its rows up to its max-height, then scrolls. Needs import \"unmagic/components/autogrow\"." },
+    { key: :uuid_field, title: "UUID field", layout: :full,
+      description: "A hidden field holding a fresh UUIDv7, minted again when the element upgrades and on every " \
+                   "form reset. Needs import \"unmagic/components/uuid_input\"." }
+  ]

data/lib/unmagic/components/browser/catalog/local_time.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :local_time,
+  name: "Local time",
+  helper: "local_time_tag",
+  import: "unmagic/components/time",
+  description: "A timestamp shown in the viewer's own locale and time zone, formatted by the browser with Intl. " \
+               "Until the element upgrades, the server's rendering in Time.zone shows instead.",
+  examples: [
+    { key: :relative, title: "Relative, keeping itself current", layout: :full,
+      description: "format: :relative stays current on a shared timer; compact: true shortens it to \"5m\"." },
+    { key: :absolute, title: "Absolute, in the viewer's zone", layout: :full }
+  ]

data/lib/unmagic/components/browser/catalog/menu.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :menu,
+  name: "Menu",
+  helper: "menu",
+  import: "unmagic/components/menu",
+  description: "A dropdown of actions built on <details>. It closes on an outside click, Escape, choosing an " \
+               "item, or a Turbo navigation, and arrow keys, Home and End move between items.",
+  examples: [
+    { key: :labelled, title: "With a label",
+      description: "A text trigger with a chevron, lined up with the trigger's left edge." },
+    { key: :actions, title: "Icon trigger with actions",
+      description: "With no label the trigger is a ⋮ button. Items can be button_to actions, and tone: :danger " \
+                   "pairs with a confirm." }
+  ]

data/lib/unmagic/components/browser/catalog/page_header.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :page_header,
+  name: "Page header",
+  helper: "page_header",
+  import: nil,
+  description: "The top of a page: a back link, the title with its badges, a description, and the page's " \
+               "actions on the right.",
+  examples: [
+    { key: :default, title: "Back link, badges and actions", layout: :full },
+    { key: :with_leading, title: "With something before the title", layout: :full,
+      description: "header.leading takes markup for an avatar or icon; title and description take blocks too." }
+  ]

data/lib/unmagic/components/browser/catalog/skeleton.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :skeleton,
+  name: "Skeleton",
+  helper: "skeleton",
+  import: nil,
+  description: "Blocks out an interface while it loads. Shapes take their size from what they stand in for, " \
+               "and screen readers hear one \"Loading…\" instead of every shape. Each example sits beside the " \
+               "real thing, so a difference in size shows at a glance.",
+  examples: [
+    { key: :blocking_out, title: "Blocking out your own layout", layout: :full,
+      description: "skeleton yields s.text, s.circle, s.block and s.button to arrange with your own markup." },
+    { key: :text_and_button, title: "skeleton_text and skeleton_button", layout: :full,
+      description: "A text line fills one line of its font; a button shape is a real button's height." },
+    { key: :page_header, title: "page_header skeleton: true", layout: :full },
+    { key: :detail_list, title: "detail_list skeleton: true", layout: :full },
+    { key: :card, title: "card skeleton: true", layout: :full }
+  ]

data/lib/unmagic/components/browser/catalog/sortable_list.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :sortable_list,
+  name: "Sortable list",
+  helper: "sortable_list",
+  import: "unmagic/components/sortable",
+  description: "A list whose items can be dragged, or moved with the keyboard, into a new place — here or in another " \
+               "list sharing its namespace. A drop fires unmagic-sortable:move and posts the move.",
+  examples: [
+    { key: :handles, title: "With handles",
+      description: "Only the grip drags, and the grip is the keyboard stop. Nothing is posted here, so the event is " \
+                   "shown below the list." },
+    { key: :grid, title: "A wrapping grid", layout: :full,
+      description: "orientation: :grid. The drop slot follows reading order, and every arrow key moves." },
+    { key: :connected, title: "Two lists, one namespace", layout: :full,
+      description: "Items move between lists that share a namespace. Left and Right move a held item across." }
+  ]

data/lib/unmagic/components/browser/catalog/streaming_markdown.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :streaming_markdown,
+  name: "Streaming Markdown",
+  group: "AI chat",
+  helper: "streaming_markdown_tag",
+  import: "unmagic/components/streaming_markdown",
+  description: "Server-rendered HTML revealed at a steady pace as fuller renders of it arrive, so a reply reads as " \
+               "one smooth stream rather than the bursts it lands in. Parsing stays on the server; the element only " \
+               "reveals.",
+  examples: [
+    { key: :reveal, title: "A reply arriving in bursts", layout: :full,
+      description: "Press Play: the renders arrive unevenly, the reveal doesn't. Lists never flicker as they grow. " \
+                   "Under reduced motion each render paints at once." },
+    { key: :stopped, title: "Stopped mid-reply", layout: :full,
+      description: "Stop swaps in a final element, and every flush still on its way is refused." }
+  ]

data/lib/unmagic/components/browser/catalog/table.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :table,
+  name: "Table",
+  helper: "table_for",
+  import: nil,
+  description: "Declarative index tables in the spirit of form_for: describe the columns, and the table " \
+               "draws the chrome — sortable headers, empty states, companion rows and pagination.",
+  examples: [
+    { key: :sortable, title: "Sortable, numeric and aligned", layout: :full,
+      description: "Click a sortable header to toggle ?sort and ?direction. The note under Ada is a companion row." },
+    { key: :empty, title: "Empty", layout: :full },
+    { key: :deferred, title: "Deferred", layout: :full,
+      description: "The first render never touches the collection. Reload to watch the skeleton swap for " \
+                   "the rows without the columns shifting." },
+    { key: :table_tag, title: "A static table from plain data", layout: :full }
+  ]

data/lib/unmagic/components/browser/catalog/tabs.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :tabs,
+  name: "Tabs",
+  helper: "tabs",
+  import: "unmagic/components/tabs",
+  description: "A row of tabs: panels switched in the page with the ARIA tab pattern, or links to separate " \
+               "pages rendered on the server.",
+  examples: [
+    { key: :panels, title: "Panels in the page", layout: :full,
+      description: "Arrow keys, Home and End move between tabs. A disabled tab shows its reason, and with an " \
+                   "id: the choice survives a reload." },
+    { key: :links, title: "Links to separate pages",
+      description: "Tabs with href: need no script; mark the current one active: true." }
+  ]

data/lib/unmagic/components/browser/catalog/toast.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :toast,
+  name: "Toast",
+  helper: "flash_toasts",
+  import: "unmagic/components/toasts",
+  description: "Flashes and stream responses as toasts that dismiss themselves, pause while hovered or " \
+               "focused, and survive Drive visits and morph refreshes.",
+  examples: [
+    { key: :flash, title: "From a flash, after a redirect", layout: :full,
+      description: "Each button sets flash[type] and redirects back. Hover a toast to hold it open." },
+    { key: :stream, title: "From a stream response",
+      description: "turbo_stream.toast pops one without a redirect." },
+    { key: :above_dialog, title: "Above an open dialog",
+      description: "A toast streamed from a dialog shows above it, and times out even though the dialog " \
+                   "makes it inert." }
+  ]

data/lib/unmagic/components/browser/catalog/tooltip.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Catalog.component :tooltip,
+  name: "Tooltip",
+  helper: "tooltip",
+  import: "unmagic/components/tooltip",
+  description: "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.",
+  examples: [
+    { key: :term, title: "A term in a sentence",
+      description: "Plain text content is styled as a term — a dashed underline — and made focusable." },
+    { key: :placement, title: "Placement and edges", layout: :full,
+      description: "placement: :bottom flips above when there's no room; a hint near the edge is clamped on screen." }
+  ]

data/lib/unmagic/components/browser/config/routes.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+Unmagic::Components::Browser::Engine.routes.draw do
+  root to: "pages#overview"
+  get "installation", to: "pages#installation"
+  get "theming", to: "pages#theming"
+  get "components/:slug", to: "pages#component", as: :component
+
+  # What the dialog and toast examples talk to.
+  get "dialogs/profile", to: "demos#edit_profile", as: :profile_dialog
+  patch "dialogs/profile", to: "demos#update_profile"
+  delete "dialogs/profile", to: "demos#destroy_profile"
+  get "dialogs/slow", to: "demos#slow_dialog", as: :slow_dialog
+  get "dialogs/forbidden", to: "demos#forbidden_dialog", as: :forbidden_dialog
+  post "toasts/flash", to: "demos#flash_toast", as: :flash_toast
+  post "toasts/stream", to: "demos#stream_toast", as: :stream_toast
+
+  # What the AI chat composer example talks to.
+  post "ai_chat/messages", to: "demos#ai_chat_message", as: :ai_chat_messages
+  post "ai_chat/stop", to: "demos#ai_chat_stop", as: :ai_chat_stop
+
+  # What the board example talks to.
+  patch "board/order", to: "demos#board_order", as: :board_order
+  post "board/cards", to: "demos#board_card", as: :board_cards
+  post "board/columns", to: "demos#board_column", as: :board_columns
+  delete "board", to: "demos#board_reset", as: :board
+
+  # The stylesheet, the components' JavaScript and Turbo, served from the gems
+  # themselves. Each URL carries its file's mtime, so it can be cached for good.
+  Unmagic::Components::Browser.asset_roots.each do |kind, root|
+    mount Rack::Files.new(root.to_s, "cache-control" => "public, max-age=31536000, immutable") => "assets/#{kind}", as: nil
+  end
+
+  # The old one-page-per-group URLs. A relative redirect keeps the mount prefix.
+  {
+    "deferred" => "table", "dialogs" => "dialog", "toasts" => "toast", "primitives" => "card",
+    "elements" => "tooltip", "skeletons" => "skeleton", "forms" => "forms"
+  }.each do |old, slug|
+    get old, to: redirect("components/#{slug}")
+  end
+end

data/lib/unmagic/components/browser/tailwind/browser.css

@@ -0,0 +1,33 @@
+/* The browser's stylesheet, prebuilt by `rake browser:css` into
+   ../assets/browser.css and shipped with the gem, so a host mounting the browser
+   compiles nothing. It is what a host's app/assets/tailwind/application.css
+   holds, except that the gem's CSS is imported by path.
+
+   The dark variant follows the browser's data-theme toggle rather than the
+   system setting, the way a host with its own theme switch would set it up.
+
+   The browser's own pages and examples are styled with utilities, so its app/
+   and catalog/ are scanned. The components' CSS arrives through the import. */
+@import "tailwindcss" source(none);
+@source "../app";
+@source "../catalog";
+
+@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
+
+@import "../../../../../app/assets/tailwind/unmagic_components/engine.css";
+
+/* An example's Preview/Code switch is the gem's tabs, lifted beside the
+   example's heading rather than above its panels. */
+.PreviewExample {
+  position: relative;
+}
+
+.PreviewExample__tabs > .UnmagicTabs__list {
+  position: absolute;
+  top: 0;
+  right: 0;
+}
+
+.PreviewExample__tabs > .UnmagicTabs__panel {
+  padding-top: 0;
+}

data/lib/unmagic/components/browser.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Unmagic
+  module Components
+    # A browser for the components, which a host mounts to look through every
+    # component, its examples and their source inside its own app:
+    #
+    #   mount Unmagic::Components::Browser::Engine => "/unmagic/components" if Rails.env.development?
+    #
+    # It is self-contained. Its stylesheet is prebuilt with the gem's default theme
+    # (rake browser:css), and it serves that, the components' JavaScript and Turbo
+    # itself, under its own importmap, so a host changes none of its own CSS or JS.
+    # turbo-rails has to be in the bundle.
+    module Browser
+      # Its root is this directory's browser/, not the gem root: the main engine's
+      # root is the gem root, so anything in the top-level app/ is autoloaded into
+      # every host.
+      class Engine < ::Rails::Engine
+        isolate_namespace Unmagic::Components::Browser
+
+        config.root = File.expand_path("browser", __dir__)
+      end
+
+      class << self
+        def root = Engine.root
+
+        # What the browser serves under <mount>/assets/<kind>/, by kind.
+        def asset_roots
+          roots = {
+            "stylesheets" => root.join("assets"),
+            "javascripts" => Components::Engine.root.join("app/assets/javascripts")
+          }
+          roots["turbo"] = ::Turbo::Engine.root.join("app/assets/javascripts") if defined?(::Turbo::Engine)
+          roots
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/components/configuration.rb

@@ -7,7 +7,8 @@ module Unmagic
     # library. An app that already owns these concerns points them at its own
     # versions in an initializer.
     class Configuration
-      attr_writer :empty_state, :pagination, :pagy_for, :submit_class, :control_class, :modal_frame_id, :flash_tones
+      attr_writer :empty_state, :pagination, :pagy_for, :submit_class, :control_class, :modal_frame_id, :flash_tones,
+        :code_block, :sortable_item, :sortable_url
 
       # The tone each flash type's toast wears, keyed by the flash type as a string.
       # A type that isn't listed is :info.
@@ -50,6 +51,35 @@ module Unmagic
         @submit_class ||= ->(_view, variant) { "UnmagicButton UnmagicButton--#{variant}" }
       end
 
+      # Renders a block of code: a tool call's payload, a failure's backtrace. Called
+      # with (view, source, language), where language is a symbol such as :json or
+      # :plaintext, and returns markup. The default is an unhighlighted
+      # <pre><code>; an app with a highlighter hands back its own.
+      #
+      #   config.code_block = ->(view, source, language) { view.highlight_code(source, language: language) }
+      def code_block
+        @code_block ||= lambda do |view, source, language|
+          view.tag.pre(view.tag.code(source, class: ("language-#{language}" if language)))
+        end
+      end
+
+      # What a sortable item carries for a record: its key and its rank. Called with
+      # (view, record); returns { key:, rank: }. unmagic-sortable sets this to its
+      # signed, scoped keys; the default is the record's id and sortable_rank.
+      def sortable_item
+        @sortable_item ||= lambda do |_view, record|
+          rank = record.try(:sortable_rank)
+          { key: record.to_param, rank: rank.is_a?(BigDecimal) ? rank.to_s("F") : rank&.to_s }
+        end
+      end
+
+      # Where a sortable list posts a drop when it isn't given url:. Called with
+      # (view); nil means a drop only fires unmagic-sortable:move for your own script.
+      # unmagic-sortable points it at its endpoint.
+      def sortable_url
+        @sortable_url ||= ->(_view) { nil }
+      end
+
       # The classes on a form control. Called with (view, kind), where kind is one
       # of Control::CLASSES' keys (:input, :select, :check…); return an app's own
       # classes, or nil to leave the control unstyled.