product_tours 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea098df5cd9d109566f8f7561a53e182932258742abd06b427596f2b8deb0574
-  data.tar.gz: f7607d43d7cc8eee2174c9232279cf192f6f74d446b1f4c7da246be752f4d2fe
+  metadata.gz: bca51e6535dbdd38d6d683ee0ea95e430acbefd41479f356e1c0e7c330c64697
+  data.tar.gz: fce14b868cabf23946d5658aa5c9362d5b0e3df92e326b27f31164b9590e01cd
 SHA512:
-  metadata.gz: d95991dc7543548549f11544d9f7c898b31a09fae6a06bd23c78e81df86937a2a5edca0c8127f6f7e51a10cd50b2c235fd19e87aa1fedaa8e54bcc8f66872d69
-  data.tar.gz: 1f1cd6f01c210a157d67b1b736a9a0540be356aabc875eb4e0daac5e91e3f6864dd9995413b324a90400ac35d9a5cc83bc12792d0d832111bf43c147e66c5273
+  metadata.gz: 1dec9e04d694dd26b2baafbe9eb6226370ccb728c500c086ebc387e8cf6bdfa7433f5588772b9a9e61be26e2d5558af59dd4d096424a429cc9004abed73b3084
+  data.tar.gz: b86e2d428a86bb9708cbb709eb80e0e5de1ead8bf3a18d32e78c38d64a9e24ce7d41a2bbaea3ee7d214e8d4dadecc74bc35dce1ffcd74e570eb7a78ea3095281

data/AGENTS.md

@@ -81,7 +81,8 @@ YouTube, Vimeo, Loom, Tella, Voomly, a direct MP4/WebM URL, or an uploaded file
 
 ### Lifecycle events
 
-Subscribe in an initializer; there is no callback config to set.
+Subscribe in an initializer when your normal request middleware already sets
+host identity:
 
 ```ruby
 ActiveSupport::Notifications.subscribe("product_tours.completed") do |*, payload|
@@ -91,6 +92,20 @@ end
 
 Names: `product_tours.viewed`, `product_tours.dismissed`, `product_tours.completed`, and `product_tours.unresolved_trigger` — the last one fires when a `data-product-tour` button names a key that does not resolve. Subscribe to it in development; it turns "my button does nothing" into a log line naming the key.
 
+The public widget controller deliberately does not inherit the host's controller.
+If that means a subscriber cannot see the host's current user/account context,
+configure the request-aware lifecycle hook instead:
+
+```ruby
+config.on_event = lambda do |name, payload, request|
+  user = request.env["warden"]&.user
+  ProductTourEventJob.perform_later(name, payload, user&.id)
+end
+```
+
+It receives only `viewed`, `dismissed`, and `completed`, runs inline, and logs
+exceptions without breaking the visitor flow. Keep it fast or enqueue a job.
+
 ### Do not
 
 - **Do not copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** `product_tours_tag` renders what is needed and the engine serves the code. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
@@ -101,7 +116,7 @@ Names: `product_tours.viewed`, `product_tours.dismissed`, `product_tours.complet
 
 ### Configuration
 
-There are five options. That is the whole surface.
+There are seven options. That is the whole surface.
 
 | Option | Default | What it does |
 | --- | --- | --- |
@@ -109,6 +124,7 @@ There are five options. That is the whole surface.
 | `enabled` | everyone | Per-request gate for the widget and its endpoints |
 | `base_controller_class` | `ActionController::Base` | Controller the dashboard inherits. Name your admin's and it adopts that layout, helpers, authentication and request context. Public endpoints never inherit it. |
 | `admin_layout` | `product_tours/application` | Render the dashboard inside your admin shell |
+| `on_event` | no-op | Handle lifecycle events with `(name, payload, request)` when host identity must be resolved from the raw request |
 | `mount_path` | `"/product_tours"` | Keep in sync with `mount_product_tours at:` |
 | `storage_service` | app default | Active Storage service for uploaded video (a `storage.yml` key) |
 
@@ -152,6 +168,6 @@ Conventions this codebase holds to — follow them rather than the first thing t
 - **Uploaded media streams through the engine's gate**, never a public blob URL.
 - **The CSP patch is additive.** It appends to existing sources and drops `'none'` rather than replacing a host's policy — do not let it start overwriting directives.
 - **The dummy app pins `config.active_job.queue_adapter = :test`.** Do not remove it or let it drift back to the `:async` default. Attaching a video enqueues Active Storage's analysis job, and `:async` runs it on a background thread that checks out its own connection — writes no test transaction covers, landing in the middle of whatever runs next. That is a suite that fails order-dependently in a test which never created a row, and it is miserable to trace back.
