phlex-stimulus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f20ab06752e9826fc2e3861ee9878cd26448f2094ccbd5779ffacb64b6fe364
+  data.tar.gz: 9b0bb287d885da0b196d9aab1b21d9d9b1048f2d4d19e2c15d969dfba7f0a1e2
+SHA512:
+  metadata.gz: 4afabcd2606a43cdf8f029e27afa3dc86c119fd68f6e5cda842ba729ac9df2659110b048f1cbb56df7f502a343cf61f6b6da8e163373780cc6d3af151f82de99
+  data.tar.gz: 9c25eddafac1a456cb42303eac937eb5f95b898a446daa85ffe981528c210bbe0b92dbce5a79812b26d3ace3e4567489bec9940dbc22f594680ab91138d6fb41

data/.ruby-version

@@ -0,0 +1 @@
+4.0.6

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Add changes in new features here. Do not change the gem's version in pull/merge requests.
+
+## [0.1.0] - 22.07.2026
+
+[Diff](https://github.com/espago/phlex-stimulus/compare/v0.0.0...v0.1.0)
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Espago
+
+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,341 @@
+# Phlex::Stimulus
+
+`phlex-stimulus` pairs every [Stimulus](https://stimulus.hotwired.dev/) controller in your app with a
+[Phlex](https://www.phlex.fun/) component, and keeps both sides strictly typed.
+
+For each Stimulus controller (the TypeScript side) there is a matching Phlex component
+(the Ruby side). The component owns the markup that mounts the controller — the `data-controller`
+attribute, its targets, actions, and values — and exposes strictly [Sorbet](https://sorbet.org/)-typed
+helpers so the wiring between Ruby and JS can't silently drift.
+
+Controllers can also be **chained**: a set of controllers can be rendered so that each one's `connect`
+logic runs to completion before the next one connects.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add phlex-stimulus
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install phlex-stimulus
+```
+
+Then run the installer.
+
+```sh
+bundle exec rails generate phlex:stimulus:install
+```
+
+## Usage
+
+### Generating a controller + component
+
+```sh
+bundle exec rails generate phlex:stimulus:controller Summary
+```
+
+This creates a matched pair:
+
+- `app/components/summary_controller.rb` — a `Components::SummaryController`
+- `app/javascript/controllers/summary_controller.ts` — a `SummaryController`
+
+### Ruby controller components
+
+A controller component declares the Stimulus controller name, its actions, and its targets. Those
+declarations generate strictly-typed helpers so your markup references controllers, actions, and targets
+by method call instead of by hand-written string:
+
+```ruby
+# typed: strict
+
+module Components
+  class SummaryController < Controller
+    self.controller_name = 'summary'
+
+    actions :redirect          # => defines SummaryController.redirect_action  #=> "summary#redirect"
+    targets :body              # => defines SummaryController.body_target       #=> "body"
+
+    #: (title: String) -> void
+    def initialize(title:)
+      @title = title
+    end
+
+    # @override
+    #: ?{ -> void } -> void
+    def view_template(&block)
+      div(data: { controller: self.class.controller_name, title: @title }) do
+        block&.call
+      end
+    end
+
+  end
+end
+```
+
+You can render a controller like any other Phlex component:
+
+```ruby
+render SummaryController.new(title: 'Report') do
+  # define an action
+  button(data: { action: event('click', SummaryController.redirect_action) }) { 'Go' }
+
+  # define a target
+  div(data: { SummaryController.target_key => SummaryController.body_target }) do
+    plan "Foo"
+  end
+end
+```
+
+### Controller component helpers
+
+#### `_action`
+
+Each action you define will result in a corresponding `_action` method being available in Ruby.
+Sorbet is fully aware of these methods thanks to a tapioca compiler.
+
+These methods just return the name of the controller together with the name of the action: `"controller#action"`.
+They mostly exist so that sorbet can check if the actions your using when building HTML elements
+actually exist.
+
+You can read more about actions [here](https://stimulus.hotwired.dev/reference/actions).
+
+```rb
+class SummaryController < Controller
+  self.controller_name = 'summary'
+
+  actions :foo
+end
+
+SummaryController.foo_action #=> "summary#foo"
+```
+
+This can be used to attach an action to an HTML element with full type safety.
+
+```rb
+div(data: { action: event('click', SummaryController.foo_action) })
+```
+
+This is the same as:
+
+```rb
+div(data: { action: 'click->summary#foo' })
+```
+
+#### `_target`
+
+Each target you define will result in a corresponding `_target` method being available in Ruby.
+Sorbet is fully aware of these methods thanks to a tapioca compiler.
+
+These methods just return the name of the target so they may seem pointless.
+They exist only so that sorbet can check if the actions your using when building HTML elements
+actually exist.
+
+You can read more about targets [here](https://stimulus.hotwired.dev/reference/targets).
+
+```rb
+class SummaryController < Controller
+  self.controller_name = 'summary'
+
+  targets :foo
+end
+
+SummaryController.foo_target #=> "foo"
+```
+
+You would use it like so to attach a target with full type safety:
+
+```rb
+div(data: { SummaryController.target_key => SummaryController.foo_target })
+```
+
+This is the same as:
+
+```rb
+div(data: { 'summary-target' => 'foo' })
+```
+
+#### `target_key`
+
+This method returns the key that can be used to attach targets to the controller.
+
+```rb
+class SummaryController < Controller
+  self.controller_name = 'summary'
+
+  targets :foo
+end
+
+SummaryController.target_key #=> "summary-target"
+```
+
+You would use it like so to attach a target with full type safety:
+
+```rb
+div(data: { SummaryController.target_key => SummaryController.foo_target })
+```
+
+This is the same as:
+
+```rb
+div(data: { 'summary-target' => 'foo' })
+```
+
+#### `dispatched`
+
+This method helps you get the names of custom events dispatched by a stimulus controller.
+You can read more about event dispatching [here](https://stimulus.hotwired.dev/reference/controllers#cross-controller-coordination-with-events).
+
+```rb
+class SummaryController < Controller
+  self.controller_name = 'summary'
+end
+
+SummaryController.dispatched('redirected') #=> "summary:redirected"
+```
+
+You would use it like so to define an action on an dispatched event:
+
+```rb
+div(data: { action: event(SummaryController.dispatched('redirected'), OtherController.do_action) })
+```
+
+This is the same as:
+
+```rb
+div(data: { 'summary:redirected' => 'other#do' })
+```
+
+### Component Helpers
+
+There are some useful helper methods you can use in every phlex component.
+
+#### `attrbool`
+
+`attrbool` converts a Ruby boolean to `'true'` or `nil` so the boolean value
+can be used in attributes of HTML elements
+
+```rb
+attrbool(true) #=> "true"
+attrbool(false) #=> nil
+```
+
+You would use it when passing a boolean value from Ruby to an HTML attribute.
+
+```rb
+button(data: { enabled: attrbool(@enabled) })
+```
+
+#### `event`
+
+`event` let's you easily and safely create stimulus action strings.
+
+```rb
+event('click', 'summary#redirect') #=> "click->summary#redirect"
+event('click', SummaryController.redirect_action) #=> "click->summary#redirect"
+```
+
+You would use it when attaching a controller action to some HTML element.
+
+```rb
+button(data: { action: event('click', SummaryController.redirect_action) })
+```
+
+#### `class_list`
+
+`class_list` let's you easily add classes to html elements conditionally.
+
+```rb
+class_list("foo", "bar", "baz") #=> "foo bar baz"
+
+error = false
+class_list("foo", "red" if error, "bar") #=> "foo bar"
+
+error = true
+class_list("foo", "red" if error, "bar") #=> "foo red bar"
+```
+
+You would use it when declaring an HTML element.
+
+```rb
+div(class: class_list("foo", "red" if error, "bar")) do
+  plain "Hello!"
+end
+```
+
+`class_list` is aliased as `strlist` as it may be useful for other things than CSS classes.
+
+### Stimulus controllers
+
+There is a `TypedController` factory that let's you define strict types for controller targets.
+
+```ts
+import { application } from "./application"
+import { TypedController } from "./typed_controller"
+
+class SummaryController extends TypedController<HTMLElement, { body: HTMLDivElement }>() {
+  static targets = ["body"]
+
+  redirect() {
+    this.bodyTarget.innerText = "…"   // fully typed
+  }
+}
+
+application.register("summary", SummaryController)
+```
+
+### Chaining controllers
+
+Sometimes controllers must connect in a specific order — each one finishing its setup before the next
+starts. `phlex-stimulus` supports this on both sides.
+
+On the TypeScript side, a chainable controller extends `ChainableController` (or
+`TypedChainableController` for typed targets) and puts its `connect` logic in `init()`. When `init()`
+resolves, the controller dispatches a `ready` event that the chain waits on:
+
+```ts
+class LogController extends ChainableController<HTMLElement> {
+  async init() {
+    console.log("connected")
+  }
+}
+```
+
+On the Ruby side, render your controller components through `Components::ControllerChain`. It renders
+each controller inside a deferred `<template>` and drives them via the `chain` controller so they attach
+one after another:
+
+```ruby
+render Components::ControllerChain.new(
+  Components::SleepController.new(timeout: 500),
+  Components::LogController.new(message: "ready!"),
+)
+```
+
+This would result in a *"ready!"* console message getting displayed after 500 milliseconds.
+
+Two of the bundled controllers are especially useful as chain building blocks:
+
+- `Components::SleepController.new(timeout:)` — pauses the chain for the given number of milliseconds.
+- `Components::LogController.new(message:, on_event:)` — `console.log`s a message when it connects
+  (handy for debugging a chain).
+
+You can look those up as examples to see how you can implement your own chainable controllers.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/espago/phlex-stimulus. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/espago/phlex-stimulus/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/generators/phlex/stimulus/controller/USAGE

@@ -0,0 +1,5 @@
+Description:
+  Creates a new stimulus controller with a phlex component.
+
+Example:
+  rails generate phlex:stimulus:controller Name

data/lib/generators/phlex/stimulus/controller/controller_generator.rb

@@ -0,0 +1,49 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../generator_mixin'
+
+module Phlex::Stimulus::Generators
+  class ControllerGenerator < ::Rails::Generators::NamedBase
+    include GeneratorMixin
+
+    source_root File.expand_path('templates', __dir__)
+
+    #: -> void
+    def create_files
+      template 'controller.ts.erb',
+               File.join(destination_root, 'app', 'javascript', 'controllers', class_path, "#{file_name}_controller.ts")
+
+      template 'component.rb.erb',
+               File.join(destination_root, 'app', 'components', class_path, "#{file_name}_controller.rb")
+
+      append_to_file File.join(destination_root, 'app', 'javascript', 'controllers', 'index.ts'),
+                     "import \"./#{class_path}/#{file_name}_controller\"\n"
+    end
+
+    private
+
+    #: -> String
+    def path_to_root_controller_dir
+      @path_to_root_controller_dir ||= begin
+        result = String.new
+        result << './'
+        class_path.length.times do
+          result << '../'
+        end
+
+        result
+      end
+    end
+
+    #: -> String
+    def stimulus_controller_name
+      @stimulus_controller_name ||= (class_path + [file_name]).join('--')
+    end
+
+    #: -> String
+    def class_name_without_namespace
+      file_name.camelize
+    end
+  end
+end

data/lib/generators/phlex/stimulus/controller/templates/component.rb.erb

@@ -0,0 +1,30 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Components
+  # Does something ;)
+  class <%= namespace if namespaced? %><%= class_name %>Controller < Controller
+    self.controller_name = '<%= stimulus_controller_name %>'
+
+    actions :act
+    targets :foo
+
+    #: (name: String) -> void
+    def initialize(name)
+      @name = name
+    end
+
+    # @override
+    #: ?{ -> void } -> void
+    def view_template(&block)
+      div(
+        data: {
+          controller: self.class.controller_name,
+          name: @name,
+        },
+      ) do
+        block&.call
+      end
+    end
+  end
+end

data/lib/generators/phlex/stimulus/controller/templates/controller.ts.erb

@@ -0,0 +1,23 @@
+import { application } from "<%= path_to_root_controller_dir %>application"
+import { TypedController } from "<%= path_to_root_controller_dir %>typed_controller"
+
+/**
+ * Does something ;)
+ **/
+class <%= class_name_without_namespace %>Controller extends TypedController<HTMLElement, { foo: HTMLDivElement }>() {
+  static targets = [ "foo" ]
+
+  name!: string
+
+  connect() {
+    let dataset = this.element.dataset
+    this.name = dataset.name!
+    console.log(`Hello from <%= class_name_without_namespace %>Controller with name of ${this.name}!`)
+  }
+
+  act() {
+    console.log(`I am <%= class_name_without_namespace %>Controller with name of ${this.name}, and I act now!`)
+  }
+}
+
+application.register("<%= stimulus_controller_name %>", <%= class_name_without_namespace %>Controller)

data/lib/generators/phlex/stimulus/generator_mixin.rb

@@ -0,0 +1,21 @@
+# typed: false
+# frozen_string_literal: true
+
+module Phlex::Stimulus::Generators
+  module GeneratorMixin
+    private
+
+    #: (String) -> void
+    def replace_with_template(path)
+      app_path = File.join(destination_root, path)
+      remove_file app_path
+      template "#{path}.erb", app_path
+    end
+
+    #: (String) -> void
+    def copy_template(path)
+      template "#{path}.erb",
+               File.join(destination_root, path)
+    end
+  end
+end

data/lib/generators/phlex/stimulus/install/USAGE

@@ -0,0 +1,5 @@
+Description:
+  Installs phlex-stimulus base components
+
+Example:
+  rails generate phlex:stimulus:install

data/lib/generators/phlex/stimulus/install/install_generator.rb

@@ -0,0 +1,111 @@
+# typed: false
+# frozen_string_literal: true
+
+require_relative '../generator_mixin'
+
+module Phlex::Stimulus::Generators
+  class InstallGenerator < ::Rails::Generators::Base
+    include GeneratorMixin
+
+    source_root File.expand_path('templates', __dir__)
+
+    def remove_importmap_if_present
+      return unless importmap_installed?
+
+      say 'Importmap detected — removing it', :yellow
+      remove_importmap
+    end
+
+    def install_jsbundling_unless_present
+      return if jsbundling_installed?
+
+      say 'Installing jsbundling-rails (esbuild)', :yellow
+      install_jsbundling_with_esbuild
+    end
+
+    def install_stimulus
+      say 'Installing stimulus', :yellow
+      gem 'stimulus-rails'
+      Bundler.with_original_env { run 'bundle install' }
+      rails_command 'stimulus:install'
+    end
+
+    def create_files
+      copy_template 'app/components.rb'
+      copy_template 'app/components/base.rb'
+      copy_template 'app/components/controller.rb'
+      copy_template 'app/components/chain_controller.rb'
+      copy_template 'app/components/controller_template.rb'
+      copy_template 'app/components/controller_chain.rb'
+      copy_template 'app/components/classlist_controller.rb'
+      copy_template 'app/components/log_controller.rb'
+      copy_template 'app/components/sleep_controller.rb'
+
+      remove_file File.join(destination_root, 'app/javascript/application.js')
+      copy_template 'app/javascript/application.ts'
+
+      remove_file File.join(destination_root, 'app/javascript/controllers/application.js')
+      copy_template 'app/javascript/controllers/application.ts'
+
+      remove_file File.join(destination_root, 'app/javascript/controllers/index.js')
+      copy_template 'app/javascript/controllers/index.ts'
+
+      copy_template 'app/javascript/controllers/typed_controller.ts'
+      copy_template 'app/javascript/controllers/chain_controller.ts'
+      copy_template 'app/javascript/controllers/chainable_controller.ts'
+      copy_template 'app/javascript/controllers/log_controller.ts'
+      copy_template 'app/javascript/controllers/sleep_controller.ts'
+      copy_template 'app/javascript/controllers/classlist_controller.ts'
+
+      copy_template 'app/javascript/utils/misc.ts'
+      copy_template 'app/javascript/utils/template.ts'
+    end
+
+    private
+
+    #: (String) -> void
+    def replace_with_template(path)
+      app_path = File.join(destination_root, path)
+      remove_file app_path
+      template "#{path}.erb", app_path
+    end
+
+    #: (String) -> void
+    def copy_template(path)
+      template "#{path}.erb",
+               File.join(destination_root, path)
+    end
+
+    def importmap_installed?
+      File.exist?(File.join(destination_root, 'config/importmap.rb')) ||
+        gemfile_includes?('importmap-rails')
+    end
+
+    def jsbundling_installed?
+      gemfile_includes?('jsbundling-rails')
+    end
+
+    def remove_importmap
+      remove_file File.join(destination_root, 'config/importmap.rb')
+      gsub_file 'Gemfile', /^\s*gem ["']importmap-rails["'].*\n/, ''
+
+      layout = File.join('app/views/layouts', 'application.html.erb')
+      return unless File.exist?(File.join(destination_root, layout))
+
+      gsub_file layout, /^\s*<%=\s*javascript_importmap_tags.*%>\n/, ''
+    end
+
+    def install_jsbundling_with_esbuild
+      gem 'jsbundling-rails'
+      Bundler.with_original_env { run 'bundle install' }
+      rails_command 'javascript:install:esbuild'
+    end
+
+    def gemfile_includes?(gem_name)
+      gemfile = File.join(destination_root, 'Gemfile')
+      return false unless File.exist?(gemfile)
+
+      File.read(gemfile).match?(/^\s*gem ["']#{Regexp.escape(gem_name)}["']/)
+    end
+  end
+end

data/lib/generators/phlex/stimulus/install/templates/app/components/base.rb.erb

@@ -0,0 +1,29 @@
+# typed: true
+# frozen_string_literal: true
+
+# Abstract class for all Phlex components that render HTML in this app.
+#
+# @abstract
+class Components::Base < Phlex::Stimulus::Components::Base
+  # Include any helpers you want to be available across all components
+  include Phlex::Rails::Helpers::Routes
+
+  if Rails.env.development?
+    #: -> void
+    def before_template
+      newline
+      comment { "Before #{self.class.name}" }
+      newline
+      super
+    end
+
+    #: -> void
+    def after_template
+      newline
+      comment { "After #{self.class.name}" }
+      newline
+      super
+    end
+  end
+
+end