tuix_rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd2c3676824936348b36faf27edba0191067f31a2d2ecce7c5d5e4f33b05178d
-  data.tar.gz: 1be22f93ab08113a150736b9a2d7726076a36481c756c8edbbf0af2e2e87e190
+  metadata.gz: 7709c6ce025779c0fdc7f6a31f535b5d7f816b649fb9472ec7c3358d4a2b44f5
+  data.tar.gz: 7a5b77dd9c370ea6531fa1842e45066c9a68f7499a21ddd230a901c56ffb4f3c
 SHA512:
-  metadata.gz: 6a58fd4728e42ef4be71e8bec5e623245319d819e716e81778d2eca5a8ae4c17da31cfcc28c8c6f484285f46093008d6d71f82e8cf077630618544905ebcb576
-  data.tar.gz: ca64d02cb52fce897c1f9610976d4b92ec0f1c4f9408aaec4b18b1978d8ecb0f82d1a4061e44a95ca44c22debd1dd4328766418aceb862b9ed0a3c40ecf53b78
+  metadata.gz: 10baca16212eebd66168e79e61657c44e8f3f0eab8581fcb398832a1a8d909278a946ac196ae03d633843690437323e415f8e4f3760de8bb5eeacf0c604331d8
+  data.tar.gz: e091941eeae31eb0edef34848a6ca94d71bc5885095f2ff0dcc08b52409c4da69345d90c181cb1a302b2e0e18c13bd47c5fe3f0914cf16129d89552338176fe4

data/README.md

@@ -5,26 +5,20 @@ widget delivery, CSP nonces and Turbo navigation. Requires Ruby 3.2+ and Rails
 7.2–8.x (Rails itself may require a newer Ruby). No database, npm installation,
 asset precompile or separate Tuix login is needed by the host application.
 
