ruby_cms 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f7daf58804d218f4b8e2e87841c9b8f66dbc78668b3b0819bb902cb82952c97
-  data.tar.gz: acb0830e517c078c8e5fe62eb1f148935adac513ba761f12d166e5c99d400622
+  metadata.gz: 2a8d714a6a977cef96bd1eb99a4efd56e66da9ea9aebf81f61e982731bed9bda
+  data.tar.gz: 2543ebcfcef9083b33a69f7346ba921c087691aa46d6e1f1b7490d57bf9edfc8
 SHA512:
-  metadata.gz: 6ddd67cc13c744e97c345185f68c3db4919f6115cb8440eeed9e17afb262bac749241282afec071e25e04429fdfd059ef9ac6113e1c47d0473b242aed397f3d3
-  data.tar.gz: c85d346d3b65f7ce7a51578b3d654ad1ca15c7e6f121dbc4387abd23f562b70bfb2255edaa06aa12b56f34ae02b985a92cd89d2ea1c578bc3005f6e0f64d2c01
+  metadata.gz: 8625f68d914febc4c00a551f6d48ac0dfa0305a79248ce6faabc95e1641bc8794fef469f4480bfdb3869966011e59977e6be9cc9fdf048e7f1a7d95c01eb7372
+  data.tar.gz: 81354dff69046ca0ea0d94dceccd4c682070b768ef6bbf640dc19d2478d7dfe8b3b78e8351fba8c19814781a489a22e2175352ebfd38bda01d1bf50b0cf4e22a

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.1.0.9] - 2026-04-02
+
+- Update add page generator, dashboard blocks and some ui tweaks.
+
 ## [0.1.0.9] - 2026-03-25
 
 - Update gems

data/README.md

@@ -1,141 +1,523 @@
 # RubyCMS
 
-![RubyCMS logo](docs/assets/ruby_cms_logo.png)
+Reusable Rails engine for a CMS-style admin: content blocks, visual editor, versioning, pluggable dashboard, permissions, analytics, and visitor error tracking.
 
-Reusable Rails engine for a CMS-style admin: permissions, admin UI shell, content blocks, and a visual editor.
-
-Vision: your app owns product features (pages, models, business logic); RubyCMS manages content workflows and admin screens.
+Your app owns product features (pages, models, business logic); RubyCMS manages content workflows and admin screens.
 
 ## Features
 
-* Visual editor (inline editing for `content_block` regions)
-* Content blocks (rich text + placeholders + list items)
-* Permissions and users (admin access control)
-* Visitor error tracking (`/admin/visitor_errors`)
-* Analytics via Ahoy (page views + events)
+- **Content blocks** -- rich text, plain text, images, links, and lists with locale support
+- **Content block versioning** -- automatic version history with rollback and side-by-side diffs
+- **Visual editor** -- inline editing on live page previews
+- **Pluggable dashboard** -- registry-based blocks with permission gating and host-app extensibility
+- **Permissions** -- key-based access control with templates and per-user assignment
+- **Admin page generator** -- one command to scaffold a new admin page with nav, permission, and route
+- **Named icon registry** -- 20+ Heroicons by name, no SVG copy-pasting
+- **Settings** -- DB-backed admin settings with categories and UI
+- **Analytics** -- Ahoy-powered visit/event tracking with dashboard drill-downs
+- **Visitor error tracking** -- automatic 404/500 capture with admin overview
 
 ## Quick Start
 
 ```bash
+# Add to Gemfile
+gem "ruby_cms"
+
+# Install
 rails g ruby_cms:install
+rails db:migrate
+rails ruby_cms:seed_permissions
+rails ruby_cms:setup_admin
 ```
 
-The generator sets up:
-
-* `config/initializers/ruby_cms.rb`
-* mounts the engine (`/admin/...` on the host app)
-* migrations + RubyCMS tables
-* seed permissions + initial admin setup
+The install generator sets up the initializer, mounts the engine at `/admin`, runs migrations, configures Tailwind, Stimulus, Action Text, and Ahoy.
 
-If your host app already has `/admin` routes, adjust/remove them so RubyCMS can use `/admin`.
+Visit `/admin` and sign in with the admin user you configured.
 
-## Using Content Blocks
+## Content Blocks
 
-In any view:
+Use the `content_block` helper in any view:
 
 ```erb
 <%= content_block("hero_title", default: "Welcome") %>
 <%= content_block("footer", cache: true) %>
 ```
 
