RubyGems - onboard_on_rails - Versions diffs - 0.1.0 - Mend

onboard_on_rails 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (62) hide show

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6db171d145c948dd206a246da8de2c21c4e9abfb9f7d7f078a090c47009df1a7
+  data.tar.gz: 3192fe22e98c26a5792e7cd13e41e9f526fbb39528ca8bae907b8dc472d5c286
+SHA512:
+  metadata.gz: 57245caf7f6477dd5b290260410beca6d57aff53149acee4c1b3c710811b871520c295a4d5cde5eac388c0ea1b4101ae98550c7e265d309a094f81121291f60a
+  data.tar.gz: 86748d9f85f060cdd897be576acdb0561dd08afec36fe3e5e67d1b5d97490757f89b7bca4720d574660b21decb898007f7aa37cac5bd9890a4c798bf0a8a6f68

data/README.md ADDED Viewed

@@ -0,0 +1,235 @@
+# OnboardOnRails
+A universal onboarding tour engine for Ruby on Rails. Mount a full-featured admin panel into your app and create interactive product tours — no front-end framework required.
+## Features
+- **Admin Panel** — create and manage tours, steps, and lessons from a browser UI
+- **Visual Selector Picker** — point-and-click CSS selector builder (iframe-based)
+- **4 Themes** — Tooltip, Modal, Banner, Slideout — configurable per tour and per step
+- **A/B Testing** — split users into deterministic groups, compare completion rates
+- **User Targeting** — DSL for registering targetable attributes with 15 operators (eq, starts_with, contains, matches, in, gt, etc.)
+- **Scheduling** — set start/end dates for time-limited tours
+- **Frequency Control** — once, every session, or always
+- **Trigger Types** — auto (page load), event-based, or manual via API
+- **Device Targeting** — run tours on all devices, desktop only, or mobile only
+- **Theming** — configurable accent color and default font applied to admin panel and tour defaults
+- **Overlay Toggle** — per-tour backdrop on/off
+- **SSR + SPA support** — vanilla JS client works with Turbo, React, or classic Rails
+- **i18n** — English and Russian out of the box, with per-user locale resolution
+- **Self-Tour Lessons** — built-in interactive tutorials that teach the admin panel itself
+- **Statistics** — completion rates, drop-off per step, A/B breakdown
+## Requirements
+- Ruby >= 3.1
+- Rails >= 7.0
+- PostgreSQL (jsonb columns for url_pattern, segment_rules, style_overrides)
+## Quick Installation
+### 1. Add the gem
+```ruby
+# Gemfile
+gem "onboard_on_rails"
+```
+```bash
+bundle install
+```
+### 2. Mount the engine
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount OnboardOnRails::Engine => "/onboard"
+  # ...
+end
+```
+### 3. Run migrations
+```bash
+bin/rails onboard_on_rails:install:migrations
+bin/rails db:migrate
+```
+### 4. Create initializer
+```ruby
+# config/initializers/onboard_on_rails.rb
+OnboardOnRails.configure do |config|
+  config.user_class = "User"
+  config.current_user_method = :current_user
+  config.admin_auth = ->(controller) {
+    controller.current_user&.admin?
+  }
+  # Optional: brand the admin panel and tour defaults
+  config.accent_color = "#2d3436"           # hex, 6 digits — dark/light/rgba variants derived automatically
+  config.default_font = "Inter, sans-serif" # applied to tours when no style override is set
+  # Optional: resolve the locale for each user (defaults to "ru")
+  config.user_locale = ->(user) { user.locale || "en" }
+  config.register_attribute :email, type: :string, label: "Email" do |user|
+    user.email
+  end
+  config.register_attribute :plan, type: :string, label: "Plan", values: ["free", "pro", "enterprise"] do |user|
+    user.plan
+  end
+end
+```
+### 5. Add meta tags and assets to your layout
+```erb
+<%# app/views/layouts/application.html.erb %>
+<head>
+  <%= onboard_on_rails_meta_tags %>
+  <%= javascript_include_tag "onboard_on_rails/client" %>
+  <%= stylesheet_link_tag "onboard_on_rails/client" %>
+</head>
+```
+## Configuration
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `user_class` | String | `"User"` | ActiveRecord model representing users |
+| `admin_auth` | Lambda | `->(_) { true }` | Receives controller, returns true/false for admin access |
+| `current_user_method` | Symbol | `:current_user` | Method name on your ApplicationController that returns the current user |
+| `user_locale` | Lambda | `->(_) { "ru" }` | Receives the user, returns a locale code used to render tours |
+| `accent_color` | String | `"#2d3436"` | 6-digit hex color; drives admin panel branding and default tour accents (light/dark/rgba variants are derived automatically) |
+| `default_font` | String | `nil` | CSS `font-family` used as a default on tours when no style override is set |
+| `register_attribute` | DSL | — | Register a user attribute for targeting (see below) |
+## User Targeting
+Register attributes that can be used for targeting in the admin panel. Each attribute needs a type, label, and a block that extracts the value from the user object.
+```ruby
+OnboardOnRails.configure do |config|
+  # String attributes — supports: eq, not_eq, in, not_in, starts_with, ends_with,
+  #   contains, not_contains, matches (regex), length_gt, length_lt
+  config.register_attribute :email, type: :string, label: "Email",
+    description: "User email address" do |user|
+    user.email
+  end
+  # String with predefined values — admin sees a dropdown instead of text input
+  config.register_attribute :plan, type: :string, label: "Plan",
+    description: "Subscription plan",
+    values: ["free", "pro", "enterprise"] do |user|
+    user.plan
+  end
+  # Number attributes — supports: eq, not_eq, in, not_in, gt, lt, gte, lte
+  config.register_attribute :account_id, type: :number, label: "Account ID",
+    description: "ID of the user's account" do |user|
+    user.account_id
+  end
+  # Boolean attributes — supports: eq (true/false dropdown)
+  config.register_attribute :admin, type: :boolean, label: "Admin?",
+    description: "Whether the user is an admin" do |user|
+    user.admin?
+  end
+end
+```
+### Parameters
+| Parameter | Required | Description |
+|---|---|---|
+| `key` | yes | Symbol identifier (first argument) |
+| `type` | yes | `:string`, `:number`, or `:boolean` |
+| `label` | yes | Display name in the admin panel |
+| `description` | no | Help text shown below the attribute selector |
+| `values` | no | Array of allowed values (renders as dropdown in admin) |
+| `block` | yes | `\|user\| -> value` — extracts the attribute value |
+### Examples
+Show a tour to users whose email starts with "foo":
+- Attribute: `email`, Operator: `starts_with`, Value: `foo`
+Show a tour to specific accounts:
+- Attribute: `account_id`, Operator: `in`, Value: `123, 456, 789`
+Show a tour to users with names longer than 10 characters:
+- Attribute: `name`, Operator: `length_gt`, Value: `10`
+Combine multiple conditions with AND/OR logic in the admin panel.
+## Usage
+1. Open the admin panel at `/onboard/admin`
+2. Click **New Tour**, fill in name, URL pattern, theme, and trigger settings
+3. Add steps — set CSS selector, placement, title, and body text
+4. Use the visual selector picker to choose elements on your pages
+5. Set the tour status to **Active**
+6. Visit the target page as a logged-in user — the tour starts automatically
+## Self-Tour Lessons
+OnboardOnRails ships with built-in tutorials that teach admins how to use the panel:
+- **Lesson 1**: Overview of the admin panel
+- **Lesson 2**: Creating and configuring a tour
+- **Lesson 3**: Adding and styling steps
+To create them, go to `/onboard/admin/lessons` and click **Create Lessons**, or call:
+```ruby
+OnboardOnRails::SelfTourSeeder.seed!
+```
+## API
+### Client-side (JavaScript)
+```javascript
+// Track a custom event
+OnboardOnRails.trackEvent("first_project_created", { project_id: 42 });
+```
+### Server-side (Ruby)
+```ruby
+# Track an event for a user
+OnboardOnRails.track_event(user, "subscription_activated", { plan: "pro" })
+```
+### REST Endpoints
+| Method | Path | Description |
+|---|---|---|
+| GET | `/onboard/api/tours?url=/dashboard` | Fetch matching tour for URL |
+| POST | `/onboard/api/completions` | Create/update completion record |
+| POST | `/onboard/api/events` | Track a custom event |
+## Tech Stack
+| Layer | Technology |
+|---|---|
+| Backend | Rails Engine (mountable, isolated namespace) |
+| Database | PostgreSQL with jsonb columns |
+| Admin JS | Vanilla JavaScript (no framework) |
+| Client JS | Vanilla JavaScript (no framework) |
+| Asset pipeline | Sprockets |
+| Styling | Plain CSS with custom properties |
+| i18n | Rails I18n (en, ru) |
+| Testing | RSpec + FactoryBot |
+## Detailed Documentation
+See [docs/setup.md](docs/setup.md) for comprehensive Russian documentation covering authentication, targeting, theming, A/B testing, API reference, and more.
+## License
+MIT

data/Rakefile ADDED Viewed

@@ -0,0 +1,10 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/app/assets/javascripts/onboard_on_rails/admin.js ADDED Viewed

@@ -0,0 +1,306 @@
+// OnboardOnRails Admin Bundle
+// Compatible with both Sprockets and Propshaft
+// === Step Preview Controller ===
+document.addEventListener("DOMContentLoaded", function() {
+  // Find the step edit form — only run on step edit pages
+  var form = document.querySelector("[data-controller='step-preview']");
+  if (!form) return;
+  function updatePreview() {
+    var title = document.querySelector("[data-step-preview-target='title']");
+    var body = document.querySelector("[data-step-preview-target='body']");
+    var previewTitle = document.querySelector("[data-step-preview-target='previewTitle']");
+    var previewBody = document.querySelector("[data-step-preview-target='previewBody']");
+    var previewButton = document.querySelector("[data-step-preview-target='previewButton']");
+    var bgColor = document.querySelector("[data-step-preview-target='bgColor']");
+    var textColor = document.querySelector("[data-step-preview-target='textColor']");
+    var buttonColor = document.querySelector("[data-step-preview-target='buttonColor']");
+    var fontFamily = document.querySelector("[data-step-preview-target='fontFamily']");
+    var fontSize = document.querySelector("[data-step-preview-target='fontSize']");
+    var borderRadius = document.querySelector("[data-step-preview-target='borderRadius']");
+    var tooltipBody = document.querySelector("[data-step-preview-target='tooltipBody']");
+    if (previewTitle && title) previewTitle.textContent = title.value || "Step Title";
+    if (previewBody && body) previewBody.textContent = body.value || "Step description goes here...";
+    if (tooltipBody) {
+      if (bgColor) tooltipBody.style.background = bgColor.value;
+      if (fontFamily) tooltipBody.style.fontFamily = fontFamily.value;
+      if (borderRadius) tooltipBody.style.borderRadius = borderRadius.value;
+    }
+    if (previewTitle && textColor) previewTitle.style.color = textColor.value;
+    if (previewBody && textColor) previewBody.style.color = textColor.value;
+    if (previewBody && fontSize) previewBody.style.fontSize = fontSize.value;
+    if (previewButton && buttonColor) previewButton.style.background = buttonColor.value;
+  }
+  // Attach listeners to all form inputs
+  form.querySelectorAll("input, textarea, select").forEach(function(el) {
+    el.addEventListener("input", updatePreview);
+    el.addEventListener("change", updatePreview);
+  });
+});
+// === Segment Rules Controller ===
+document.addEventListener("DOMContentLoaded", function() {
+  var wrapper = document.querySelector("[data-controller='segment-rules']");
+  if (!wrapper) return;
+  var container = wrapper.querySelector("[data-segment-rules-target='container']");
+  var output = wrapper.querySelector("[data-segment-rules-target='output']");
+  var logicSelect = wrapper.querySelector("[data-segment-rules-target='logic']");
+  var addButton = wrapper.querySelector("[data-action*='segment-rules#add']");
+  var availableAttributes = [];
+  var operatorLabels = {};
+  var placeholders = {};
+  try { availableAttributes = JSON.parse(wrapper.getAttribute("data-available-attributes") || "[]"); } catch(e) {}
+  try { operatorLabels = JSON.parse(wrapper.getAttribute("data-operator-labels") || "{}"); } catch(e) {}
+  try { placeholders = JSON.parse(wrapper.getAttribute("data-placeholders") || "{}"); } catch(e) {}
+  var OPERATORS_BY_TYPE = {
+    string:  ["eq", "not_eq", "in", "not_in", "starts_with", "ends_with", "contains", "not_contains", "matches", "length_gt", "length_lt"],
+    number:  ["eq", "not_eq", "in", "not_in", "gt", "lt", "gte", "lte"],
+    boolean: ["eq"]
+  };
+  function findAttr(key) {
+    for (var i = 0; i < availableAttributes.length; i++) {
+      if (availableAttributes[i].key === key) return availableAttributes[i];
+    }
+    return null;
+  }
+  function serialize() {
+    var rows = container.querySelectorAll(".oor-segment-row");
+    var conditions = Array.from(rows).map(function(row) {
+      var op = row.querySelector(".oor-segment-op").value;
+      var val = row.querySelector(".oor-segment-val").value;
+      if (op === "in" || op === "not_in") {
+        val = val.split(",").map(function(v) { return v.trim(); });
+      }
+      return {
+        attribute: row.querySelector(".oor-segment-attr").value,
+        operator: op,
+        value: val
+      };
+    });
+    var logic = logicSelect ? logicSelect.value : "and";
+    output.value = JSON.stringify({ conditions: conditions, logic: logic });
+  }
+  function buildAttrSelect(selectedKey) {
+    var html = "";
+    for (var i = 0; i < availableAttributes.length; i++) {
+      var a = availableAttributes[i];
+      var sel = a.key === selectedKey ? " selected" : "";
+      html += '<option value="' + a.key + '"' + sel + '>' + a.label + '</option>';
+    }
+    return html;
+  }
+  function buildOpSelect(type, selectedOp) {
+    var ops = OPERATORS_BY_TYPE[type] || OPERATORS_BY_TYPE.string;
+    var html = "";
+    for (var i = 0; i < ops.length; i++) {
+      var op = ops[i];
+      var label = operatorLabels[op] || op;
+      var sel = op === selectedOp ? " selected" : "";
+      html += '<option value="' + op + '"' + sel + '>' + label + '</option>';
+    }
+    return html;
+  }
+  function buildValueInput(attrDef, operator, value) {
+    if (operator === "eq" && attrDef && attrDef.type === "boolean") {
+      return '<select class="oor-segment-val oor-form-control" style="flex:1;">' +
+        '<option value="true"' + (value === "true" ? " selected" : "") + '>' + (placeholders.boolean_true || "true") + '</option>' +
+        '<option value="false"' + (value !== "true" ? " selected" : "") + '>' + (placeholders.boolean_false || "false") + '</option>' +
+        '</select>';
+    }
+    if ((operator === "eq" || operator === "not_eq") && attrDef && attrDef.values && attrDef.values.length > 0) {
+      var html = '<select class="oor-segment-val oor-form-control" style="flex:1;">';
+      for (var i = 0; i < attrDef.values.length; i++) {
+        var v = attrDef.values[i];
+        var sel = v === value ? " selected" : "";
+        html += '<option value="' + v + '"' + sel + '>' + v + '</option>';
+      }
+      html += '</select>';
+      return html;
+    }
+    var placeholder = placeholders.value || "value";
+    if (operator === "in" || operator === "not_in") placeholder = placeholders.in_values || "values separated by comma";
+    if (operator === "matches") placeholder = placeholders.regex || "regular expression";
+    var displayValue = Array.isArray(value) ? value.join(", ") : (value || "");
+    return '<input type="text" placeholder="' + placeholder + '" value="' + displayValue + '" class="oor-segment-val oor-form-control" style="flex:1;">';
+  }
+  function addConditionRow(condition) {
+    var attrKey = condition.attribute || (availableAttributes[0] ? availableAttributes[0].key : "");
+    var attrDef = findAttr(attrKey);
+    var type = attrDef ? attrDef.type : "string";
+    var operator = condition.operator || "eq";
+    var row = document.createElement("div");
+    row.className = "oor-segment-row";
+    row.innerHTML =
+      '<div style="display:flex;gap:8px;align-items:center;flex-wrap:wrap;">' +
+        '<select class="oor-segment-attr oor-form-control" style="flex:1;min-width:120px;">' + buildAttrSelect(attrKey) + '</select>' +
+        '<select class="oor-segment-op oor-form-control" style="flex:1;min-width:120px;">' + buildOpSelect(type, operator) + '</select>' +
+        buildValueInput(attrDef, operator, Array.isArray(condition.value) ? condition.value.join(", ") : (condition.value || "")) +
+        '<button type="button" class="oor-segment-remove oor-btn oor-btn--sm oor-btn--danger" style="flex-shrink:0;">&times;</button>' +
+      '</div>' +
+      (attrDef && attrDef.description ? '<div class="oor-segment-description">' + attrDef.description + '</div>' : '');
+    row.querySelector(".oor-segment-remove").addEventListener("click", function() {
+      row.remove();
+      serialize();
+    });
+    var attrSelect = row.querySelector(".oor-segment-attr");
+    attrSelect.addEventListener("change", function() {
+      var newAttrDef = findAttr(attrSelect.value);
+      var newType = newAttrDef ? newAttrDef.type : "string";
+      var opSelect = row.querySelector(".oor-segment-op");
+      opSelect.innerHTML = buildOpSelect(newType, "eq");
+      var oldValEl = row.querySelector(".oor-segment-val");
+      var temp = document.createElement("div");
+      temp.innerHTML = buildValueInput(newAttrDef, "eq", "");
+      oldValEl.parentNode.replaceChild(temp.firstChild, oldValEl);
+      var descEl = row.querySelector(".oor-segment-description");
+      if (descEl) descEl.remove();
+      if (newAttrDef && newAttrDef.description) {
+        var newDesc = document.createElement("div");
+        newDesc.className = "oor-segment-description";
+        newDesc.textContent = newAttrDef.description;
+        row.appendChild(newDesc);
+      }
+      bindRowEvents(row);
+      serialize();
+    });
+    var opSelect = row.querySelector(".oor-segment-op");
+    opSelect.addEventListener("change", function() {
+      var currentAttrDef = findAttr(attrSelect.value);
+      var oldValEl = row.querySelector(".oor-segment-val");
+      var temp = document.createElement("div");
+      temp.innerHTML = buildValueInput(currentAttrDef, opSelect.value, "");
+      oldValEl.parentNode.replaceChild(temp.firstChild, oldValEl);
+      bindRowEvents(row);
+      serialize();
+    });
+    bindRowEvents(row);
+    container.appendChild(row);
+    serialize();
+  }
+  function bindRowEvents(row) {
+    row.querySelectorAll(".oor-segment-val, .oor-segment-op, .oor-segment-attr").forEach(function(el) {
+      el.removeEventListener("change", serialize);
+      el.removeEventListener("input", serialize);
+      el.addEventListener("change", serialize);
+      el.addEventListener("input", serialize);
+    });
+  }
+  function loadExisting() {
+    var data;
+    try { data = JSON.parse(output.value || "{}"); } catch(e) { data = {}; }
+    if (data.conditions && data.conditions.length > 0) {
+      data.conditions.forEach(function(c) { addConditionRow(c); });
+    }
+    if (data.logic && logicSelect) logicSelect.value = data.logic;
+  }
+  if (addButton) {
+    addButton.addEventListener("click", function(e) {
+      e.preventDefault();
+      addConditionRow({ attribute: "", operator: "eq", value: "" });
+    });
+  }
+  if (logicSelect) {
+    logicSelect.addEventListener("change", serialize);
+  }
+  loadExisting();
+});
+// === Sortable Controller ===
+document.addEventListener("DOMContentLoaded", function() {
+  var wrapper = document.querySelector("[data-controller='sortable']");
+  if (!wrapper) return;
+  var sortableUrl = wrapper.getAttribute("data-sortable-url-value");
+  var draggedItem = null;
+  wrapper.querySelectorAll("[data-step-id]").forEach(function(item) {
+    item.draggable = true;
+    item.addEventListener("dragstart", function(e) {
+      draggedItem = e.currentTarget;
+      e.currentTarget.style.opacity = "0.4";
+      e.dataTransfer.effectAllowed = "move";
+    });
+    item.addEventListener("dragover", function(e) {
+      e.preventDefault();
+      e.dataTransfer.dropEffect = "move";
+      var target = e.currentTarget;
+      if (target !== draggedItem) {
+        var rect = target.getBoundingClientRect();
+        if (e.clientY < rect.top + rect.height / 2) {
+          target.parentNode.insertBefore(draggedItem, target);
+        } else {
+          target.parentNode.insertBefore(draggedItem, target.nextSibling);
+        }
+      }
+    });
+    item.addEventListener("drop", function(e) {
+      e.preventDefault();
+      saveOrder();
+    });
+    item.addEventListener("dragend", function(e) {
+      e.currentTarget.style.opacity = "1";
+      draggedItem = null;
+    });
+  });
+  function saveOrder() {
+    var items = wrapper.querySelectorAll("[data-step-id]");
+    var order = Array.from(items).map(function(item, i) {
+      return { id: item.dataset.stepId, position: i + 1 };
+    });
+    if (sortableUrl) {
+      var csrfToken = document.querySelector('meta[name="csrf-token"]');
+      fetch(sortableUrl, {
+        method: "PATCH",
+        headers: {
+          "Content-Type": "application/json",
+          "X-CSRF-Token": csrfToken ? csrfToken.content : ""
+        },
+        body: JSON.stringify({ order: order })
+      });
+    }
+  }
+});
+// === Selector Picker Controller ===
+// Register on window directly (not inside DOMContentLoaded) so it survives Turbo Drive navigations
+window.addEventListener("message", function(event) {
+  if (event.data && event.data.type === "oor-selector-picked") {
+    var input = document.querySelector("input[name='step[selector]']")
+              || document.getElementById("step_selector");
+    if (input) {
+      input.value = event.data.selector;
+      input.dispatchEvent(new Event("input"));
+      input.dispatchEvent(new Event("change"));
+    }
+  }
+});