-MIT licensed. Until the gem is on RubyGems, install it from a checkout of this
-repository or from a built gem, as below.
+MIT licensed, on [RubyGems](https://rubygems.org/gems/tuix_rails).
 
 ## Install
 
-Add the package to the host application's Gemfile, using a checkout of this
-repository or an unpacked gem artifact:
-
-```ruby
-gem "tuix_rails", path: "/absolute/path/to/tuix/packages/rails"
-```
-
-For the built artifact, run `gem unpack output/releases/tuix_rails-0.1.0.gem`
-and point `path:` at the resulting `tuix_rails-0.1.0` directory.
+In the host application:
 
 ```sh
-bundle install
+bundle add tuix_rails
 bin/rails generate tuix:install
 ```
 
+To try a change before its release, use `gem "tuix_rails", path: "/absolute/path/to/packages/rails"`
+in the Gemfile instead.
+
 The generator creates `config/initializers/tuix.rb`. It prints the layout steps
 instead of guessing your authentication library or rewriting custom layouts.
 Re-running it uses Rails' normal file conflict handling; `--skip` preserves a
@@ -95,6 +89,19 @@ shared full-page cache. Browser back/forward cache follows the host's existing
 session policy; the bridge destroys the widget on `pagehide` and re-reads the
 current page on `pageshow`. See the [Turbo lifecycle documentation](https://turbo.hotwired.dev/handbook/building).
 
+## Component names
+
+`tuix_component` writes the `data-tuix-component` attribute the widget reads, so a report says which view or partial it is about. Put it on the root element of a partial or layout, in either ERB form:
+
+```erb
+<%= tag.form class: "f", **tuix_component do %> ... <% end %>
+<form class="f" <%= tag.attributes(tuix_component) %>> ... </form>
+```
+
+It returns `{ data: { tuix_component: "orders/_form" } }`. Without an argument the name is the virtual path of the template being rendered (`orders/_form`, `layouts/application`); it is right inside nested partials and collections, and back in the parent after a partial returns. Pass a name to choose your own: `tuix_component("Checkout.Button")`. In a ViewComponent call `helpers.tuix_component(self.class.name)`, since the helper cannot see a component's own template. A block you write in one template and render inside a layout partial (`render layout: "box" do ... end`) runs while that partial is current, so give elements in it an explicit name.
+
+A name the widget would ignore (it must start with a letter or underscore, continue with letters, digits and `_ . : / -`, and have at most 100 characters), or no name at all (an inline template has no virtual path), gives `{}`: no attribute is rendered and nothing raises.
+
 ## Content security policy
 
 Helpers use Rails' `content_security_policy_nonce` by default; an explicit
@@ -110,7 +117,7 @@ previews need `blob:` and `data:`. Capture requires `style-src-attr 'unsafe-inli
 and the empty stylesheet hash
 `'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='` in the applicable style
 directive. Account for `script-src-elem`/`style-src-elem` when present. Test capture
-against the real host policy; Tuix → Project settings → Install tuix → Content
+against the real host policy; Tuix → Project settings → Installation → Content
 Security Policy lists the exact sources for your project.
 
 ## Development
@@ -130,7 +137,7 @@ npm run test:browser -w @tuix/rails
 CI covers Rails 7.2/Ruby 3.2, Rails 8.0/Ruby 3.3 and Rails 8.1/Ruby 3.4.
 Integration tests boot a real Rails application, render helpers, fetch the asset
 through middleware, check identity signing/escaping, and exercise the generator.
-The package command builds `output/releases/tuix_rails-0.1.0.gem`, verifies its
+The package command builds `output/releases/tuix_rails-0.2.0.gem`, verifies its
 contents and reruns integration tests against a temporary gem installation before copying
 the artifact into place. It never publishes. CI uploads the same local artifact, and the
 release workflow publishes that artifact.
@@ -149,3 +156,8 @@ its remote run is separate from these local results.
 
 Before rolling out to your users, try report creation, screenshots and notifications
 against a real Tuix project using the host's authentication, origin and CSP.
+
+## Version history
+
+- **0.2.0**: adds the view helper `tuix_component` (see Component names), which writes the `data-tuix-component` attribute, so a report says which view or partial it is about. Nothing changes until you call it.
+- **0.1.0**: the first release.

data/lib/tuix_rails/helper.rb

@@ -1,6 +1,9 @@
 require_relative "assets"
 
 module TuixRails
+  # A component name the widget accepts (`data-tuix-component`).
+  COMPONENT_NAME = /\A[A-Za-z_][A-Za-z0-9_.:\/-]{0,99}\z/
+
   module Helper
     def tuix_assets(nonce: content_security_policy_nonce)
       path = "#{request.script_name}#{Assets::PATH}"
@@ -14,5 +17,31 @@ module TuixRails
       content_tag(:div, "", id: "tuix-rails", hidden: true,
         data: { tuix_rails: payload && JSON.generate(payload), turbo_temporary: true })
     end
+
+    # Names the component a feedback report is about. Returns a hash for tag
+    # helpers (`tag.form **tuix_component`, `tag.attributes(tuix_component)`):
+    # `{ data: { tuix_component: "orders/_form" } }`. Without an argument the name
+    # is the virtual path of the template being rendered (`orders/_form`,
+    # `layouts/application`); pass a String for any other
+    # explicit name. In a ViewComponent call `helpers.tuix_component(self.class.name)`.
+    #
+    # Returns `{}` (renders no attribute) when there is no name or the widget
+    # would ignore it. It never raises in a view.
+    def tuix_component(name = nil)
+      name = name.nil? ? tuix_template_path : name
+      name = name.to_s if name.is_a?(Symbol)
+      return {} unless name.is_a?(String) && name.valid_encoding? && name.match?(TuixRails::COMPONENT_NAME)
+      { data: { tuix_component: name } }
+    end
+
+    private
+
+    # `@virtual_path` is the template Action View is rendering right now: each
+    # compiled template sets it on entry and `ActionView::Base#_run` restores the
+    # caller's value on exit, so it is right inside nested partials and after
+    # they return. It is the same ivar Rails' own `t(".key")` lookup reads.
+    def tuix_template_path
+      @virtual_path
+    end
   end
 end

data/lib/tuix_rails/version.rb

@@ -1,3 +1,3 @@
 module TuixRails
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tuix_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tuix