-<details>
-<summary>Placeholders (attributes like `placeholder`, `alt`, meta tags)</summary>
+### Content Types
+
+| Type | Description |
+|------|-------------|
+| `text` | Plain text string |
+| `rich_text` | Action Text rich content (HTML) |
+| `image` | Attached image via Active Storage |
+| `link` | URL string |
+| `list` | JSON array or newline-separated items |
+
+### Placeholders and Attributes
 
-`content_block` wraps output for the visual editor, so do not put it inside HTML attributes.
-Use `wrap: false` (or `content_block_text`):
+`content_block` wraps output for the visual editor. For HTML attributes, use `wrap: false`:
 
 ```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_text("contact.message_placeholder", fallback: "Your message...") %>
+  placeholder: content_block("contact.placeholder", wrap: false, fallback: "Your name") %>
 ```
 
-</details>
+Or use `content_block_text` which never wraps:
 
-<details>
-<summary>List items (badges, tags, arrays)</summary>
+```erb
+<meta name="description" content="<%= content_block_text("meta_desc", fallback: "Default") %>">
+```
 
-Use `content_block_list_items` to get an Array:
+### List Items
 
 ```erb
-<% content_block_list_items("education.item.badges", fallback: item[:badges]).each do |badge| %>
+<% content_block_list_items("badges", fallback: ["Ruby", "Rails"]).each do |badge| %>
   <%= tag.span badge, class: "badge" %>
 <% end %>
 ```
 
-Store list content as JSON (`["Ruby", "Rails"]`) or newline-separated text in the CMS.
+### Multi-locale Support
 
-</details>
+Content blocks have a `locale` field. The CMS groups blocks by key prefix across locales for easy management.
 
-Create/edit blocks in **Admin -> Content blocks**.
+## Content Block Versioning
+
+Versions are created automatically on every meaningful change:
+
+```ruby
+block = ContentBlock.create!(key: "hero", title: "Welcome", content: "Hello",
+                              content_type: "text", locale: "en")
+block.versions.count  # => 1 (event: "create")
+
+block.update!(title: "Welcome!")
+block.versions.count  # => 2 (event: "update")
+
+block.update!(published: false)
+block.versions.last.event  # => "unpublish"
+```
+
+### Events
+
+| Event | When |
+|-------|------|
+| `create` | Block is first created |
+| `update` | Title, content, or content_type changes |
+| `publish` | `published` changes to `true` |
+| `unpublish` | `published` changes to `false` |
+| `rollback` | `rollback_to_version!` is called |
+| `visual_editor` | Edit via the visual editor |
+
+### Rollback
+
+```ruby
+old_version = block.versions.first
+block.rollback_to_version!(old_version, user: current_user)
+# Creates a new version with event: "rollback"
+# Restores title, content, content_type, published, and rich_content
+```
+
+### Admin UI
+
+- **Version history** link on each content block show page
+- **Timeline view** with colored event badges
+- **Side-by-side diff** (old vs new, red/green)
+- **Rollback button** with confirmation
+
+### Routes
+
+```
+GET  /admin/content_blocks/:id/versions        # index (HTML + JSON)
+GET  /admin/content_blocks/:id/versions/:vid    # show with diff
+POST /admin/content_blocks/:id/versions/:vid/rollback
+```
 
 ## Visual Editor
 
