ruby_cms 0.1.0

data/README.md

@@ -0,0 +1,235 @@
+# RubyCMS
+
+Reusable Rails engine: admin-only auth, permissions, admin shell, content blocks, and visual editor.
+
+**Vision:** The CMS manages content (content blocks, visual editor); the programmer builds the SaaS product (auth, billing, dashboards, etc.). You define pages and templates in your app; you edit content using the visual editor.
+
+## Features
+
+- **Visual Editor** - Inline editing of content blocks
+- **Content Blocks** - Reusable content snippets with rich text support
+- **Permissions** - Fine-grained permission system
+- **Users** - User management with permission assignments
+- **Visitor Error Tracking** - Automatic exception logging with admin interface
+- **Page View Tracking** - Ahoy-based analytics for page views and events
+
+## Documentation
+
+- **[Installation](#installation)** - Get started with RubyCMS
+- **[Usage](#usage)** - Basic usage examples
+
+## Installation {#installation}
+
+### 1. Create a Rails app (or use an existing one)
+
+```bash
+rails new my_cms_app -d sqlite3
+cd my_cms_app
+```
+
+### 2. Install RubyCMS
+
+```bash
+rails g ruby_cms:install
+```
+
+This generator:
+
+- configures RubyCMS (`config/initializers/ruby_cms.rb`) and mounts the engine,
+- ensures authentication is present (generates `User`, `Session`, and `Authentication` on Rails 8+ apps that need it),
+- installs Action Text / Active Storage when missing and runs the required `db:migrate`,
+- creates the RubyCMS tables and seeds permissions,
+- guides you through picking or creating the first admin user and granting CMS permissions.
+
+### 3. Resolve route conflicts
+
+If the app already has `/admin` routes, remove or change them so RubyCMS can use `/admin`. The install adds `mount RubyCms::Engine => "/"`; keep it after your main routes (e.g. `root`, `resources`) so it doesn’t override them.
+
+## Usage
+
+### Content blocks
+
+In any view:
+
+```erb
+<%= content_block("hero_title", default: "Welcome") %>
+<%= content_block("footer", cache: true) %>
+```
+
+**Important:** For **placeholders** (input `placeholder`, `alt`, meta tags), use `wrap: false` or `content_block_text`. The `content_block` helper normally wraps content in a `<span>` for the visual editor; that HTML must not go into placeholder attributes:
+
+```erb
+<%= text_field_tag :name, nil, placeholder: content_block("contact.name_placeholder", wrap: false, fallback: "Your name") %>
+<%= text_area_tag :message, nil, placeholder: content_block("contact.message_placeholder", wrap: false, fallback: "Your message...") %>
+```
+
+Or use `content_block_text` (equivalent to `content_block(..., wrap: false)`):
+
+```erb
+<%= text_field_tag :name, nil, placeholder: content_block_text("contact.name_placeholder", fallback: "Your name") %>
+```
+
+For **lists** (badges, tags) that you need to iterate over, use `content_block_list_items`—it returns an array instead of HTML:
+
+```erb
+<% content_block_list_items("education.item.badges", fallback: item[:badges]).each do |badge| %>
+  <%= tag.span badge, class: "badge" %>
+<% end %>
+```
+
+Store list content as JSON (`["Ruby", "Rails"]`) or newline-separated text in the CMS.
+
+Create and edit blocks under **Admin → Content blocks**.
+
+### Seeding content blocks from YAML
+
+1. In `config/initializers/ruby_cms.rb`, set the translation namespace (the install generator sets this by default):
+
+   ```ruby
+   c.content_blocks_translation_namespace = "content_blocks"
+   ```
+
+2. Add content under that key in your locale files (e.g. `config/locales/en.yml`):
+
+   ```yaml
+   en:
+     content_blocks:
+       hero_title: "Welcome to my site"
+       about_intro: "We build things."
+       footer_copyright: "© 2025"
+   ```
+
+3. Run the seed task to import into the database (creates/updates blocks, marks them published):
+
+   ```bash
+   rails ruby_cms:content_blocks:seed
+   ```
+
+   Or call it from `db/seeds.rb`:
+
+   ```ruby
+   Rake::Task["ruby_cms:content_blocks:seed"].invoke
+   ```
+
+   ENV overrides: `published=false` to import as unpublished; `create_missing=false` or `update_existing=false` to limit what is changed.
+
+### Visual editor
+
+1. **Preview templates** come from `config.ruby_cms.preview_templates` in `config/initializers/ruby_cms.rb`.
+
+   ```ruby
+   c.preview_templates = { "home" => "pages/home", "about" => "pages/about" }
+   c.preview_data = ->(page_key, view) { { products: Product.limit(5) } }
+   ```
+
+2. Create the view templates (e.g. `app/views/pages/home.html.erb`) and use the `content_block("key")` helper for editable regions. Wrap editable elements in `<div class="ruby_cms-content-block" data-content-key="...">`.
+
+3. Open **Admin → Visual editor**, pick a page, and click any content block in the preview to edit in the modal.
+
+4. **postMessage**: The preview iframe and parent communicate via postMessage for content block editing and updates.
+
+### Visitor Error Tracking
+
+RubyCMS automatically captures unhandled exceptions from public pages (non-admin) and logs them to the `ruby_cms_visitor_errors` table.
+
+**Note**: Error logging is disabled in development environment (errors are skipped and only re-raised for normal Rails error pages).
+
+#### How it works
+
+1. The install generator adds `RubyCms::VisitorErrorCapture` to your `ApplicationController` with `rescue_from StandardError`
+2. When an exception occurs in production/staging, it's logged with full context (backtrace, request params, IP, user agent, etc.)
+3. The exception is re-raised so users still see the standard error page
+4. Admin users can view and manage errors at `/admin/visitor_errors`
+
+#### What gets logged
+
+- Error class and message
+- Request path and method
+- IP address and user agent
+- Session ID
+- First 10 lines of backtrace
+- Sanitized request params (passwords/tokens excluded)
+
+#### Admin interface
+
+Visit `/admin/visitor_errors` to:
+
+- View all errors with filtering by path, error type, and resolved status
+- See full error details including backtrace and request context
+- Mark errors as resolved (single or bulk)
+- Delete errors (bulk action)
+
+### Page View Tracking (Ahoy)
+
+RubyCMS includes Ahoy for visit and event tracking. The install generator sets up Ahoy with server-side tracking (no JavaScript required).
+
+#### Tracking page views
+
+Include `RubyCms::PageTracking` in your public controllers to automatically track page views:
+
+```ruby
+class PagesController < ApplicationController
+  include RubyCms::PageTracking
+
+  def home
+    # @page_name is set to controller_name by default
+    # Override if needed: @page_name = "home"
+  end
+end
+```
+
+Page views are stored in `ahoy_events` with:
+
+- `name: "page_view"`
+- `page_name`: Controller-specific identifier
+- `request_path`: Full request path
+- `visit`: Associated Ahoy visit (includes IP, user agent, browser, etc.)
+
+#### What Ahoy tracks
+
+**Visits** (`ahoy_visits` table):
+
+- Visit token (unique per session)
+- IP address and user agent
+- Browser, OS, device type
+- Landing page and referrer
+- UTM parameters
+- User ID (when authenticated)
+
+**Events** (`ahoy_events` table):
+
+- Event name (e.g., "page_view")
+- Timestamp
+- Associated visit
+- Custom properties (page_name, request_path, etc.)
+- User ID (when authenticated)
+
+#### Accessing analytics data
+
+Query the Ahoy tables directly or use the Ahoy gem's built-in methods:
+
+```ruby
+# Get all page views
+Ahoy::Event.where(name: "page_view")
+
+# Page views for a specific page
+Ahoy::Event.where(name: "page_view", page_name: "home")
+
+# Unique visitors (visits)
+Ahoy::Visit.count
+
+# Page views by page
+Ahoy::Event.where(name: "page_view")
+          .group(:page_name)
+          .count
+```
+
+#### Architecture notes
+
+**Visitor Errors** and **Ahoy** are independent systems:
+
+- Visitor Errors log exceptions via `ApplicationController#rescue_from`
+- Ahoy tracks visits/events via Rack middleware and controller callbacks
+- No direct relationship between the two systems
+
+---

data/Rakefile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+# CSS compile (no Rails needed - for gem development)
+namespace :ruby_cms do
+  namespace :css do
+    desc "Compile RubyCMS admin.css from component files (for gem development)"
+    task compile_gem: :environment do
+      require_relative "lib/ruby_cms/css_compiler"
+      gem_root = __dir__
+      dest = File.join(gem_root, "app/assets/stylesheets/ruby_cms/admin.css")
+      RubyCms::CssCompiler.compile(gem_root, dest)
+      puts "✓ Compiled admin.css in gem"
+    end
+  end
+end
+
+task :environment do
+  # No-op for gem Rakefile; Rails app Rakefiles load full env
+end
+
+task default: %i[spec rubocop]

data/app/components/ruby_cms/admin/admin_page/admin_table_content.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RubyCms
+  module Admin
+    class AdminPage
+      # Optional wrapper for pages that want a consistent Turbo Frame target
+      # for table/content updates (pagination, filters, search, etc).
+      #
+      # Default ID matches RubyCMS convention: "admin_table_content".
+      class AdminTableContent < BaseComponent
+        def initialize(id: "admin_table_content", **attrs)
+          super()
+          @id = id
+          @attrs = attrs
+        end
+
+        def view_template(&)
+          turbo_frame_tag(@id, **default_attrs.merge(@attrs), &)
+        end
+
+        private
+
+        def default_attrs
+          {
+            class: "flex-1 flex flex-col min-h-0",
+            data: { turbo_action: "advance" }
+          }
+        end
+      end
+    end
+  end
+end

data/app/components/ruby_cms/admin/admin_page.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+module RubyCms
+  module Admin
+    # Admin page wrapper component (Tailwind-first)
+    #
+    # NOTE: This file must exist (at this path) so Zeitwerk autoloads
+    # `RubyCms::Admin::AdminPage` as a CLASS (not a module inferred from the
+    # `admin_page/` directory).
+    class AdminPage < BaseComponent
+      def initialize(title: nil, footer: nil, **options)
+        super()
+        @title = title
+        @footer = footer
+
+        assign_options(options)
+        @user_attrs = extract_user_attrs(options)
+      end
+
+      def extract_user_attrs(options)
+        excluded_keys = %i[
+          title subtitle actions action_icons search breadcrumbs padding overflow
+          content_card turbo_frame turbo_frame_options
+        ]
+        options.except(*excluded_keys)
+      end
+
+      def view_template(&)
+        content = build_page_content(&)
+        wrap_with_turbo_frame(content)
+      end
+
+      private
+
+      def build_page_content(&block)
+        lambda do
+          div(class: build_classes("flex flex-col gap-4", @user_attrs[:class]),
+              **@user_attrs.except(:class)) do
+            render_breadcrumbs if @breadcrumbs&.any?
+            render_header
+            render_content(&block)
+            render_footer if @footer.present?
+          end
+        end
+      end
+
+      def wrap_with_turbo_frame(content)
+        if @turbo_frame
+          turbo_frame_tag(@turbo_frame, **default_turbo_frame_options, &content)
+        else
+          content.call
+        end
+      end
+
+      def default_turbo_frame_options
+        { class: "flex-1 flex flex-col min-h-0", data: { turbo_action: "advance" } }
+          .merge(@turbo_frame_options || {})
+      end
+
+      def turbo_frame_tag(id, **attrs, &)
+        if respond_to?(:helpers) && helpers.respond_to?(:turbo_frame_tag)
+          helpers.turbo_frame_tag(id, **attrs, &)
+        elsif respond_to?(:turbo_frame_tag, true)
+          super
+        else
+          div(id: id, data: { turbo_frame: id, turbo_action: "advance" }, **attrs, &)
+        end
+      end
+
+      def render_breadcrumbs
+        nav(class: "text-sm text-gray-500", aria_label: "Breadcrumb") do
+          ol(class: "flex items-center flex-wrap gap-x-2 gap-y-1") do
+            @breadcrumbs.each_with_index do |crumb, index|
+              render_breadcrumb_item(crumb, index == @breadcrumbs.size - 1)
+            end
+          end
+        end
+      end
+
+      def render_breadcrumb_item(crumb, last)
+        li(class: "flex items-center") do
+          last ? render_breadcrumb_current(crumb) : render_breadcrumb_link(crumb)
+        end
+      end
+
+      def render_breadcrumb_current(crumb)
+        span(class: "font-medium text-gray-900", aria_current: "page") do
+          crumb[:label] || crumb[:text]
+        end
+      end
+
+      def render_breadcrumb_link(crumb)
+        a(href: crumb[:url] || crumb[:path], class: "hover:text-gray-700") do
+          span { crumb[:label] || crumb[:text] }
+          span(class: "px-2 text-gray-300") { "/" }
+        end
+      end
+
+      def render_header
+        return unless @title || @action_icons.any? || @actions.any? || @search
+
+        div(class: "flex flex-col gap-3") { render_header_rows }
+      end
+
+      def render_header_rows
+        div(class: "flex flex-wrap items-start justify-between gap-4") do
+          render_header_title_group
+          render_header_actions_icons
+        end
+
+        div(class: "flex flex-wrap items-center justify-between gap-3") do
+          render_search if @search
+          div(class: "flex items-center gap-2 flex-wrap") { render_header_action_buttons }
+        end
+      end
+
+      def render_header_title_group
+        return unless @title || @subtitle
+
+        div(class: "min-w-0") do
+          h1(class: "text-lg font-semibold text-gray-900 truncate") { @title } if @title
+          p(class: "text-sm text-gray-500 mt-0.5") { @subtitle } if @subtitle
+        end
+      end
+
+      def render_header_actions_icons
+        return unless @action_icons.any?
+
+        div(class: "flex items-center gap-2 flex-wrap") do
+          @action_icons.each {|icon_action| render_icon_action(icon_action) }
+        end
+      end
+
+      def render_header_action_buttons
+        @actions.each {|action| render_action_button(action) }
+      end
+
+      def render_icon_action(action)
+        if get_method?(action[:method])
+          render_icon_link(action)
+        else
+          render_icon_form(action)
+        end
+      end
+
+      def render_icon_link(action)
+        a(href: action_url(action), **icon_attrs(action)) { render_icon(action[:icon]) }
+      end
+
+      def render_icon_form(action)
+        form_with(url: action_url(action), method: action[:method],
+                  class: "inline") do
+          button(type: "submit", **icon_attrs(action)) { render_icon(action[:icon]) }
+        end
+      end
+
+      def icon_attrs(action)
+        attrs = base_icon_attrs(action)
+        data = action[:data]
+        attrs[:data] = data if data
+        attrs
+      end
+
+      def action_url(action)
+        action[:url] || action[:path] || "#"
+      end
+
+      def render_icon(icon)
+        case icon
+        when String then svg_icon_path(icon)
+        when Hash then svg_icon_hash(icon)
+        else sanitize(
+          icon.to_s,
+          tags: %w[svg path g circle rect line polygon polyline ellipse text],
+          attributes: %w[
+            fill stroke stroke-linecap stroke-linejoin stroke-width d
+            class viewBox cx cy r x y points x1 y1 x2 y2 aria-current id title aria-label
+          ]
+        )
+        end
+      end
+
+      def svg_icon_path(path)
+        svg(class: "w-5 h-5", fill: "none", stroke: "currentColor",
+            viewBox: "0 0 24 24") do |s|
+          s.path(stroke_linecap: "round", stroke_linejoin: "round", stroke_width: "2", d: path)
+        end
+      end
+
+      def svg_icon_hash(icon)
+        svg(class: "w-5 h-5",
+            fill: icon[:fill] || "none",
+            stroke: icon[:stroke] || "currentColor",
+            viewBox: icon[:viewBox] || "0 0 24 24") do |s|
+          Array(icon[:paths] || icon[:path]).compact.each {|p| s.path(**p) }
+        end
+      end
+
+      def render_action_button(action)
+        if action[:html].present?
+          render_safe_html_action(action)
+        else
+          render_standard_action(action)
+        end
+      end
+
+      def render_safe_html_action(action)
+        content = action[:html].to_s
+        sanitize(content)
+      end
+
+      def render_standard_action(action)
+        label = action[:label] || action[:text] || action[:name]&.humanize || "Action"
+        render_action_element(action_url(action), action[:method] || :get,
+                              build_action_attributes(action), label)
+      end
+
+      def build_action_attributes(action)
+        base = "inline-flex items-center justify-center rounded-lg px-3 py-2 " \
+               "text-sm font-medium transition"
+        secondary = "bg-white text-gray-700 ring-1 ring-gray-200 hover:bg-gray-50"
+        variant = action_primary?(action) ? primary_action_classes : secondary
+        attrs = { class: build_classes(base, variant, action[:class]) }
+        attrs[:data] = action[:data] if action[:data]
+        attrs
+      end
+
+      def action_primary?(action)
+        action[:primary] != false && action[:style] != "secondary"
+      end
+
+      def action_secondary?(action)
+        action[:style] == "secondary" || action[:primary] == false
+      end
+
+      def render_action_element(url, method, attrs, label)
+        if get_method?(method)
+          a(href: url, **attrs) { label }
+        else
+          render_form_action(url, method, attrs, label)
+        end
+      end
+
+      def render_form_action(url, method, attrs, label)
+        form_with(url: url, method: method, class: "inline") do
+          button(type: "submit", **attrs) { label }
+        end
+      end
+
+      def render_content(&)
+        div(class: "flex-1 flex flex-col min-h-0") do
+          if @content_card
+            div(
+              class: "bg-white rounded-lg border border-gray-200/80 shadow-sm " \
+                     "p-5 sm:p-6 flex-1 flex flex-col min-h-0"
+            ) { yield if block_given? }
+          elsif block_given?
+            yield
+          end
+        end
+      end
+
+      def render_footer
+        div(class: "mt-4") do
+          case @footer
+          when Proc
+            instance_exec(&@footer)
+          else
+            plain @footer
+          end
+        end
+      end
+
+      def render_search
+        opts = @search.kind_of?(Hash) ? @search : { placeholder: "Search" }
+        form_with(url: opts[:url] || "#", method: :get, class: "w-full sm:w-auto",
+                  data: { turbo_frame: opts[:turbo_frame] || "admin_table_content" }) do
+          div(class: "relative flex items-center") do
+            span(class: "absolute left-3 text-gray-400 pointer-events-none") do
+              svg_icon_path("M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z")
+            end
+            input(
+              type: "search",
+              name: opts[:name] || "q",
+              placeholder: opts[:placeholder] || "Search",
+              class: "w-full sm:w-72 pl-10 pr-3 py-2 text-sm rounded-lg bg-white ring-1 " \
+                     "ring-gray-200 focus:outline-none focus:ring-2 focus:ring-teal-200",
+              value: opts[:value],
+              data: { action: "input->turbo-frame#submit" }
+            )
+          end
+        end
+      end
+
+      def get_method?(method)
+        [:get, "get"].include?(method)
+      end
+
+      def assign_options(options)
+        @subtitle = options[:subtitle]
+        @actions = options[:actions] || []
+        @action_icons = options[:action_icons] || []
+        @search = options[:search]
+        @breadcrumbs = options[:breadcrumbs]
+        @padding = options.fetch(:padding, false)
+        @overflow = options.fetch(:overflow, true)
+        @content_card = options.fetch(:content_card, true)
+        @turbo_frame = options[:turbo_frame]
+        @turbo_frame_options = options[:turbo_frame_options]
+      end
+
+      def base_icon_attrs(action)
+        label = action[:title] || action[:label] || ""
+        {
+          class: build_classes(icon_base_classes, icon_color_classes(action[:color])),
+          title: label,
+          aria_label: label
+        }
+      end
+
+      def icon_color_classes(color)
+        icon_color_class_map.fetch((color || "blue").to_s, icon_color_class_map["blue"])
+      end
+
+      def icon_color_class_map
+        {
+          "blue" => "text-blue-600 hover:bg-blue-50",
+          "green" => "text-green-600 hover:bg-green-50",
+          "red" => "text-red-600 hover:bg-red-50",
+          "purple" => "text-purple-600 hover:bg-purple-50",
+          "gray" => "text-gray-700 hover:bg-gray-50",
+          "teal" => "text-teal-600 hover:bg-teal-50"
+        }
+      end
+
+      def icon_base_classes
+        "inline-flex items-center justify-center w-9 h-9 rounded-lg"
+      end
+
+      def primary_action_classes
+        "bg-teal-600 text-white hover:bg-teal-700"
+      end
+    end
+  end
+end