micra-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a6d0b13ecc6a8986ce5eea667182297f74cd8c5c8b32632e04b1b58f6cd4c26
+  data.tar.gz: f2d33530d1f24d31382a61a4bf1321d3a566d5ddb1cabe8906724afe7628fa07
+SHA512:
+  metadata.gz: dbe6c5e23d82e90f2414e448db3a01bdd3015708bc940439e279cad84117fd4a6547d4a4a712f5323aa9d2479033c53cc7d6fff057f05391a1335c4e20967c25
+  data.tar.gz: c17d3344f4c6419d2c00c3f493b322473bc0d31bbe08cac15de3b9b1658fec75ff2e7ab805166a50b018d0a870b751fbc20cbf7738a77cbaf6159072f2733089

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+- Initial release skeleton.
+- Helpers: `micra_component`, `micra_includes`, `micra_state`.
+- Generator: `rails g micra:install` pins micra.js via importmap and adds a
+  `<%= micra_includes %>` line to the application layout.
+
+[unreleased]: https://github.com/denisfl/micra-rails/compare/v0.0.0...HEAD

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Denis Fedosov-Ledovskikh
+
+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 @@
+# micra-rails
+
+Rails integration for [Micra.js] — reactive UI in **~5 kB gzip**, no build step.
+
+Drop reactive client state, declarative directives, and a cross-component event
+bus into any Rails view — the way `data-controller` works for Stimulus, except
+your state is reactive and your bindings are declarative.
+
+```erb
+<%= micra_component :counter, count: 0 do %>
+  <button @click="dec">−</button>
+  <strong data-text="count"></strong>
+  <button @click="inc">+</button>
+<% end %>
+```
+
+```js
+// app/javascript/application.js
+import * as Micra from "micra";
+
+Micra.define("counter", {
+  state: { count: 0 },
+  inc() {
+    this.state.count++;
+  },
+  dec() {
+    this.state.count--;
+  },
+});
+```
+
+That's the whole API surface. Micra mounts on `DOMContentLoaded`, walks
+`[data-component]`, and wires up reactive bindings.
+
+## Install
+
+```bash
+bundle add micra-rails
+bin/rails generate micra:install
+```
+
+The generator:
+
+- pins `micra` via importmap to jsDelivr CDN
+- inserts `<%= micra_includes %>` into your application layout
+- prints a quickstart counter example
+
+## Helpers
+
+### `micra_component(name, tag: :div, **props, &block)`
+
+Wraps content in `<div data-component="<name>">` with `data-*` attributes for
+each prop. Primitives (`String`, `Symbol`, `Numeric`, `Boolean`, `nil`) are
+stringified; everything else (`Hash`, `Array`, ActiveRecord objects via
+`as_json`) is JSON-encoded.
+
+```erb
+<%= micra_component :user_card, user: @user.as_json, tag: :article do %>
+  <h3 data-text="user.name"></h3>
+  <p data-text="user.bio"></p>
+<% end %>
+```
+
+### `micra_includes`
+
+Outputs importmap tags + the `Micra.start()` boot script. Call once in your
+application layout (the installer does this for you).
+
+### `micra_state(**props)`
+
+Returns a hash of `data-*` attributes — useful when you want to attach state
+to an existing element instead of wrapping it.
+
+```erb
+<form id="signup" <%= micra_state(intent: "signup", token: form_token).to_html %>>
+  ...
+</form>
+```
+
+## Why Micra over the alternatives
+
+|                            | Micra.js         | Stimulus          | Alpine.js      | Hotwire alone    |
+| -------------------------- | ---------------- | ----------------- | -------------- | ---------------- |
+| Bundle (gzip)              | ~5 kB            | ~10 kB            | ~14 kB         | —                |
+| Reactive client state      | ✓                | manual            | ✓              | server-driven    |
+| Standard `data-*` syntax   | ✓                | `data-controller` | `x-*`          | `turbo-*`        |
+| Pairs with Turbo / Hotwire | ✓                | ✓                 | works          | native           |
+| Sweet spot                 | reactive islands | Rails behaviors   | small reactive | server-driven UI |
+
+Use **Stimulus** for behaviors that don't need client state.
+Use **Micra** when you need reactive state on a Rails page.
+Pair Micra with **Turbo Streams** for the full Hotwire stack with reactivity.
+
+## Production vs CDN
+
+By default, `micra-rails` pins to jsDelivr:
+
+```ruby
+pin "micra", to: "https://cdn.jsdelivr.net/npm/micra.js@2.1.0/dist/micra.esm.js"
+```
+
+To self-host (no third-party CDN):
+
+```bash
+bin/importmap pin micra --download
+```
+
+This downloads `micra.esm.js` into `vendor/javascript/` and updates the pin.
+
+## Compatibility
+
+| Rails | Status        |
+| ----- | ------------- |
+| 8.x   | ✓             |
+| 7.2   | ✓             |
+| 7.1   | ✓             |
+| < 7.1 | not supported |
+
+Requires Ruby ≥ 3.1.
+
+## License
+
+MIT © Denis Fedosov-Ledovskikh
+
+[Micra.js]: https://github.com/denisfl/micra.js