-Configure preview templates + (optional) preview data in `config/initializers/ruby_cms.rb`:
+Configure 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) } }
+RubyCms.configure do |c|
+  c.preview_templates = { "home" => "pages/home", "about" => "pages/about" }
+  c.preview_data = ->(page_key, view) { { products: Product.limit(5) } }
+end
 ```
 
-Then open **Admin -> Visual editor**, pick a page key, and click content blocks in the preview.
+Open **Admin > Visual editor**, pick a page, and click content blocks to edit them inline.
 
-## Admin UI Pages (custom admin templates)
+## Dashboard
 
-RubyCMS exposes an `admin_page` helper:
+The dashboard uses a registry-based block system. Each block is a partial with optional permission gating and data injection.
 
-```erb
-<%= admin_page(title: "My Page", subtitle: "Optional") do %>
-  <p>Hello from RubyCMS admin.</p>
-<% end %>
+### Default Blocks
+
+| Block | Section | Permission |
+|-------|---------|------------|
+| Content blocks stats | stats | `manage_content_blocks` |
+| Users stats | stats | `manage_permissions` |
+| Permissions stats | stats | `manage_permissions` |
+| Visitor errors stats | stats | `manage_visitor_errors` |
+| Quick actions | main | -- |
+| Recent errors | main | `manage_visitor_errors` |
+| Analytics overview | main | `manage_analytics` |
+
+### Adding Custom Blocks
+
+```ruby
+# config/initializers/ruby_cms.rb (or ruby_cms_pages.rb)
+Rails.application.config.to_prepare do
+  RubyCms.dashboard_register(
+    key: :orders_stats,
+    label: "Orders",
+    section: :stats,          # :stats (top row) or :main (bottom grid)
+    order: 5,
+    partial: "admin/dashboard/orders_stats",
+    permission: :manage_orders,
+    span: :single,            # :single or :double (grid width)
+    data: ->(controller) {
+      { count: Order.count, today: Order.where("created_at > ?", Date.today).count }
+    }
+  )
+end
+```
+
+Then create the partial `app/views/admin/dashboard/_orders_stats.html.erb`. The `block` local contains the registration data and any computed `data`.
+
+### Overriding Default Blocks
+
+Re-register with the same key to override:
+
+```ruby
+RubyCms.dashboard_register(
+  key: :quick_actions,
+  label: "Quick actions",
+  section: :main,
+  partial: "admin/dashboard/my_quick_actions"  # your own partial
+)
+```
+
+## Navigation and Permissions
+
+### register_page (recommended)
+
+One call to register a nav item and its permission:
+
+```ruby
+RubyCms.register_page(
+  key: :backups,
+  label: "Backups",
+  path: :admin_backups_path,        # Symbol: auto-wrapped via main_app
+  icon: :archive_box,               # Named icon from RubyCms::Icons
+  section: :main,                   # :main (sidebar top) or :settings (sidebar bottom)
+  permission: :manage_backups,      # Auto-registered as permission key
+  order: 10
+)
+```
+
+### nav_register (low-level)
+
+For more control (custom visibility gates, non-standard paths):
+
+```ruby
+RubyCms.nav_register(
+  key: :reports,
+  label: "Reports",
+  path: ->(view) { view.main_app.reports_path },
+  icon: :chart_bar,
+  section: "main",
+  permission: :manage_reports,
+  if: ->(view) { view.current_user_cms&.admin? }
+)
+```
+
+### Path Options
+
+| Format | Example | Behavior |
+|--------|---------|----------|
+| Symbol | `:admin_backups_path` | Auto-wrapped: `view.main_app.send(:admin_backups_path)` |
+| Lambda | `-> (v) { v.some_path }` | Called with view context |
+| String | `"/admin/backups"` | Used as-is |
+
+### Named Icons
+
+Use symbol keys from `RubyCms::Icons`:
+
+```ruby
+RubyCms::Icons.available
+# => [:home, :pencil_square, :document_duplicate, :chart_bar, :shield_check,
+#     :exclamation_triangle, :user_group, :cog_6_tooth, :archive_box, :folder,
+#     :bell, :clock, :tag, :cube, :envelope, :wrench, :globe, :photograph,
+#     :list_bullet, :plus_circle, :trash, :eye, :lock_closed, :currency_dollar]
+```
+
+Raw SVG strings are also accepted for custom icons.
+
+### Permission Keys
+
+Default keys: `manage_admin`, `manage_permissions`, `manage_content_blocks`, `manage_visitor_errors`, `manage_analytics`.
+
+Register additional keys:
+
+```ruby
+RubyCms.register_permission_keys(:manage_orders, :manage_reports)
+```
+
+### Permission Templates
+
+Group permission keys into reusable templates:
+
+```ruby
+RubyCms.register_permission_template(:editor,
+  label: "Editor",
+  keys: %w[manage_admin manage_content_blocks],
+  description: "Can manage content but not users"
+)
+
+# Apply to a user:
+RubyCms::Permission.apply_template!(user, :editor)
+```
+
+### cms_page Macro
+
+In controllers that inherit from `RubyCms::Admin::BaseController`, use `cms_page` to link to a registered page. The permission is looked up from the nav registry automatically:
+
+```ruby
+class Admin::BackupsController < RubyCms::Admin::BaseController
+  cms_page :backups  # permission from register_page(:backups, permission: :manage_backups)
+
+  def index
+    @backups = Backup.recent
+  end
+end
+```
+
+## Admin Page Generator
+
+Scaffold a complete admin page with one command:
+
+```bash
+rails g ruby_cms:admin_page backups
 ```
 