-- **`lib/product_tours/dashboard.css` is half shared.** Everything above the `GEM-SPECIFIC` banner is the design system all five gems in the family ship — the same tokens, the same `.page-head`/`.tabs`/`.filters`/`.card`/`.badge`/`button`, the same `.dashboard-shell` + `.record-row` + `.detail-panel` two-pane dashboard — identical in every repo apart from the `pt` prefix. Diff it against a sibling before changing it, and carry the change to the other four. Anything only this gem has goes below the banner. New dashboard markup reuses the shared class names rather than inventing a domain-specific one.
+- **`lib/product_tours/dashboard.css` is half shared.** Everything above the `GEM-SPECIFIC` banner is the design system all five gems in the family ship — the same tokens, the same `.page-head`/`.tabs`/`.filters`/`.card`/`.badge`/`button`/`.status-switch`, the same `.dashboard-shell` + `.record-row` + `.detail-panel` two-pane dashboard — identical in every repo apart from the `pt` prefix. Diff it against a sibling before changing it, and carry the change to the other four. Anything only this gem has goes below the banner. New dashboard markup reuses the shared class names rather than inventing a domain-specific one.
 - Every user-facing change bumps `lib/product_tours/version.rb` and adds a `CHANGELOG.md` entry (Keep a Changelog format) that says what it costs, not only what it adds.
 - Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.3.1] - 2026-08-08
+
+- **Hosts can handle lifecycle events with their own request context.** Set
+  `config.on_event` to a callable accepting `(name, payload, request)` when a
+  `viewed`, `dismissed`, or `completed` signal must resolve a signed session,
+  user, account, or tenant that deliberately does not belong in the gem. The
+  existing `ActiveSupport::Notifications` events and their minimal payloads are
+  unchanged. The hook runs inline, so slow work should be enqueued; exceptions
+  are logged and never turn a working tutorial action into a visitor-facing
+  failure.
+
 ## 0.3.0
 
 - **One design system across the family.** The stylesheet now opens with a
@@ -60,8 +73,6 @@
   `remove_index :product_tours_posts, :locale`.
 - A `BackboneTest` now fails the build on any of the above regressing.
 
-## [Unreleased]
-
 ## [0.1.2] - 2026-08-04
 
 - Added `AGENTS.md`: install and integration instructions written for coding
@@ -122,6 +133,7 @@
 - Removed generic tutorial duplication now that translations provide the only
   intentional content-copying workflow.
 
-[Unreleased]: https://github.com/yshmarov/product_tours/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/yshmarov/product_tours/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/yshmarov/product_tours/compare/v0.3.0...v0.3.1
 [0.1.1]: https://github.com/yshmarov/product_tours/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/yshmarov/product_tours/releases/tag/v0.1.0

data/README.md

@@ -228,6 +228,7 @@ Everything is optional — a development install works with zero config. In
 | `authorize_admin` | development only | **Who can manage content at the mount path** |
 | `base_controller_class` | `ActionController::Base` | Controller the dashboard inherits — name your admin's and it adopts its layout, helpers and auth |
 | `admin_layout` | gem layout | Just the shell, if you don't want the whole controller |
+| `on_event` | no-op | Handle lifecycle events with the raw request and host-owned identity/account context |
 | `storage_service` | app default | Named Active Storage service for uploaded videos |
 | `mount_path` | `/product_tours` | Keep in sync only when mounting the engine manually |
 
@@ -236,6 +237,9 @@ ProductTours.configure do |config|
   config.enabled = ->(request) { request.env["warden"]&.user.present? }
   config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
   config.admin_layout = "admin/application"