data/Rakefile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "bundler/gem_tasks" # provides rake build, rake install, rake release
+require "rake/testtask"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake" if File.exist?(APP_RAKEFILE)
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/generators/micra/install/install_generator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Micra
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      desc "Installs Micra.js: pins via importmap and inserts <%= micra_includes %> into the application layout."
+
+      source_root File.expand_path("templates", __dir__)
+
+      def pin_micra_in_importmap
+        return unless File.exist?("config/importmap.rb")
+
+        line = %(pin "micra", to: "https://cdn.jsdelivr.net/npm/micra.js@#{Micra::Rails::MICRA_JS_VERSION}/dist/micra.esm.js", preload: true\n)
+
+        append_to_file "config/importmap.rb" do
+          "\n# Micra.js — reactive UI directives (<5 KB gzip)\n#{line}"
+        end
+      end
+
+      def inject_includes_in_layout
+        layout = "app/views/layouts/application.html.erb"
+        return unless File.exist?(layout)
+
+        unless File.read(layout).include?("micra_includes")
+          inject_into_file layout,
+            "    <%= micra_includes %>\n",
+            before: "  </head>\n"
+        end
+      end
+
+      def show_done_message
+        say ""
+        say "✔ Micra.js installed."
+        say ""
+        say "  Try it in any view:"
+        say ""
+        say %(    <%= micra_component :counter, count: 0 do %>)
+        say %(      <button @click="dec">−</button>)
+        say %(      <strong data-text="count"></strong>)
+        say %(      <button @click="inc">+</button>)
+        say %(    <% end %>)
+        say ""
+        say %(  Then in JS (app/javascript/application.js or similar):)
+        say ""
+        say %(    import * as Micra from "micra")
+        say %(    Micra.define("counter", {)
+        say %(      state: { count: 0 },)
+        say %(      inc() { this.state.count++ },)
+        say %(      dec() { this.state.count-- },)
+        say %(    }))
+        say ""
+        say "  Docs: https://denisfl.github.io/micra.js/"
+        say ""
+      end
+    end
+  end
+end

data/lib/micra/rails/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Micra
+  module Rails
+    # Mountable engine: registers the importmap pin and the view helpers.
+    class Engine < ::Rails::Engine
+      isolate_namespace Micra::Rails
+
+      initializer "micra.rails.importmap", before: "importmap" do |app|
+        next unless app.config.respond_to?(:importmap)
+
+        app.config.importmap.paths << root.join("config/importmap.rb")
+      end
+
+      initializer "micra.rails.helpers" do
+        ActiveSupport.on_load(:action_view) do
+          require "micra/rails/view_helpers"
+          include Micra::Rails::ViewHelpers
+        end
+      end
+    end
+  end
+end