+This generates:
+
+| File | Description |
+|------|-------------|
+| `app/controllers/admin/backups_controller.rb` | Controller with `cms_page :backups` |
+| `app/views/admin/backups/index.html.erb` | View template |
+| `config/routes.rb` | Route injection (`namespace :admin`) |
+| `config/initializers/ruby_cms_pages.rb` | `register_page` call |
+
+### Options
+
+```bash
+rails g ruby_cms:admin_page backups \
+  --permission=manage_backups \
+  --icon=archive_box \
+  --section=settings \
+  --order=15
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--permission` | `manage_<name>` | Permission key |
+| `--icon` | `folder` | Icon from `RubyCms::Icons` |
+| `--section` | `main` | `main` or `settings` |
+| `--order` | `10` | Sort order in nav |
+
+After generating, run `rails ruby_cms:seed_permissions` to create the permission row in the database.
+
+## Settings
+
+RubyCMS uses DB-backed settings with a registry for defaults and types:
+
+```ruby
+# Read
+RubyCms::Settings.get(:analytics_default_period, default: "week")
+
+# Write (admin UI or programmatic)
+RubyCms::Settings.set(:analytics_default_period, "month")
+```
+
+### Registering Custom Settings
+
+```ruby
+RubyCms::SettingsRegistry.register(
+  key: :my_custom_setting,
+  type: :string,
+  default: "hello",
+  category: :general,
+  description: "A custom setting"
+)
+```
+
+Settings are managed in **Admin > Settings** with tabs per category.
+
 ## Visitor Error Tracking
 
-Public (non-admin) exceptions are captured and shown in **`/admin/visitor_errors`**.
+Public exceptions are automatically captured when `RubyCms::VisitorErrorCapture` is included in your `ApplicationController` (added by the install generator).
 
-In development, logging is typically disabled and exceptions are re-raised normally.
+View captured errors in **Admin > Visitor errors** with status codes, paths, timestamps, and resolution tracking.
 
-## Page View Tracking (Ahoy)
+## Analytics (Ahoy)
+
+RubyCMS integrates with Ahoy for server-side page view and event tracking.
 
 Include `RubyCms::PageTracking` in public controllers:
 
 ```ruby
 class PagesController < ApplicationController
   include RubyCms::PageTracking
+end
+```
 
-  def home
-    # @page_name can be set; defaults vary by controller
-  end
+View analytics in **Admin > Analytics** with:
+- Visit and event counts
+- Popular pages
+- Top visitors
+- Configurable date ranges and periods
+
+### Customization Hooks
+
+```ruby
+RubyCms.configure do |c|
+  c.analytics_visit_scope = ->(scope) { scope.where.not(ip: ["127.0.0.1"]) }
+  c.analytics_event_scope = ->(scope) { scope }
+  c.analytics_extra_cards = lambda { |start_date:, end_date:, period:, visits_scope:, events_scope:|
+    [{ title: "Custom KPI", value: visits_scope.count }]
+  }
 end
 ```
 
 ## Seeding Content Blocks from YAML
 
-If you want to import blocks from locales, set:
+Set the translation namespace:
 
 ```ruby
-c.content_blocks_translation_namespace = "content_blocks"
+RubyCms.configure do |c|
+  c.content_blocks_translation_namespace = "content_blocks"
+end
 ```
 
-Example `config/locales/en.yml`:
+Create locale files:
 
 ```yaml
+# config/locales/en.yml
 en:
   content_blocks:
     hero_title: "Welcome to my site"
+    footer_text: "Copyright 2026"
 ```
 
 Import:
 
 ```bash
-rails ruby_cms:content_blocks:seed
+rails ruby_cms:content_blocks:import
+```
+
+Export DB content blocks back to YAML:
+
+```bash
+rails ruby_cms:content_blocks:export
 ```
 