+  config.on_event = lambda do |name, payload, request|
+    AnalyticsJob.perform_later(name, payload, request.session[:user_id])
+  end
   config.storage_service = :product_tours
 end
 ```
@@ -302,6 +306,20 @@ end
 Your subscriber can attach `Current.user` or account context. That identity does
 not need to become product-tour configuration.
 
+If the engine's public controller does not run your host controller callbacks,
+use `on_event` instead. It receives the same event name and payload plus the raw
+request, so it can safely resolve the host's signed session:
+
+```ruby
+config.on_event = lambda do |name, payload, request|
+  user = request.env["warden"]&.user
+  ProductTourEventJob.perform_later(name, payload, user&.id)
+end
+```
+
+The hook runs inline; enqueue slow work. Exceptions are logged and do not break
+the visitor flow. `product_tours.unresolved_trigger` remains a notification only.
+
 ## Broken triggers fail loudly, not publicly
 
 `data-product-tour="key"` is a contract between code and dashboard content.

data/app/controllers/product_tours/tours_controller.rb

@@ -32,12 +32,20 @@ module ProductTours
         page_url: clean_page_url(params[:page_url]),
         source: params[:source].to_s.presence
       }
-      ActiveSupport::Notifications.instrument("product_tours.#{action}", payload)
+      event_name = "product_tours.#{action}"
+      ActiveSupport::Notifications.instrument(event_name, payload)
+      notify_host(event_name, payload)
       head :no_content
     end
 
     private
 
+    def notify_host(event_name, payload)
+      ProductTours.config.on_event.call(event_name, payload, request)
+    rescue StandardError => e
+      Rails.logger.error("product_tours: on_event hook raised #{e.class}: #{e.message}")
+    end
+
     def post_payload(post)
       video = post.resolved_video
       video[:url] = media_path(post) if video&.dig(:kind) == 'upload'

data/lib/generators/product_tours/install/templates/initializer.rb

@@ -21,6 +21,13 @@ ProductTours.configure do |config|
   # Tutorials resolve in the page's current I18n.locale and fall back to
   # I18n.default_locale when no translation exists.
 
+  # Optional lifecycle hook. Receives the event name, minimal payload, and raw
+  # request so the host can resolve its own user/account context. Runs inline;
+  # enqueue slow work. Hook errors are logged and never break the visitor flow.
+  # config.on_event = lambda do |name, payload, request|
+  #   AnalyticsJob.perform_later(name, payload, request.session[:user_id])
+  # end
+
   # Optional dedicated Active Storage service for uploaded videos.
   # config.storage_service = :product_tours
 

data/lib/product_tours/configuration.rb

@@ -7,7 +7,7 @@ module ProductTours
     DEFAULT_ADMIN_LAYOUT = 'product_tours/application'
 
     attr_accessor :enabled, :authorize_admin, :admin_layout, :mount_path,
-                  :storage_service
+                  :storage_service, :on_event
 
     # The controller the DASHBOARD inherits from, as a String so it resolves
     # lazily rather than at config time. Default: a plain
@@ -31,6 +31,7 @@ module ProductTours
       @base_controller_class = 'ActionController::Base'
       @mount_path = '/product_tours'
       @storage_service = nil
+      @on_event = ->(_name, _payload, _request) {}
     end
 
     def widget_endpoint = "#{mount_path.to_s.chomp('/')}/widget"

data/lib/product_tours/dashboard.css

@@ -144,6 +144,19 @@
   & .actions form { display: inline; }
   & .form-actions { padding-top: 12px; }
 
+  /* Status switch: one pill holding every state a record can be in, the state it
+     is in now lit. Each other segment is a submit button, so moving a record
+     takes one click and no JavaScript; the current segment is a `type="button"`
+     so clicking it cannot re-file the record it is already filed under. Two
+     states or five, the pill sizes itself. A gem tints the lit segment with its
+     own status colour — see the `GEM-SPECIFIC` section. */
+  & .status-switch { display: inline-flex; flex: 0 0 auto; margin: 0; padding: 3px; border: 1px solid var(--pt-border); border-radius: 999px; background: var(--pt-bg); }
+  & .status-switch button { min-height: 30px; padding: 0 12px; border: 0; border-radius: 999px; background: none; color: var(--pt-muted); font-size: 13px; font-weight: 700; white-space: nowrap; transition: background .16s ease, color .16s ease; }
+  & .status-switch button:hover { border: 0; background: color-mix(in srgb, var(--pt-muted) 12%, transparent); color: var(--pt-text); }
+  & .status-switch button.current { background: var(--pt-surface); color: var(--pt-text); box-shadow: 0 1px 2px rgba(15, 23, 42, .12); cursor: default; }
+  & .status-switch button.current:hover { background: var(--pt-surface); }
+  & .panel-head .status-switch { margin-left: auto; }
+
   & .card { overflow: hidden; border: 1px solid var(--pt-border); border-radius: 12px; background: var(--pt-surface); }
   & .card.pad { padding: 16px; overflow: visible; }
   & table { width: 100%; border-collapse: collapse; }
@@ -266,6 +279,7 @@
     & .dashboard-detail .detail-panel { min-height: calc(100vh - 64px); }
     & .mobile-back { display: block; flex: 0 0 auto; margin: 4px 0 10px; font-size: 13px; }
     & .panel-head h1 { font-size: 18px; }
+    & .status-switch button { padding: 0 9px; font-size: 12px; }
     & dl { grid-template-columns: 1fr; gap: 3px; }
     & dd { margin-bottom: 8px; }
   }

data/lib/product_tours/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ProductTours
-  VERSION = '0.3.0'
+  VERSION = '0.3.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: product_tours
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Yaroslav Shmarov