data/lib/micra/rails/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Micra
+  module Rails
+    VERSION = "0.1.0"
+
+    # Tracks the Micra.js npm version we ship by default. The importmap pin
+    # uses this value. Bump it together with VERSION when wrapping a new
+    # upstream release.
+    MICRA_JS_VERSION = "2.1.0"
+  end
+end

data/lib/micra/rails/view_helpers.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Micra
+  module Rails
+    # View helpers for Micra.js components.
+    #
+    #   <%= micra_component :counter, count: 0 do %>
+    #     <button @click="dec">−</button>
+    #     <strong data-text="count"></strong>
+    #     <button @click="inc">+</button>
+    #   <% end %>
+    #
+    # Produces:
+    #
+    #   <div data-component="counter" data-count="0">
+    #     <button @click="dec">−</button>
+    #     <strong data-text="count"></strong>
+    #     <button @click="inc">+</button>
+    #   </div>
+    module ViewHelpers
+      # Renders a wrapper <%= tag %> with `data-component="<name>"` and
+      # `data-<key>="<value>"` for each prop. Non-string values are JSON-encoded
+      # so they round-trip via this.prop() in Micra.
+      def micra_component(name, tag: :div, **props, &block)
+        attributes = {"data-component" => name.to_s}
+
+        props.each do |key, value|
+          attributes["data-#{key.to_s.dasherize}"] = serialize_prop(value)
+        end
+
+        content_tag(tag, capture(&block), attributes)
+      end
+
+      # Drop into your application layout once. Outputs the importmap module
+      # script that boots Micra and a final <script>Micra.start()</script>.
+      def micra_includes
+        capture do
+          concat javascript_importmap_tags
+          concat javascript_tag(<<~JS, type: "module")
+            import * as Micra from "micra"
+            window.Micra = Micra
+            document.addEventListener("DOMContentLoaded", () => Micra.start())
+          JS
+        end
+      end
+
+      # Inline JSON props for a single component instance.
+      #
+      #   <%= micra_state user: @user.as_json %>
+      #
+      # Equivalent to writing data-user='{"id":1,...}' yourself.
+      def micra_state(**props)
+        props.map { |k, v| ["data-#{k.to_s.dasherize}", serialize_prop(v)] }.to_h
+      end
+
+      private
+
+      def serialize_prop(value)
+        case value
+        when String, Symbol, Numeric, TrueClass, FalseClass, NilClass
+          value.to_s
+        else
+          value.to_json
+        end
+      end
+    end
+  end
+end

data/lib/micra/rails.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails"
+require "importmap-rails"
+
+require "micra/rails/version"
+require "micra/rails/engine"
+
+module Micra
+  module Rails
+    # Convenience accessor used by ViewHelpers and the install generator.
+    # In production you may want to vendor the minified file instead of
+    # hitting jsDelivr — flip `Micra::Rails.vendored = true` and put the
+    # file at `app/assets/javascripts/micra.min.js`.
+    class << self
+      attr_accessor :vendored
+    end
+
+    self.vendored = false
+  end
+end

data/lib/micra-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "micra/rails"

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: micra-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Denis Fedosov-Ledovskikh
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: importmap-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |
+  Drop-in Rails helpers and an importmap pin for Micra.js — a 5 kB reactive
+  framework for server-rendered apps. Provides micra_component helper,
+  SSR-friendly props via data-* attributes, and a one-command installer.
+email:
+- denis@fedosov.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/generators/micra/install/install_generator.rb
+- lib/micra-rails.rb
+- lib/micra/rails.rb
+- lib/micra/rails/engine.rb
+- lib/micra/rails/version.rb
+- lib/micra/rails/view_helpers.rb
+homepage: https://github.com/denisfl/micra-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/denisfl/micra-rails
+  source_code_uri: https://github.com/denisfl/micra-rails
+  changelog_uri: https://github.com/denisfl/micra-rails/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Rails integration for Micra.js — reactive UI in ~5 kB, no build step
+test_files: []