-## Common Rake Tasks
+## Configuration
+
+All configuration happens in `config/initializers/ruby_cms.rb`:
+
+```ruby
+RubyCms.configure do |c|
+  # Base controller (must provide current_user + authentication)
+  c.admin_base_controller = "ApplicationController"
+
+  # Admin layout
+  c.admin_layout = "admin/admin"
+
+  # User model class name
+  c.user_class_name = "User"
+
+  # Allow user.admin? bypass when no Permission records exist
+  c.bootstrap_admin_with_role = true
+
+  # Redirect path for unauthenticated/unauthorized users
+  c.unauthorized_redirect_path = "/"
+
+  # Visual editor
+  c.preview_templates = { "home" => "pages/home" }
+  c.preview_data = ->(page_key, view) { {} }
+
+  # Content blocks
+  c.content_blocks_translation_namespace = "content_blocks"
+  c.image_content_types = %w[image/png image/jpeg image/gif image/webp]
+  c.image_max_size = 5 * 1024 * 1024
+end
+```
+
+## Rake Tasks
+
+| Task | Description |
+|------|-------------|
+| `ruby_cms:seed_permissions` | Create default permission rows + settings |
+| `ruby_cms:setup_admin` | Interactive first admin user setup |
+| `ruby_cms:grant_manage_admin` | Grant all permissions to a user by email |
+| `ruby_cms:content_blocks:export` | Export DB content blocks to YAML |
+| `ruby_cms:content_blocks:import` | Import content blocks from YAML |
+| `ruby_cms:content_blocks:sync` | Export + optional import |
+| `ruby_cms:import_initializer_settings` | Import initializer values into DB settings |
+| `ruby_cms:css:compile` | Compile admin CSS to host app |
+| `ruby_cms:css:compile_gem` | Compile admin CSS within the gem |
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/jobhammer00/ruby_cms.git
+cd ruby_cms
+bundle install
+```
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+Tests use an in-memory SQLite database via `spec/support/dummy_app.rb`. No separate dummy Rails app directory is needed.
+
+### CSS Compilation
+
+```bash
+rails ruby_cms:css:compile_gem
+```
+
+### Architecture
+
+```
+lib/ruby_cms.rb              # Module: nav_register, register_page, permissions API
+lib/ruby_cms/engine.rb        # Rails::Engine: config, initializers, rake tasks, nav registration
+lib/ruby_cms/icons.rb         # Named Heroicon SVG registry
+lib/ruby_cms/dashboard_blocks.rb  # Dashboard block registry
+lib/ruby_cms/settings.rb      # DB-backed settings
+lib/ruby_cms/settings_registry.rb  # Settings definitions and defaults
+app/controllers/ruby_cms/admin/  # Admin controllers (base, dashboard, content blocks, etc.)
+app/models/                   # ContentBlock, ContentBlockVersion, Permission, etc.
+app/views/ruby_cms/admin/     # Admin views
+app/views/layouts/ruby_cms/   # Admin layout + sidebar
+app/components/               # ViewComponents (AdminPage, etc.)
+app/helpers/                  # Content block, settings, dashboard helpers
+```
+
+### Key Extension Points
+
+| What | How |
+|------|-----|
+| New admin page | `rails g ruby_cms:admin_page <name>` |
+| New nav item | `RubyCms.register_page(...)` or `RubyCms.nav_register(...)` |
+| New permission | `RubyCms.register_permission_keys(:key)` |
+| New dashboard block | `RubyCms.dashboard_register(...)` |
+| New setting | `RubyCms::SettingsRegistry.register(...)` |
+| New icon | Pass raw SVG string to `icon:` parameter |
+
+## License
 
-* `rails ruby_cms:seed_permissions`
-* `rails ruby_cms:setup_admin`
-* `rails ruby_cms:content_blocks:seed`
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/ruby_cms/admin/base_controller.rb

@@ -20,8 +20,39 @@ module RubyCms
       # new_session_path, root_path, etc.
       include RubyCms::Engine.routes.url_helpers
 
+      # Declare which registered page this controller serves.
+      # Looks up the permission from the nav_registry entry and sets a before_action.
+      # Usage: cms_page :backups (requires a matching register_page call with key: :backups)
+      def self.cms_page(key)
+        page_key = key.to_sym
+        before_action do
+          entry = RubyCms.nav_registry.find {|e| e[:key] == page_key }
+          if entry.nil?
+            if defined?(Rails.logger)
+              Rails.logger.warn("[RubyCMS] cms_page :#{page_key} has no matching register_page entry. " \
+                                "Only manage_admin is enforced.")
+            end
+          elsif entry[:permission].present?
+            require_permission!(entry[:permission].to_sym)
+          end
+        end
+      end
+
+      # Public API: dashboard block +data procs and host code may call this on the controller instance.
+      def current_user_cms
+        @current_user_cms ||= resolve_current_user
+      end
+
       private
 
+      def resolve_current_user
+        if respond_to?(:current_user, true)
+          send(:current_user)
+        else
+          Rails.application.config.ruby_cms.current_user_resolver&.call(self)
+        end
+      end
+
       def require_cms_access
         ensure_authenticated
         require_permission!(:manage_admin)
@@ -67,18 +98,6 @@ module RubyCms
         Rails.application.config.ruby_cms.unauthorized_redirect_path.presence || "/"
       end
 
-      def current_user_cms
-        @current_user_cms ||= resolve_current_user
-      end
-
-      def resolve_current_user
-        if respond_to?(:current_user, true)
-          send(:current_user)
-        else
-          Rails.application.config.ruby_cms.current_user_resolver&.call(self)
-        end
-      end
-
       def render_not_found
         render "ruby_cms/errors/not_found",
                status: :not_found,
@@ -106,6 +125,8 @@ module RubyCms
       def model_param_key(model_class, param_name)
         params.key?(param_name) ? param_name : model_class.model_name.param_key.to_sym
       end
+
+      public :current_user_cms
     end
   end
 end