transition_buttons 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56cd7f848d886a443f88cb3d05e1a964c4bcc7e97e8acdd41736887f3f95bc3a
+  data.tar.gz: 1cf834be4961dab9dcaefa081dee0667dc10e7d2c9319aa55873df638de54a7a
+SHA512:
+  metadata.gz: e8ce855b727b18eec80d41baed23a2a1617cb1417e0bcf0ae4cbf4a1819f6d1b182643819395aac82019286918c0754b2dbceb60ed5102e0333945ef16f561fe
+  data.tar.gz: ab0afecb056a98a2c03fd197a7527368ca9335e8375864ad668fb0db85623dbccd967adb35fb24131a8bff9726e035c5c7c0a4dc7ead6078499397177e196eab

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.0.1] - 2026-07-08
+
+- Reserve the gem name. Placeholder release; the first usable version will be
+  0.1.0. Source extracted from the `ruby-state-machine-tests` research repo.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 First Draft
+
+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,125 @@
+# transition_buttons
+
+Render one button per state-machine event **the current user may perform on a
+record right now** — the intersection of *legal from the current state* (the
+state machine's guards) and *authorized for this user* (your policy) — each
+button POSTing to a member `transition` route that **re-checks both
+server-side** before firing.
+
+The buttons are a convenience for the view. The endpoint is the security
+boundary: it never trusts the submitted event, re-deriving the legal-and-authorized
+set independently.
+
+Ships with adapters for [`state_machines`](https://github.com/state-machines/state_machines)
+and [ActionPolicy](https://github.com/palkan/action_policy); both are swappable.
+
+## Install
+
+```ruby
+# Gemfile
+gem "transition_buttons"
+gem "state_machines-activerecord"
+gem "action_policy"
+```
+
+## Usage
+
+### 1. A model with one or more state machines
+
+```ruby
+class Post < ApplicationRecord
+  state_machine :state, initial: :draft do
+    event(:submit)  { transition draft: :pending_review }
+    event(:publish) { transition pending_review: :published }
+    event(:reject)  { transition pending_review: :draft }
+  end
+
+  # A second machine on the same record is fully supported.
+  state_machine :moderation_state, initial: :ok do
+    event(:flag)   { transition ok: :flagged }
+    event(:unflag) { transition flagged: :ok }
+  end
+end
+```
+
+### 2. A policy whose rule names match the event names
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  def submit?  = owner?
+  def publish? = editor?
+  def reject?  = editor?
+  def flag?    = editor?
+  def unflag?  = editor?
+end
+```
+
+An event with no matching rule is **denied by default** — adding an event can
+never silently expose it.
+
+### 3. Route + controller
+
+```ruby
+# config/routes.rb
+resources :posts, only: [:index, :show] do
+  transitionable        # POST /posts/:id/transition  (transition_post)
+end
+```
+
+```ruby
+class PostsController < ApplicationController
+  include TransitionButtons::Transitionable
+  # `transition` is provided. The record defaults to Post.find(params[:id]);
+  # override #transition_buttons_record for custom scoping.
+end
+```
+
+### 4. The view
+
+```erb
+<%= transition_buttons_for(@post) %>                       <%# machine: :state %>
+<%= transition_buttons_for(@post, machine: :moderation_state) %>
+<%= transition_buttons_for(@post, user: some_user, class: "btn") %>
+
+<%# Or render your own UI from the raw permitted list: %>
+<% available_events(@post).each do |event| %> ... <% end %>
+```
+
+`user:` defaults to `current_user` when the view exposes it. Extra keyword
+options are forwarded to each `button_to`.
+
+## Recording who triggered a transition
+
+If your model exposes `current_actor=`, the controller sets it to `current_user`
+before firing, so a transition log (e.g.
+[state_machines-audit_trail](https://github.com/state-machines/state_machines-audit_trail))
+can record the actor:
+
+```ruby
+class Post < ApplicationRecord
+  attr_accessor :current_actor
+  state_machine :state, initial: :draft do
+    audit_trail context: :audited_by
+    # ...
+  end
+  def audited_by = current_actor&.email
+end
+```
+
+## Swapping backends
+
+```ruby
+TransitionButtons.configure do |c|
+  c.state_machine_adapter = MyAdapter.new   # #available_events/#current_state/#fire/#event_label
+  c.authorizer            = MyAuthorizer.new # #permitted?(user:, record:, event:, machine:)
+  c.default_machine       = :state
+end
+```
+
+An AASM adapter (`record.aasm(machine).events(permitted: true)` /
+`record.public_send("#{event}!")`) and a Pundit authorizer are natural
+additions and the seams are designed for them.
+
+## Out of scope (v1)
+
+Events that need arguments — those want a real form, not a one-click button.

data/lib/transition_buttons/authorizers/action_policy.rb

@@ -0,0 +1,19 @@
+module TransitionButtons
+  module Authorizers
+    # Authorizer backed by ActionPolicy.
+    #
+    # Convention: a transition event maps to the policy rule of the same name
+    # with a `?` suffix (event `:publish` -> rule `publish?`). When the policy
+    # defines no such rule we deny by default, so adding an event without a
+    # matching rule can never silently expose it.
+    class ActionPolicy
+      def permitted?(user:, record:, event:, machine:)
+        policy = ::ActionPolicy.lookup(record).new(record, user: user)
+        rule = :"#{event}?"
+        return false unless policy.respond_to?(rule)
+
+        policy.apply(rule)
+      end
+    end
+  end
+end

data/lib/transition_buttons/configuration.rb

@@ -0,0 +1,21 @@
+require "transition_buttons/state_machine_adapters/state_machines"
+require "transition_buttons/authorizers/action_policy"
+
+module TransitionButtons
+  class Configuration
+    # Object responding to #available_events, #current_state, #fire, #event_label.
+    attr_accessor :state_machine_adapter
+
+    # Object responding to #permitted?(user:, record:, event:, machine:).
+    attr_accessor :authorizer
+
+    # Machine to target when a helper/endpoint does not specify one.
+    attr_accessor :default_machine
+
+    def initialize
+      @state_machine_adapter = StateMachineAdapters::StateMachines.new
+      @authorizer = Authorizers::ActionPolicy.new
+      @default_machine = :state
+    end
+  end
+end

data/lib/transition_buttons/controller.rb

@@ -0,0 +1,75 @@
+module TransitionButtons
+  # Mixed into a host controller to add a `transition` action:
+  #
+  #   class PostsController < ApplicationController
+  #     include TransitionButtons::Transitionable
+  #   end
+  #
+  # Paired with the `transitionable` route helper:
+  #
+  #   resources :posts do
+  #     transitionable
+  #   end
+  #
+  # This action is the real security boundary. The view's buttons are only a
+  # hint; here we independently re-resolve which events are legal-and-authorized
+  # for the current user before firing, and refuse anything else.
+  module Transitionable
+    extend ActiveSupport::Concern
+
+    def transition
+      record = transition_buttons_record
+      machine = (params[:machine].presence || TransitionButtons.config.default_machine).to_sym
+      event = params.require(:event).to_sym
+
+      # Record who triggered the transition for the audit trail, if supported.
+      record.current_actor = current_user if record.respond_to?(:current_actor=)
+
+      resolver = EventResolver.new(record: record, user: current_user, machine: machine)
+
+      if !resolver.domain_event?(event)
+        transition_buttons_render_unavailable(record, event, machine)
+      elsif !resolver.permitted?(event)
+        transition_buttons_render_forbidden(record, event, machine)
+      elsif resolver.fire(event)
+        transition_buttons_render_success(record, event, machine)
+      else
+        # Legal and authorized, but the machine still refused (e.g. a guard that
+        # flipped between resolution and firing). Surface it rather than hide it.
+        transition_buttons_render_unavailable(record, event, machine)
+      end
+    end
+
+    private
+
+    # --- Overridable hooks --------------------------------------------------
+
+    # Defaults to inferring the model from the controller name and finding by
+    # :id (PostsController -> Post.find(params[:id])). Override for anything
+    # non-conventional (scoping to current_user, nested resources, etc.).
+    def transition_buttons_record
+      controller_name.classify.constantize.find(params[:id])
+    end
+
+    def transition_buttons_render_success(record, event, _machine)
+      respond_to do |format|
+        format.html { redirect_back fallback_location: url_for(record), notice: "#{event.to_s.humanize} succeeded." }
+        format.json { render json: record }
+      end
+    end
+
+    def transition_buttons_render_forbidden(record, event, _machine)
+      respond_to do |format|
+        format.html { redirect_back fallback_location: url_for(record), alert: "You are not allowed to #{event}." }
+        format.json { head :forbidden }
+      end
+    end
+
+    def transition_buttons_render_unavailable(record, event, _machine)
+      respond_to do |format|
+        format.html { redirect_back fallback_location: url_for(record), alert: "#{event.to_s.humanize} is not available right now." }
+        format.json { head :unprocessable_entity }
+      end
+    end
+  end
+end

data/lib/transition_buttons/event_resolver.rb

@@ -0,0 +1,54 @@
+module TransitionButtons
+  # Single source of truth shared by the view helper and the controller, so the
+  # buttons a user sees and the transitions the endpoint accepts can never drift
+  # apart. The view renders `permitted_events`; the controller re-derives the
+  # same set server-side before firing (the buttons are a hint, never the
+  # security boundary).
+  class EventResolver
+    attr_reader :machine
+
+    def initialize(record:, user:, machine: nil, adapter: nil, authorizer: nil)
+      @record = record
+      @user = user
+      @machine = (machine || TransitionButtons.config.default_machine).to_sym
+      @adapter = adapter || TransitionButtons.config.state_machine_adapter
+      @authorizer = authorizer || TransitionButtons.config.authorizer
+    end
+
+    # Events the state machine allows from the current state (guards applied).
+    def domain_events
+      @domain_events ||= Array(@adapter.available_events(@record, machine: @machine)).map(&:to_sym)
+    end
+
+    def domain_event?(event)
+      domain_events.include?(event.to_sym)
+    end
+
+    # The intersection the UI cares about: legal AND authorized for this user.
+    def permitted_events
+      domain_events.select { |event| authorized?(event) }
+    end
+
+    def permitted?(event)
+      domain_event?(event) && authorized?(event)
+    end
+
+    def current_state
+      @adapter.current_state(@record, machine: @machine)
+    end
+
+    # Fires the event. Returns the adapter's truthy/falsey result. Does NOT
+    # enforce authorization itself — callers (the controller) must check
+    # `permitted?` first; this keeps the security decision explicit at the
+    # boundary rather than buried in a side effect.
+    def fire(event)
+      @adapter.fire(@record, event.to_sym, machine: @machine)
+    end
+
+    private
+
+    def authorized?(event)
+      @authorizer.permitted?(user: @user, record: @record, event: event.to_sym, machine: @machine)
+    end
+  end
+end

data/lib/transition_buttons/railtie.rb

@@ -0,0 +1,15 @@
+require "rails/railtie"
+
+module TransitionButtons
+  class Railtie < Rails::Railtie
+    initializer "transition_buttons.view_helper" do
+      ActiveSupport.on_load(:action_view) do
+        include TransitionButtons::ViewHelper
+      end
+    end
+
+    initializer "transition_buttons.routing" do
+      ActionDispatch::Routing::Mapper.include(TransitionButtons::Routing)
+    end
+  end
+end

data/lib/transition_buttons/routing.rb

@@ -0,0 +1,16 @@
+module TransitionButtons
+  # Adds a `transitionable` helper to the routes DSL:
+  #
+  #   resources :posts do
+  #     transitionable          # => POST /posts/:id/transition  (transition_post)
+  #   end
+  #
+  # Equivalent to writing `member { post :transition }`, but named so intent is
+  # obvious and so the route name stays consistent with what the view helper's
+  # `polymorphic_path([:transition, record])` expects.
+  module Routing
+    def transitionable
+      member { post :transition }
+    end
+  end
+end

data/lib/transition_buttons/state_machine_adapters/state_machines.rb

@@ -0,0 +1,38 @@
+module TransitionButtons
+  module StateMachineAdapters
+    # Adapter for the `state_machines` gem.
+    #
+    # state_machines prefixes its generated helpers with the machine's attribute
+    # name, so a machine declared as `state_machine :review_state` exposes
+    # `review_state_events`, `fire_review_state_event`, `review_state_name`, and
+    # `Klass.human_review_state_event_name`. We build those names from `machine`.
+    class StateMachines
+      # Events permitted by the machine's guards from the current state.
+      # `state_machines` evaluates if/unless guards here by default, so this is
+      # the domain-legal set, before authorization.
+      def available_events(record, machine:)
+        record.public_send("#{machine}_events")
+      end
+
+      def current_state(record, machine:)
+        record.public_send("#{machine}_name")
+      end
+
+      # Returns true/false (state_machines does not raise when an event is
+      # disallowed), letting the caller translate a false into an HTTP 422.
+      def fire(record, event, machine:)
+        record.public_send("fire_#{machine}_event", event)
+      end
+
+      def event_label(record, event, machine:)
+        humanizer = "human_#{machine}_event_name"
+        klass = record.class
+        if klass.respond_to?(humanizer)
+          klass.public_send(humanizer, event)
+        else
+          event.to_s.humanize
+        end
+      end
+    end
+  end
+end

data/lib/transition_buttons/version.rb

@@ -0,0 +1,3 @@
+module TransitionButtons
+  VERSION = "0.0.1"
+end

data/lib/transition_buttons/view_helper.rb

@@ -0,0 +1,59 @@
+module TransitionButtons
+  module ViewHelper
+    # Renders one button per event the current user may perform on `record`
+    # right now, each POSTing to the record's member `transition` route.
+    #
+    #   <%= transition_buttons_for(@post) %>
+    #   <%= transition_buttons_for(@post, machine: :review_state) %>
+    #   <%= transition_buttons_for(@post, user: some_user, class: "btn") %>
+    #
+    # `user:` defaults to `current_user` when the view exposes it. Remaining
+    # keyword options are forwarded to each `button_to` as HTML options.
+    def transition_buttons_for(record, machine: nil, user: nil, **html_options)
+      resolver = transition_buttons_resolver(record, machine: machine, user: user)
+      adapter = TransitionButtons.config.state_machine_adapter
+      path = transition_buttons_path(record)
+
+      buttons = resolver.permitted_events.map do |event|
+        button_to(
+          adapter.event_label(record, event, machine: resolver.machine),
+          path,
+          method: :post,
+          params: {event: event, machine: resolver.machine},
+          **html_options
+        )
+      end
+
+      safe_join(buttons)
+    end
+
+    # The raw permitted-event list, for callers who want to render their own UI.
+    #
+    #   <% available_events(@post).each do |event| %> ... <% end %>
+    def available_events(record, machine: nil, user: nil)
+      transition_buttons_resolver(record, machine: machine, user: user).permitted_events
+    end
+
+    private
+
+    def transition_buttons_resolver(record, machine:, user:)
+      EventResolver.new(
+        record: record,
+        user: user || transition_buttons_current_user,
+        machine: machine
+      )
+    end
+
+    def transition_buttons_current_user
+      return current_user if respond_to?(:current_user, true)
+
+      nil
+    end
+
+    # Resolves the record's member `transition` route, e.g. /posts/42/transition.
+    # Relies on the `transitionable` routing helper (a member POST :transition).
+    def transition_buttons_path(record)
+      polymorphic_path([:transition, record])
+    end
+  end
+end

data/lib/transition_buttons.rb

@@ -0,0 +1,32 @@
+require "transition_buttons/version"
+require "transition_buttons/configuration"
+require "transition_buttons/event_resolver"
+require "transition_buttons/view_helper"
+require "transition_buttons/controller"
+require "transition_buttons/routing"
+require "transition_buttons/railtie" if defined?(Rails::Railtie)
+
+# Authorization-aware state machine transition buttons for Rails.
+#
+# Renders one button per event the current user may perform on a record (the
+# intersection of "legal from the current state" and "authorized for this
+# user"), each POSTing to a member `transition` route that re-checks both
+# server-side before firing.
+module TransitionButtons
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Test/reset hook.
+    def reset_config!
+      @config = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: transition_buttons
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- First Draft
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: state_machines
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: action_policy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: Render one button per event the current user may perform on a record,
+  each POSTing to a member transition route that re-authorizes server-side. Pluggable
+  state machine and authorization backends; ships with state_machines and ActionPolicy.
+email:
+- raghu@firstdraft.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/transition_buttons.rb
+- lib/transition_buttons/authorizers/action_policy.rb
+- lib/transition_buttons/configuration.rb
+- lib/transition_buttons/controller.rb
+- lib/transition_buttons/event_resolver.rb
+- lib/transition_buttons/railtie.rb
+- lib/transition_buttons/routing.rb
+- lib/transition_buttons/state_machine_adapters/state_machines.rb
+- lib/transition_buttons/version.rb
+- lib/transition_buttons/view_helper.rb
+homepage: https://github.com/firstdraft/transition_buttons
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/firstdraft/transition_buttons
+  changelog_uri: https://github.com/firstdraft/transition_buttons/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Authorization-aware state machine transition buttons for Rails
+test_files: []