hanami-turbo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25698bfc47dcbbad1d9fe915efc56b9baff1286e5d8f74137baeb704f90d3562
+  data.tar.gz: b9daa12a59ac36e46a98a23d2e5558ec2af132db1a18d8ee8372a64ffd112dba
+SHA512:
+  metadata.gz: 2bf61aa86174a526b17b5a08b48d888b75b424c172d89f2fffca79bddaa7e8c1e0ca0fa310312851097dfd2d96b845ace92fd856e866cf38be756f5e0f1494db
+  data.tar.gz: c92a9bd136e2b83dfce19c839d5cc038ff61e51e9c3b890bf9ccc86997dfca4d20eb4dc3af951e1e57d537abecd24aec57cd6d0a92ec250006dfc19a86cd64a9

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+- Initial release.
+- Add `button_to`, for one-button forms with Turbo confirmations (`data: {turbo_confirm: "..."}`).
+- Support custom stream actions: include a module into `Hanami::Turbo::StreamBuilder`. Actions may have no target, and `turbo_stream_action_tag` matches turbo-rails.

data/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2026 Andrea Fomera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,415 @@
+# hanami-turbo
+
+[Hotwire Turbo](https://turbo.hotwired.dev) support for Hanami apps.
+
+- Renders `.turbo_stream` templates for Turbo Stream requests (without a layout), falling back to
+  HTML when a view has no stream template.
+- A `turbo_stream` builder, `turbo_frame_tag`, and `dom_id`/`dom_class` helpers for templates.
+- `button_to`, for buttons that submit (with Turbo confirmations, like Rails).
+- [Custom stream actions](#custom-stream-actions), added like in turbo-rails
+  (`turbo_stream_action_tag` included).
+- `303 See Other` redirects after non-GET requests, as Turbo requires.
+- Optional lighter layouts for Turbo Frame requests.
+
+Built against the main branches of Hanami and its gems. See
+[hanami-turbo-example](../hanami-turbo-example) for a complete app using every feature.
+
+## Setup
+
+```ruby
+# Gemfile
+gem "hanami-turbo"
+```
+
+```ruby
+# config/app.rb
+require "hanami"
+require "hanami/turbo"
+
+module Bookshelf
+  class App < Hanami::App
+    Hanami::Turbo.install(config)
+  end
+end
+```
+
+`install` registers the `turbo_stream` format (`text/vnd.turbo-stream.html`) and adds it to your
+accepted formats. If your app accepts any format (the default), it keeps doing so.
+
+Then add Turbo to your JavaScript, and the CSRF meta tags to your layout, so Turbo can send the
+token with requests made from links and buttons:
+
+```sh
+npm install @hotwired/turbo
+```
+
+```js
+// app/assets/js/app.js
+import "@hotwired/turbo";
+```
+
+```erb
+<%# app/templates/layouts/app.html.erb, inside <head> %>
+<%= csrf_meta_tags&.html_safe %>
+<%= javascript_tag "app", defer: true %>
+```
+
+Load the script in `<head>` (with `defer`), not at the end of `<body>`: Turbo replaces the body on
+each visit, and would otherwise evaluate it again.
+
+On Hanami main, `csrf_meta_tags` returns a string that isn't marked HTML safe, so it is escaped
+unless you call `html_safe` as above. (Sessions must be enabled for CSRF tokens to exist.)
+
+## Turbo Streams
+
+Turbo form submissions accept stream responses. When a view has a `.turbo_stream` template, it is
+rendered for these requests, with no layout:
+
+```erb
+<%# app/templates/books/create.turbo_stream.erb %>
+<%= turbo_stream.prepend "books", partial: "books/book", locals: {book:} %>
+<%= turbo_stream.update "books_count", books_count.to_s %>
+<%= turbo_stream.replace "new_book" do %>
+  <%= render "books/form" %>
+<% end %>
+```
+
+Views without a `.turbo_stream` template render HTML as usual, so you can add stream templates only
+where you want them.
+
+Partials render in the stream format when one exists (`_book.turbo_stream.erb`), and otherwise as
+HTML, so the same `_book.html.erb` serves full pages and streams.
+
+The builder supports every Turbo action: `append`, `prepend`, `replace`, `update`, `before`,
+`after`, `remove` and `refresh`, plus `*_all` variants that take a CSS selector (`update_all
+".count", "3"`), `method: :morph`, and `action(:custom_action, target, ...)` for custom actions.
+Targets can be strings or records.
+
+A common shape for actions that respond to Turbo with streams, and redirect everyone else:
+
+```ruby
+def handle(request, response)
+  book = book_repo.create(request.params[:book])
+
+  if request.turbo_stream?
+    response.render(view, book:)   # renders create.turbo_stream.erb
+  else
+    response.redirect_to routes.path(:books)
+  end
+end
+```
+
+Error responses that weren't rendered from a stream template (such as `halt 404`) are sent as HTML
+even when the request negotiated a stream, so Turbo shows them instead of silently ignoring them.
+
+Custom actions (your own, beyond Turbo's built-ins) are covered in
+[Custom stream actions](#custom-stream-actions) below.
+
+To pick a format yourself, pass it to `render`; explicit options always win:
+
+```ruby
+res.render(view, format: :html)
+```
+
+## Custom stream actions
+
+Turbo's built-in actions cover changing the DOM, but you can add your own, such as showing a toast,
+highlighting an element, or logging to the console. A custom action has two halves:
+
+1. **Ruby**: a method on the `turbo_stream` builder that renders `<turbo-stream action="...">`.
+2. **JavaScript**: a function on `Turbo.StreamActions` that runs when that element arrives.
+
+This works the way it does in turbo-rails, and modules written for turbo-rails can be reused as they
+are (see [Porting from turbo-rails](#porting-from-turbo-rails)).
+
+### 1. Define the actions
+
+Write a module of methods, and include it into `Hanami::Turbo::StreamBuilder`:
+
+```ruby
+# config/turbo_stream_actions.rb
+module Bookshelf
+  module TurboStreamActions
+    # No target: the JavaScript decides where the toast goes.
+    def toast(message, level: "info")
+      action(:toast, nil, message:, level:)
+    end
+
+    # A target: a DOM id string, or a record (turned into an id with dom_id).
+    def highlight(target)
+      action(:highlight, target)
+    end
+
+    # A target and content, rendered from a partial.
+    def flash_message(target, message)
+      action(:flash_message, target, partial: "shared/flash", locals: {message:})
+    end
+  end
+end
+
+Hanami::Turbo::StreamBuilder.include(Bookshelf::TurboStreamActions)
+```
+
+Require it from your app class, so it's loaded before anything renders, whether in the server, the
+console, or tests:
+
+```ruby
+# config/app.rb
+require "hanami"
+require "hanami/turbo"
+require_relative "turbo_stream_actions"
+```
+
+Keep this file out of `app/` and `lib/<your_app>/`: those are autoloaded, and the module is included
+once, at boot. Like a Rails initializer, changes need a server restart (code reloading won't pick
+them up).
+
+### 2. Use them in stream templates
+
+```erb
+<%# app/templates/books/create.turbo_stream.erb %>
+<%= turbo_stream.prepend "books", partial: "books/book", locals: {book:} %>
+<%= turbo_stream.toast "Added #{book.title}", level: "success" %>
+<%= turbo_stream.highlight book %>
+```
+
+This renders:
+
+```html
+<turbo-stream action="prepend" target="books"><template>...</template></turbo-stream>
+<turbo-stream action="toast" message="Added Dune" level="success"></turbo-stream>
+<turbo-stream action="highlight" target="book_42"></turbo-stream>
+```
+
+For a one-off action, you don't need a module. Use `action` directly, or the
+`turbo_stream_action_tag` view helper:
+
+```erb
+<%= turbo_stream.action :scroll_to, book, behavior: "smooth" %>
+<%= turbo_stream_action_tag :console_log, message: "Hello" %>
+```
+
+### 3. Handle them in JavaScript
+
+Register a handler for each action on `StreamActions`. Inside it, `this` is the `<turbo-stream>`
+element:
+
+```js
+// app/assets/js/stream_actions.js, imported from app.js
+import { StreamActions } from "@hotwired/turbo";
+
+StreamActions.toast = function () {
+  const toast = document.createElement("div");
+  toast.className = `toast toast-${this.getAttribute("level")}`;
+  toast.setAttribute("role", "status");
+  toast.textContent = this.getAttribute("message");
+  document.getElementById("toasts").append(toast);
+  setTimeout(() => toast.remove(), 4000);
+};
+
+StreamActions.highlight = function () {
+  this.targetElements.forEach((element) => element.classList.add("highlight"));
+};
+
+StreamActions.flash_message = function () {
+  this.targetElements.forEach((element) => element.replaceChildren(this.templateContent));
+};
+```
+
+Useful properties of the stream element:
+
+| | |
+| --- | --- |
+| `this.getAttribute("name")` | an attribute you passed from Ruby |
+| `this.targetElements` | the elements matching `target` (by id) or `targets` (by CSS selector) |
+| `this.templateContent` | a copy of the `<template>` content, if any |
+
+Import the handlers in your entry point (`import "./stream_actions.js"`), so they're registered
+before any stream arrives. If no handler is registered for an action, Turbo raises an error in the
+browser console.
+
+### The building blocks
+
+Your methods (and templates) can use these builder methods:
+
+| Method | Renders |
+| --- | --- |
+| `action(name, target, content = nil, **options, &block)` | an action for one target. `target` may be `nil`. |
+| `action_all(name, targets, content = nil, **options, &block)` | an action for every element matching the `targets` CSS selector. |
+| `turbo_stream_action_tag(name, target: nil, targets: nil, template: nil, **attributes)` | the turbo-rails equivalent, with keyword arguments. |
+
+Inside your methods, `scope` is the scope of the template being rendered, so you can use its
+helpers, `routes` and locals, just as turbo-rails methods use `@view_context`:
+
+```ruby
+def toast_with_link(message, book)
+  action(:toast, nil, message:, href: scope.routes.path(:book, id: book.id))
+end
+```
+
+How the arguments become HTML:
+
+- **Content** goes in a `<template>`, from (in order of precedence) a block, `partial:` with
+  `locals:`, or the `content` argument. Strings are HTML-escaped unless marked safe
+  (`.html_safe`). Partials are rendered as stream partials if they exist (`_flash.turbo_stream.erb`),
+  and otherwise as HTML (`_flash.html.erb`).
+- **A `<template>` is added only when there's content.** Turbo's built-in content actions (`append`,
+  `update`, etc.) always get one, since Turbo expects it.
+- **Other keyword arguments become attributes**, with their names used as given. `request_id: 1`
+  renders `request_id="1"`, so for a dashed name use a string key (`"request-id": 1`). A `data:` hash
+  becomes `data-*` attributes, with keys dasherized and non-string values encoded as JSON.
+  Attributes with `nil` values are left out, and `true` renders as `"true"`.
+- **`partial:`, `locals:` and `method:` are reserved**: the first two supply content, and `method:`
+  is the attribute Turbo uses for morphing (`method: :morph`).
+
+### Testing
+
+Custom actions render plain HTML, so request specs can check for them like any other stream:
+
+```ruby
+it "shows a toast after creating a book" do
+  post "/books", {book: {title: "Dune", author: "Frank Herbert"}},
+    {"HTTP_ACCEPT" => "text/vnd.turbo-stream.html, text/html"}
+
+  expect(last_response.body).to include(
+    %(<turbo-stream action="toast" message="Added Dune" level="success"></turbo-stream>)
+  )
+end
+```
+
+The JavaScript half needs a browser test (for example with Capybara or Playwright).
+
+### Porting from turbo-rails
+
+| turbo-rails | hanami-turbo |
+| --- | --- |
+| `Turbo::Streams::TagBuilder.prepend(MyActions)` | `Hanami::Turbo::StreamBuilder.include(MyActions)` |
+| Module in `config/initializers/` | Module in `config/`, required from `config/app.rb` |
+| `turbo_stream_action_tag :name, target:, targets:, template:, **attributes` | the same |
+| `action(:name, target, content)` in TagBuilder methods | the same, plus `partial:`/`locals:` and blocks |
+| `@view_context` in TagBuilder methods | `scope`: the template's scope, with its helpers and `routes` |
+| `Turbo.StreamActions.name = function () { ... }` | the same (it's Turbo's JavaScript API) |
+
+## Turbo Frames
+
+```erb
+<%= turbo_frame_tag "tray" do %>...<% end %>
+<%= turbo_frame_tag book %>                       <%# id="book_42" %>
+<%= turbo_frame_tag book, :comments, src: routes.path(:book_comments, id: book.id), loading: :lazy %>
+```
+
+Turbo only uses the matching `<turbo-frame>` from a frame request's response. To skip rendering the
+full layout for these requests:
+
+```ruby
+Hanami::Turbo.config.frame_layout = false     # no layout
+Hanami::Turbo.config.frame_layout = "frame"   # or a lighter layout, e.g. one with just <head>
+```
+
+In actions, `req.turbo_frame` returns the requesting frame's id, and `req.turbo_frame?` and
+`req.turbo_stream?` tell you what kind of Turbo request you have.
+
+## Buttons, confirmations and non-GET links
+
+`button_to` renders a one-button form (with the CSRF token, and `_method` for PATCH, PUT and DELETE),
+like Rails. Attributes go on the button; `form:` sets the form's own attributes, and `params:` adds
+hidden fields.
+
+```erb
+<%= button_to "Delete", routes.path(:book, id: book.id),
+      method: :delete,
+      data: {turbo_confirm: "Delete #{book.title}?"} %>
+
+<%= button_to "Archive", routes.path(:archive_book, id: book.id), form: {class: "inline"}, params: {return_to: "/books"} %>
+```
+
+Turbo asks for confirmation before submitting any form, or form button, with `data-turbo-confirm`.
+You can put it on the button (as above) or the form (`form: {data: {turbo_confirm: "..."}}`), as
+Rails apps do.
+
+Links can make non-GET requests through Turbo, with or without confirmation, using `link_to`:
+
+```erb
+<%= link_to "Delete", routes.path(:book, id: book.id),
+      data: {turbo_method: :delete, turbo_confirm: "Are you sure?"} %>
+```
+
+Turbo sends these as real `DELETE` (etc.) requests, with the CSRF token from `csrf_meta_tags` in an
+`X-CSRF-Token` header. Prefer `button_to` for anything destructive: unlike links, buttons also work
+without JavaScript.
+
+### Custom confirmation dialogs
+
+By default Turbo uses the browser's `confirm()`. To show your own dialog, set
+`Turbo.config.forms.confirm` to a function returning a promise of true or false:
+
+```erb
+<%# in the layout %>
+<dialog id="confirm-dialog">
+  <form method="dialog">
+    <p id="confirm-message"></p>
+    <button value="cancel">Cancel</button>
+    <button value="confirm" data-confirm-button>Confirm</button>
+  </form>
+</dialog>
+```
+
+```js
+import * as Turbo from "@hotwired/turbo";
+
+Turbo.config.forms.confirm = (message, form, submitter) => {
+  const dialog = document.getElementById("confirm-dialog");
+  dialog.querySelector("#confirm-message").textContent = message;
+  dialog.querySelector("[data-confirm-button]").textContent =
+    submitter?.dataset.turboConfirmButton || form.dataset.turboConfirmButton || "Confirm";
+  dialog.showModal();
+
+  return new Promise((resolve) => {
+    dialog.addEventListener("close", () => resolve(dialog.returnValue === "confirm"), { once: true });
+  });
+};
+```
+
+The `data-turbo-confirm-button` attribute is a convention from this snippet (not part of Turbo)
+for customising the confirm button's label per button:
+
+```erb
+<%= button_to "Delete", path, method: :delete,
+      data: {turbo_confirm: "Delete this book?", turbo_confirm_button: "Delete book"} %>
+```
+
+(On Turbo 7, use `Turbo.setConfirmMethod(fn)` instead; Turbo 8 deprecates it.)
+
+## DOM ids
+
+`dom_id` and `dom_class` name records after their class, for use as frame ids and stream targets:
+
+```erb
+<%= dom_id(book) %>          <%# "book_42" %>
+<%= dom_id(book, :edit) %>   <%# "edit_book_42" %>
+<%= dom_id(Book.new) %>      <%# "new_book" %>
+```
+
+Decorated parts also respond to `dom_id` and `dom_class` directly: `<li id="<%= book.dom_id %>">`.
+
+## Forms and redirects
+
+Turbo expects:
+
+- **A redirect after a successful submission.** For non-GET requests, `res.redirect_to` now defaults
+  to `303 See Other`. Browsers repeat PATCH and DELETE requests when following a 302, so this is
+  required for those; for POST it behaves the same as a 302. An explicit `status:` is always kept.
+  To turn this off: `Hanami::Turbo.config.see_other_redirects = false`.
+- **A 4xx status when re-rendering a form with errors.** Turbo ignores a `200` response to a form
+  submission, so set `res.status = 422` before rendering.
+
+## How it works
+
+The gem extends Hanami at public extension points where it can: it prepends `Response#render` and
+`Response#redirect_to`, includes helpers into the standard Hanami view helpers, and adds methods to
+`Request` and `View::Part`. The few calls into hanami-view's private API (checking a template
+exists, and rendering a partial in another format) are kept in `Hanami::Turbo::ViewInternals`.
+
+## License
+
+MIT

data/lib/hanami/turbo/action.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # Turbo-aware finishing for `Hanami::Action`.
+    #
+    # @api private
+    module Action
+      private
+
+      # Sends error responses as HTML unless they really are Turbo Streams.
+      #
+      # A Turbo form submission negotiates the stream format before the action runs, so a `halt 404`
+      # (or any other error response not rendered from a stream template) would otherwise go out as
+      # a stream. Turbo would treat it as empty and do nothing. As HTML, Turbo shows it instead.
+      #
+      # This prepends `Action#finish`, which is private API, but is also how Hanami's own app
+      # integration hooks into actions.
+      def finish(request, response, halted)
+        super.tap do
+          response.format = :html if response.turbo_stream_mismatch?
+        end
+      end
+    end
+  end
+end
+
+Hanami::Action.prepend(Hanami::Turbo::Action)

data/lib/hanami/turbo/dom_id.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # Builds DOM ids and classes for records, for use as Turbo Frame ids and Turbo Stream targets.
+    #
+    # Records may be view parts (their value is used) or any object responding to `#id`. The name
+    # comes from the record's class, so a `Bookshelf::Structs::Book` with id 42 has the DOM id
+    # `"book_42"`.
+    #
+    # @api public
+    module DomId
+      NEW = "new"
+      JOIN = "_"
+
+      module_function
+
+      # Returns the DOM id for a record.
+      #
+      # @example
+      #   dom_id(book)              # => "book_42"
+      #   dom_id(book, :comments)   # => "comments_book_42"
+      #   dom_id(Book.new)          # => "new_book"
+      #   dom_id(Book.new, :edit)   # => "edit_book"
+      #   dom_id("custom_target")   # => "custom_target"
+      #
+      # @param record [Object, String, Symbol] the record, or a ready-made id
+      # @param prefix [String, Symbol, nil] optional prefix
+      #
+      # @return [String]
+      #
+      # @api public
+      def dom_id(record, prefix = nil, inflector: Turbo.inflector)
+        return record.to_s if record.is_a?(String) || record.is_a?(Symbol)
+
+        value = unwrap(record)
+        id = value.id if value.respond_to?(:id)
+
+        if id.nil?
+          dom_class(record, prefix || NEW, inflector:)
+        else
+          [dom_class(record, prefix, inflector:), id].join(JOIN)
+        end
+      end
+
+      # Returns the DOM class for a record (its singular name, with an optional prefix).
+      #
+      # @param record [Object] the record
+      # @param prefix [String, Symbol, nil] optional prefix
+      #
+      # @return [String]
+      #
+      # @api public
+      def dom_class(record, prefix = nil, inflector: Turbo.inflector)
+        name = record_name(record, inflector)
+        prefix ? [prefix, name].join(JOIN) : name
+      end
+
+      # @api private
+      def record_name(record, inflector)
+        value = unwrap(record)
+        klass = value.is_a?(Class) ? value : value.class
+
+        # Anonymous classes (and plain hashes or structs from ad hoc data) have no useful class name,
+        # so fall back to the part's name, when there is one.
+        if klass.name.nil? || [Hash, Struct, Data, Object].include?(klass)
+          return inflector.singularize(record._name.to_s) if record.respond_to?(:_name)
+
+          raise ArgumentError, "cannot infer a DOM id name for #{value.inspect}"
+        end
+
+        inflector.underscore(inflector.demodulize(klass.name))
+      end
+
+      # @api private
+      def unwrap(record)
+        record.is_a?(Hanami::View::Part) ? record._value : record
+      end
+    end
+  end
+end

data/lib/hanami/turbo/helpers.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # View helpers for Turbo, included in the standard Hanami helpers (so available in templates,
+    # scopes, and via `helpers` in parts).
+    #
+    # @api public
+    module Helpers
+      # Returns a builder for `<turbo-stream>` elements.
+      #
+      # @return [StreamBuilder]
+      #
+      # @see StreamBuilder
+      #
+      # @api public
+      def turbo_stream
+        StreamBuilder.new(self)
+      end
+
+      # Returns a `<turbo-stream>` element, like turbo-rails' helper of the same name.
+      #
+      # @see StreamBuilder#turbo_stream_action_tag
+      #
+      # @api public
+      def turbo_stream_action_tag(...)
+        turbo_stream.turbo_stream_action_tag(...)
+      end
+
+      # Returns a `<turbo-frame>` element.
+      #
+      # The id may be a string, or a record (with an optional prefix), passed to {#dom_id}.
+      #
+      # @example
+      #   turbo_frame_tag "tray" { "..." }
+      #   turbo_frame_tag book                      # id="book_42"
+      #   turbo_frame_tag book, :comments           # id="comments_book_42"
+      #   turbo_frame_tag "details", src: "/books/1/details", loading: :lazy
+      #
+      # @api public
+      def turbo_frame_tag(record_or_id, prefix = nil, src: nil, target: nil, loading: nil, **attributes, &block)
+        id =
+          if prefix.nil? && (record_or_id.is_a?(String) || record_or_id.is_a?(Symbol))
+            record_or_id.to_s
+          else
+            dom_id(record_or_id, prefix)
+          end
+
+        tag.turbo_frame(id:, src:, target:, loading:, **attributes, &block)
+      end
+
+      # Returns a form containing a single button, for actions that shouldn't be links (anything that
+      # changes data). Like Rails' `button_to`.
+      #
+      # The form includes the CSRF token and, for methods other than GET and POST, a `_method` field.
+      # Attributes are given to the button, so `data: {turbo_confirm: "..."}` asks Turbo to confirm
+      # before submitting. Use `form:` for the form's own attributes.
+      #
+      # @example
+      #   button_to "Delete", routes.path(:book, id: book.id), method: :delete,
+      #     data: {turbo_confirm: "Delete #{book.title}?"}
+      #
+      #   button_to routes.path(:archive_book, id: book.id), form: {class: "inline"} do
+      #     "<span>Archive</span>".html_safe
+      #   end
+      #
+      # @param content [String, nil] button content (omit when giving a block)
+      # @param url [String] the form's action
+      # @param method [Symbol, String] HTTP method (default: POST)
+      # @param form [Hash] attributes for the form (default class: `"button_to"`)
+      # @param params [Hash] extra hidden fields to submit
+      # @param attributes [Hash] attributes for the button
+      #
+      # @return [String] the form
+      #
+      # @api public
+      def button_to(content = nil, url = nil, method: :post, form: {}, params: {}, **attributes, &block)
+        if block
+          raise ArgumentError, "give either content or a block, not both" if url
+
+          url = content
+          content = nil
+        end
+        raise ArgumentError, "a URL is required" unless url
+
+        form_attributes = {class: "button_to", **form}
+
+        # `values:` and `params:` are form_for's sources for field values; this form has no fields.
+        form_for(url, method:, values: {}, params: {}, **form_attributes) do |f|
+          hidden_fields = params.map { |name, value|
+            tag.input(type: "hidden", name: name.to_s, value: value.to_s)
+          }
+
+          button =
+            if block
+              f.button(type: "submit", **attributes, &block)
+            else
+              f.button(content, type: "submit", **attributes)
+            end
+
+          (hidden_fields.join + button).html_safe
+        end
+      end
+
+      # @see DomId.dom_id
+      #
+      # @api public
+      def dom_id(record, prefix = nil)
+        DomId.dom_id(record, prefix, inflector: _turbo_inflector)
+      end
+
+      # @see DomId.dom_class
+      #
+      # @api public
+      def dom_class(record, prefix = nil)
+        DomId.dom_class(record, prefix, inflector: _turbo_inflector)
+      end
+
+      private
+
+      def _turbo_inflector
+        respond_to?(:_inflector, true) ? _inflector : Turbo.inflector
+      end
+    end
+  end
+end
+
+Hanami::View::Scope.include(Hanami::Turbo::Helpers)
+Hanami::Extensions::View::StandardHelpers.include(Hanami::Turbo::Helpers)

data/lib/hanami/turbo/part.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # DOM id methods for view parts.
+    #
+    # @example
+    #   <article id="<%= book.dom_id %>">
+    #
+    # @api public
+    module Part
+      # @see DomId.dom_id
+      #
+      # @api public
+      def dom_id(prefix = nil)
+        DomId.dom_id(self, prefix, inflector: _rendering.inflector)
+      end
+
+      # @see DomId.dom_class
+      #
+      # @api public
+      def dom_class(prefix = nil)
+        DomId.dom_class(self, prefix, inflector: _rendering.inflector)
+      end
+    end
+  end
+end
+
+Hanami::View::Part.include(Hanami::Turbo::Part)

data/lib/hanami/turbo/request.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # Turbo-specific methods for `Hanami::Action::Request`.
+    #
+    # @api public
+    module Request
+      TURBO_FRAME_HEADER = "HTTP_TURBO_FRAME"
+      ACCEPT_HEADER = "HTTP_ACCEPT"
+
+      # Returns the id of the Turbo Frame that made this request, if any.
+      #
+      # @return [String, nil]
+      #
+      # @api public
+      def turbo_frame
+        get_header(TURBO_FRAME_HEADER)
+      end
+
+      # Returns true if this request was made by a Turbo Frame.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def turbo_frame?
+        !turbo_frame.nil?
+      end
+
+      # Returns true if the request explicitly accepts Turbo Stream responses.
+      #
+      # Turbo adds the stream media type to the `Accept` header of form submissions. Unlike
+      # `#accept?`, this does not match wildcard `Accept` headers.
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def turbo_stream?
+        get_header(ACCEPT_HEADER).to_s.include?(MEDIA_TYPE)
+      end
+    end
+  end
+end
+
+Hanami::Action::Request.include(Hanami::Turbo::Request)

data/lib/hanami/turbo/response.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # Turbo-aware rendering and redirects for `Hanami::Action::Response`.
+    #
+    # @api public
+    module Response
+      # Renders the view, choosing its format and layout for Turbo requests.
+      #
+      # - For Turbo Stream responses, renders the view's `.turbo_stream` template without a layout.
+      #   If the view has no such template, switches the response to HTML and renders that instead,
+      #   so Turbo never receives HTML labelled as a stream.
+      # - For Turbo Frame requests, renders with {Turbo.config.frame_layout}, when one is set.
+      #
+      # Any `format:` or `layout:` given explicitly takes precedence.
+      #
+      # @api public
+      def render(view, **input)
+        options = _turbo_render_options(view, input)
+        @_turbo_stream_rendered = (input[:format] || options[:format]) == FORMAT
+
+        super(view, **options, **input)
+      end
+
+      # Redirects to the given URL, defaulting to `303 See Other` for non-GET requests.
+      #
+      # @see Turbo.config.see_other_redirects
+      #
+      # @api public
+      def redirect_to(url, status: nil)
+        status ||= SEE_OTHER if _turbo_see_other?
+
+        status ? super(url, status:) : super(url)
+      end
+
+      # Returns true if the response is labelled a Turbo Stream but its body is not one.
+      #
+      # This happens for error responses that weren't rendered from a stream template, such as
+      # `halt 404`. Turbo would treat these as empty streams and silently do nothing.
+      #
+      # @api private
+      def turbo_stream_mismatch?
+        return false unless format == FORMAT && status >= 400
+        return false if @_turbo_stream_rendered
+
+        # Only inspect buffered bodies; leave streamed ones (e.g. from `send_file`) alone.
+        return false unless body.is_a?(Array)
+
+        !body.first.to_s.lstrip.start_with?("<turbo-stream")
+      end
+
+      SEE_OTHER = 303
+      private_constant :SEE_OTHER
+
+      private
+
+      def _turbo_render_options(view, input)
+        options = {}
+
+        if !input.key?(:format) && format == FORMAT
+          return {format: FORMAT, layout: false} if ViewInternals.template?(view, FORMAT)
+
+          # No stream template, so render HTML. Turbo handles HTML responses to form submissions
+          # (including those made inside frames) like any other page.
+          self.format = :html
+        end
+
+        if request&.turbo_frame? && !Turbo.config.frame_layout.nil? && input[:format] != FORMAT
+          options[:layout] = Turbo.config.frame_layout
+        end
+
+        options
+      end
+
+      def _turbo_see_other?
+        Turbo.config.see_other_redirects && request && !request.get? && !request.head?
+      end
+    end
+  end
+end
+
+Hanami::Action::Response.prepend(Hanami::Turbo::Response)

data/lib/hanami/turbo/stream_builder.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # Builds `<turbo-stream>` elements. Returned by the `turbo_stream` view helper.
+    #
+    # Each action takes a target (a DOM id string, or a record passed through {DomId.dom_id}), and
+    # its content as a string, a block, or a partial to render.
+    #
+    # Partials are rendered in the current format when such a partial exists (e.g.
+    # `_book.turbo_stream.erb`), and otherwise as HTML, so the same `_book.html.erb` partial can be
+    # used for full page renders and for streams.
+    #
+    # Add your own stream actions by including a module, as turbo-rails apps do with
+    # `Turbo::Streams::TagBuilder`. Methods can call {#action}, {#action_all}, or
+    # {#turbo_stream_action_tag}, so modules written for turbo-rails work unchanged:
+    #
+    #   module MyApp::TurboStreamActions
+    #     def toast(message, level: "info")
+    #       action(:toast, nil, message:, level:)
+    #     end
+    #   end
+    #
+    #   Hanami::Turbo::StreamBuilder.include(MyApp::TurboStreamActions)
+    #
+    # Then handle the action in JavaScript via `Turbo.StreamActions`.
+    #
+    # @example In a `.turbo_stream.erb` template
+    #   <%= turbo_stream.append "books", partial: "books/book", locals: {book:} %>
+    #   <%= turbo_stream.replace book do %>
+    #     <p><%= book.title %></p>
+    #   <% end %>
+    #   <%= turbo_stream.remove book %>
+    #
+    # @api public
+    class StreamBuilder
+      # Actions that take content.
+      CONTENT_ACTIONS = %i[append prepend replace update before after].freeze
+
+      # @api private
+      def initialize(scope)
+        @scope = scope
+      end
+
+      CONTENT_ACTIONS.each do |name|
+        # Targets one element by DOM id.
+        define_method(name) do |target, content = nil, **options, &block|
+          action(name, target, content, **options, &block)
+        end
+
+        # Targets all elements matching a CSS selector.
+        define_method(:"#{name}_all") do |targets, content = nil, **options, &block|
+          action_all(name, targets, content, **options, &block)
+        end
+      end
+
+      # Removes the target element.
+      #
+      # @api public
+      def remove(target)
+        action(:remove, target)
+      end
+
+      # Removes all elements matching the CSS selector.
+      #
+      # @api public
+      def remove_all(targets)
+        action_all(:remove, targets)
+      end
+
+      # Asks the page to refresh itself (Turbo 8 page refreshes).
+      #
+      # @param request_id [String, nil] identifies the request, so the page that made it can ignore
+      #   the refresh
+      #
+      # @api public
+      def refresh(request_id: nil, **attributes)
+        stream_tag(action: :refresh, "request-id": request_id, **attributes)
+      end
+
+      # Builds a stream element for any action, including custom ones.
+      #
+      # Any other keyword arguments become attributes of the `<turbo-stream>` element (except
+      # `partial:`, `locals:` and `method:`, which are used as described below). A `<template>` is
+      # included when there is content, and always for Turbo's built-in content actions.
+      #
+      # @param name [Symbol, String] the stream action
+      # @param target [Object, nil] DOM id string, a record, or nil for actions without a target
+      # @param content [String, nil] content for the element's `<template>`
+      # @param partial [String, nil] partial to render as the content
+      # @param locals [Hash] locals for the partial
+      # @param method [Symbol, nil] `:morph` to morph rather than replace (for `replace` and `update`)
+      #
+      # @api public
+      def action(name, target, content = nil, **options, &block)
+        target_attributes = target.nil? ? {} : {target: DomId.dom_id(target, inflector: inflector)}
+        stream(name, target_attributes, content, **options, &block)
+      end
+
+      # Builds a stream element for any action, targeting all elements matching a CSS selector.
+      #
+      # @api public
+      def action_all(name, targets, content = nil, **options, &block)
+        stream(name, {targets: targets}, content, **options, &block)
+      end
+
+      # Builds a stream element, with the same signature as turbo-rails' `turbo_stream_action_tag`.
+      #
+      # @example
+      #   turbo_stream_action_tag :console_log, message: "Hello"
+      #   turbo_stream_action_tag :notify, target: book, template: "<b>Saved</b>".html_safe
+      #
+      # @param name [Symbol, String] the stream action
+      # @param target [Object, nil] DOM id string or record
+      # @param targets [String, nil] CSS selector, instead of a target
+      # @param template [String, nil] content for the element's `<template>`
+      # @param attributes [Hash] other attributes for the `<turbo-stream>` element
+      #
+      # @api public
+      def turbo_stream_action_tag(name, target: nil, targets: nil, template: nil, **attributes)
+        if targets
+          action_all(name, targets, template, **attributes)
+        else
+          action(name, target, template, **attributes)
+        end
+      end
+
+      private
+
+      # The scope of the template being rendered. Custom action methods can use it for helpers,
+      # `routes` and locals (the equivalent of `@view_context` in turbo-rails).
+      #
+      # @api public
+      attr_reader :scope
+
+      def stream(name, target_attributes, content = nil, partial: nil, locals: {}, method: nil, **attributes, &block)
+        content = render_partial(partial, locals) if partial
+        content = block.call if block
+
+        if name.to_sym != :remove && (!content.nil? || CONTENT_ACTIONS.include?(name.to_sym))
+          template = scope.tag.template(content.to_s)
+        end
+
+        stream_tag(template, action: name, **target_attributes, method:, **attributes)
+      end
+
+      def render_partial(name, locals)
+        rendering = scope._rendering
+        format = rendering.format
+
+        if format == :html || ViewInternals.partial?(rendering, name, format)
+          return scope.render(name, **locals)
+        end
+
+        html_rendering = ViewInternals.with_format(rendering, :html, scope._context)
+        partial_locals = locals.empty? ? scope._locals : locals
+        html_rendering.partial(name, scope.class.new(locals: partial_locals, rendering: html_rendering))
+      end
+
+      def stream_tag(content = nil, **attributes)
+        scope.tag.turbo_stream(content.to_s.html_safe, **attributes.compact)
+      end
+
+      def inflector
+        scope.respond_to?(:_inflector, true) ? scope.send(:_inflector) : Turbo.inflector
+      end
+    end
+  end
+end

data/lib/hanami/turbo/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    VERSION = "0.1.0"
+  end
+end

data/lib/hanami/turbo/view_internals.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hanami
+  module Turbo
+    # The only place hanami-turbo reaches into hanami-view's private API.
+    #
+    # hanami-view has no public way to ask whether a template exists, or to render with a different
+    # format partway through a render. Keeping these calls together makes them easy to audit, and
+    # to replace if hanami-view gains public equivalents.
+    #
+    # @api private
+    module ViewInternals
+      module_function
+
+      # Returns true if the view has a template for the format.
+      def template?(view, format)
+        !view.rendering(format: format).renderer.send(:lookup, view.config.template, format).nil?
+      end
+
+      # Returns true if the rendering can find the partial in the format.
+      def partial?(rendering, name, format)
+        renderer = rendering.renderer
+        !renderer.send(:lookup, renderer.send(:name_for_partial, name), format).nil?
+      end
+
+      # Returns a copy of the rendering using a different format, sharing its config and context.
+      def with_format(rendering, format, context)
+        Hanami::View::Rendering.new(
+          config_data: rendering.renderer.send(:config_data),
+          format: format,
+          context: context
+        )
+      end
+    end
+  end
+end

data/lib/hanami/turbo.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "dry/inflector"
+require "hanami"
+require "hanami/action"
+require "hanami/view"
+
+require_relative "turbo/version"
+
+module Hanami
+  # Hotwire Turbo support for Hanami apps.
+  #
+  # Requiring this file extends `Hanami::Action::Request`, `Hanami::Action::Response`,
+  # `Hanami::View::Part` and the standard Hanami view helpers. Call {.install} from your app class to
+  # register the Turbo Stream format.
+  #
+  # @example
+  #   # config/app.rb
+  #   require "hanami"
+  #   require "hanami/turbo"
+  #
+  #   module Bookshelf
+  #     class App < Hanami::App
+  #       Hanami::Turbo.install(config)
+  #     end
+  #   end
+  #
+  # @api public
+  module Turbo
+    extend Dry::Configurable
+
+    # The format name for Turbo Stream responses.
+    FORMAT = :turbo_stream
+
+    # The media type Turbo sends in `Accept` headers and expects on stream responses.
+    MEDIA_TYPE = "text/vnd.turbo-stream.html"
+
+    # @!attribute [rw] see_other_redirects
+    #   Whether `res.redirect_to` defaults to `303 See Other` for non-GET requests. Turbo requires a
+    #   303 after PATCH, PUT and DELETE form submissions, since browsers repeat the original method
+    #   when following a 302. An explicitly given `status:` is always respected.
+    #
+    #   Defaults to true.
+    setting :see_other_redirects, default: true
+
+    # @!attribute [rw] frame_layout
+    #   The layout to use when rendering HTML for a request made by a Turbo Frame (one with a
+    #   `Turbo-Frame` header). Turbo only uses the matching `<turbo-frame>` from these responses, so
+    #   rendering the full layout is wasted work.
+    #
+    #   `nil` (the default) leaves the view's layout unchanged. `false` renders no layout. A string
+    #   names a layout within the view's `layouts_dir`.
+    setting :frame_layout, default: nil
+
+    # Registers the `:turbo_stream` format with the given app config.
+    #
+    # `:turbo_stream` is added to the app's accepted formats, so that Turbo's `Accept` header
+    # negotiates a stream response. Apps that accept any format (the default) also get the `:all`
+    # format, which keeps them accepting any format, so installing Turbo never causes new 406
+    # responses.
+    #
+    # @param config [Hanami::Config] the app's config
+    #
+    # @return [void]
+    #
+    # @api public
+    def self.install(config)
+      formats = config.actions.formats
+      formats.register(FORMAT, MEDIA_TYPE)
+
+      # Assign `accepted` directly rather than using `accept`, which would make the first format the
+      # default response format.
+      formats.accepted = (formats.accepted.empty? ? [:all] : formats.accepted) | [FORMAT]
+    end
+
+    # @api private
+    def self.inflector
+      @inflector ||= Dry::Inflector.new
+    end
+  end
+end
+
+require_relative "turbo/view_internals"
+require_relative "turbo/dom_id"
+require_relative "turbo/request"
+require_relative "turbo/response"
+require_relative "turbo/action"
+require_relative "turbo/stream_builder"
+require_relative "turbo/helpers"
+require_relative "turbo/part"

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: hanami-turbo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrea Fomera
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hanami
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: hanami-action
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: hanami-view
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: Turbo Stream rendering, Turbo Frame helpers, and Turbo-friendly redirects
+  for Hanami
+email:
+- afomera@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/hanami/turbo.rb
+- lib/hanami/turbo/action.rb
+- lib/hanami/turbo/dom_id.rb
+- lib/hanami/turbo/helpers.rb
+- lib/hanami/turbo/part.rb
+- lib/hanami/turbo/request.rb
+- lib/hanami/turbo/response.rb
+- lib/hanami/turbo/stream_builder.rb
+- lib/hanami/turbo/version.rb
+- lib/hanami/turbo/view_internals.rb
+homepage: https://hanamirb.org
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Hotwire Turbo support for Hanami apps
+test_files: []