tsykvas_rails_template 0.1.0

data/lib/generators/tsykvas_rails_template/install/templates/.claude/docs/ui-components.md

@@ -0,0 +1,196 @@
+# UI Components
+
+For visual tokens (palette, typography, geometry, motion) see [`design-system.md`](design-system.md). This page documents the component APIs that ship with the template.
+
+## Buttons — always use `Base::Component::Btn`
+
+```ruby
+render ::Base::Component::Btn.new(type: 'add',    text: t('admin.users.new'),    path: new_admin_user_path)
+render ::Base::Component::Btn.new(type: 'save',   text: t('forms.save'),         submit: true)
+render ::Base::Component::Btn.new(type: 'remove', text: t('admin.users.delete'), modal_target: "delete_modal_#{user.id}")
+```
+
+Valid types: `add`, `cancel`, `check`, `edit`, `next`, `save`, `search`, `show`, `remove` (constants in `Base::Component::Btn::VALID_TYPES`). Each maps to a Bootstrap Icon and a CSS variant:
+
+| `type` | Variant | Use |
+|---|---|---|
+| `add`, `save`, `next`, `search`, `cancel` | `.btn-primary` | Primary action |
+| `show`, `edit` | `.btn-outline-secondary` | Secondary / informational action |
+| `check` | `.btn-outline-success` | Confirm / positive action |
+| `remove` | `.btn-danger` | Destructive action only |
+
+Sizes: `XS`, `SM` / `S` (default), `M`, `L`. Use `S` for table action buttons and `L` for full-width form submits / page-header CTAs.
+
+Other parameters: `disabled:` (Boolean), `path:` (renders `<a>`), `submit:` (renders `<button type="submit">`), `method:` (HTTP method), `data:` (hash of data attributes), `target: '_blank'`, `prefetch:` (Turbo prefetch override), `formaction:`, `modal_target:` (Bootstrap modal id without `#`).
+
+When you need multiple buttons in a single table cell, wrap them in a flex container:
+
+```ruby
+safe_join([
+  render(::Base::Component::Btn.new(type: 'show', text: t('view'), path: admin_user_path(user))),
+  render(::Base::Component::Btn.new(type: 'remove', text: t('delete'), path: admin_user_path(user), method: :delete))
+])
+```
+
+See [`design-system.md`](design-system.md#buttons) for the full variant catalog (including manual classes like `.btn-secondary`, `.btn-outline-light`, `.btn-ghost` not surfaced via `Btn`).
+
+---
+
+## Tables — always use `Base::Component::Table::Table`
+
+Extract the table itself into a dedicated ViewComponent (e.g. `Admin::User::Component::UsersTable`). Inside, build the table imperatively:
+
+```ruby
+def call
+  table = Base::Component::Table::Table.new(rows: @users)
+
+  table.add_column(
+    header: I18n.t('admin.users.index.table.id'),
+    sort_field: :id,
+    sort_path: @sorting_path,
+    sort_data_type: 'number'
+  ) { |user| user.id.to_s }
+
+  table.add_column(
+    header: I18n.t('admin.users.index.table.role'),
+    sort_field: :role,
+    sort_path: @sorting_path,
+    sort_data_type: 'string',
+    stack: { to: :mobile, prefix: :header, smaller_than: :lg },
+    hide:  { smaller_than: :md }
+  ) { |user| role_badge(user.role) }
+
+  table.add_column(header: I18n.t('admin.users.index.table.actions'), type: :button) do |user|
+    action_buttons(user)
+  end
+
+  render table
+end
+```
+
+Column options: `header:`, `align:`, `type:` (`:regular` or `:button`), `stack:` (collapse columns on small screens — `{ to:, prefix:, smaller_than: }`), `hide:` (`{ smaller_than: }`), `sort_field:`, `sort_path:`, `sort_data_type:` (`'number'` / `'string'`), and a `&block` returning the cell content.
+
+Sortable columns require a `sort_path` matching the controller's index path; the operation must use `Base::Operation::Sortable#apply_sorting` with the same allowlist.
+
+`Table#format_date(date)` is a helper that returns a locale-formatted date string (configured in `config/locales/<locale>.yml` under `date.formats.default`).
+
+Action buttons inside cells use `.table-action-btn` (square hairline 32px) — see [`design-system.md`](design-system.md#tables).
+
+---
+
+## Title row — `Base::Component::TitleRow`
+
+```ruby
+render ::Base::Component::TitleRow.new(
+  title: I18n.t('admin.users.index.title'),
+  back_path: admin_root_path,
+  back_text: I18n.t('common.back'),
+  divider: true
+)
+```
+
+Renders a header with optional back-link and `<hr>` divider. Configure via `Base::Component::TitleRowConfig` if you need to share configuration across pages. The `<h1>` it renders inherits typography from your design-system stylesheet.
+
+---
+
+## Stat cards (dashboard tiles)
+
+Replacement for the colored Bootstrap `.card.bg-primary/.bg-success/.bg-warning` tiles. Two visual variants — both use neutral surfaces and rely on type/spacing for hierarchy rather than colour.
+
+```slim
+.stat-card.stat-card--emphasis
+  span.stat-card-label = I18n.t('admin.dashboard.users.title')
+  span.stat-card-figure = users_count
+  p.stat-card-description = I18n.t('admin.dashboard.users.description')
+
+.stat-card
+  span.stat-card-label = I18n.t('admin.dashboard.properties.title')
+  span.stat-card-figure = properties_count
+  p.stat-card-description = I18n.t('admin.dashboard.properties.description')
+```
+
+- **`.stat-card--emphasis`** — primary-coloured surface, inverse text. Use for ONE primary metric per dashboard.
+- **`.stat-card`** — neutral hairline-bordered card. Use for everything else.
+
+Structure parts:
+- `.stat-card-label` — uppercase small label.
+- `.stat-card-figure` — large display number.
+- `.stat-card-description` — small body line.
+
+Lay them out inside `.row.g-4` with `.col-md-4` (Bootstrap grid). Don't put more than ~3 in a row.
+
+---
+
+## Forms
+
+ViewComponent does not auto-mix Rails form helpers. Inside Slim templates of components, call `simple_form_for` via `helpers.`:
+
+```slim
+= helpers.simple_form_for @property, url: crm_edit_property_path, method: :patch do |f|
+  = f.input :name, label: t('crm.property.edit.name'), placeholder: t('crm.property.edit.name_placeholder')
+  = render ::Base::Component::Btn.new(type: 'save', text: t('crm.property.edit.submit'), submit: true)
+```
+
+For new/edit pages, follow the **Form / New / Edit** triad:
+
+- `form.rb` + `form.html.slim` — shared form fields
+- `new.rb` — subclass that sets title/breadcrumbs, embeds `Form`
+- `edit.rb` — same, for edit
+
+Two visual variants:
+
+| Class | Use |
+|---|---|
+| `.form-control` | Standard forms (CRM, admin) — boxed input, hairline border, primary focus halo |
+| `.form-control--underline` | Auth pages — no box, just bottom hairline that thickens on focus |
+
+`auth.scss` automatically applies underline-style inputs to anything inside `.auth-form`. For non-auth forms use the standard `.form-control`.
+
+See [`forms.md`](forms.md) for the full form pattern.
+
+---
+
+## Section / overline text
+
+Utility classes for small uppercase labels (used as section titles, stat-card labels):
+
+```slim
+span.section-label = I18n.t('ui.sections.workspace')
+```
+
+Pair with a display heading below for editorial dashboard headers:
+
+```slim
+.dashboard-header
+  span.section-label = I18n.t('ui.sections.administration')
+  h1.mb-0.mt-2 = I18n.t('admin.navbar.dashboard')
+  hr.divider
+```
+
+Define `.section-label` as a small uppercase tracked label in your design system; `.divider` as a hairline border divider.
+
+---
+
+## Layouts
+
+Three top-level layouts under `app/views/layouts/` (one per top-level concept namespace):
+
+- `admin.slim` — used by `Admin::BaseController` (renders the admin sidebar)
+- `crm.slim` — used by CRM controllers
+- `public.slim` — public-facing layout for unauthenticated visitors
+- `application.html.erb` — default Devise wrapper (sign-in / sign-up)
+
+All layouts load the same stylesheet entry (`application.bootstrap.scss` by default — see `design-system.md`).
+
+`Shared::Sidebar::*` and `Shared::Navbar::*` live under `app/concepts/shared/`.
+
+---
+
+## Other base components
+
+- `Base::Component::Btn` / `Base::Component::BtnConfig` — buttons (above)
+- `Base::Component::Table::Table` / `TableRow` — tables (above)
+- `Base::Component::TitleRow` / `TitleRowConfig` — page headers (above)
+- `Base::Component::InformationCard` (`+ InformationCardConfig`) — detail card on user-show / property-show pages. Header strip + hairline divider + monogram tile (square, no rounded avatar).
+- `Shared::Navbar::Component::*` — top navigation per domain
+- `Shared::Sidebar::Component::*` — sidebar per domain

data/lib/generators/tsykvas_rails_template/install/templates/CLAUDE.md.tt

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+> **Keep this file ≤ 100 lines.** Loaded into every Claude session — brevity = token economy. Push detail into `.claude/docs/` and link from the routing table below. Content between `<!-- tsykvas-template:start ... -->` markers is gem-owned; `/tsykvas-claude` rewrites only inside the fences.
+
+<!-- tsykvas-template:start v=0.1.0 section=routing -->
+## Read these first
+
+For anything beyond a one-line edit, read the relevant docs in `.claude/docs/` — they hold the architecture, conventions, and review checklists. After install only `tsykvas_rails_template.md`, `forms.md`, and `companions.md` exist; the rest are generated by `/tsykvas-claude` from probe data.
+
+| Topic | File |
+|---|---|
+| **Big-picture: how the gem works** | [.claude/docs/tsykvas_rails_template.md](.claude/docs/tsykvas_rails_template.md) |
+| **Architecture** — Concepts Pattern, `endpoint`, `Base::Operation::Base`, sub-operations, Pundit | [.claude/docs/architecture.md](.claude/docs/architecture.md) |
+| **Concepts walkthrough** — operations, components, refactor checklist | [.claude/docs/concepts-refactoring.md](.claude/docs/concepts-refactoring.md) |
+| **Routing & namespaces** — domain setup, base controllers, redirect dispatch | [.claude/docs/routing-and-namespaces.md](.claude/docs/routing-and-namespaces.md) |
+| **Authentication** — Devise sign-up, custom controllers, permitted params | [.claude/docs/authentication.md](.claude/docs/authentication.md) |
+| **Design system** — colour tokens, typography, component catalog | [.claude/docs/design-system.md](.claude/docs/design-system.md) |
+| **UI components** — `Base::Component::Btn`, table, title row, layouts | [.claude/docs/ui-components.md](.claude/docs/ui-components.md) |
+| **Forms** — `simple_form_for`, Form/New/Edit triad, when to promote `<Concept>::Form` | [.claude/docs/forms.md](.claude/docs/forms.md) |
+| **Stimulus controllers** — naming, `disconnect()` cleanup, Turbo events | [.claude/docs/stimulus-controllers.md](.claude/docs/stimulus-controllers.md) |
+| **I18n** — full-key rule, locale parity, simple_form labels, time zone | [.claude/docs/i18n.md](.claude/docs/i18n.md) |
+| **Database & migrations** — multi-DB, enum patterns, schema, seeds | [.claude/docs/database.md](.claude/docs/database.md) |
+| **Background jobs** — SolidQueue placement, recurring, calling from operations | [.claude/docs/background-jobs.md](.claude/docs/background-jobs.md) |
+| **Code style + anti-patterns** — frozen_string_literal, full I18n keys, git workflow | [.claude/docs/code-style.md](.claude/docs/code-style.md) |
+| **Security** — Pundit enforcement, parameter filtering, CSP, Brakeman | [.claude/docs/security.md](.claude/docs/security.md) |
+| **Testing** — RSpec setup, factories, mocks | [.claude/docs/testing.md](.claude/docs/testing.md) |
+| **Testing examples** — operation / component / model / policy / controller | [.claude/docs/testing-examples.md](.claude/docs/testing-examples.md) |
+| **Commands** — dev, tests, lint, security, deploy | [.claude/docs/commands.md](.claude/docs/commands.md) |
+| **Deployment (Kamal)** — `config/deploy.yml`, secrets, hooks, scaling | [.claude/docs/deployment.md](.claude/docs/deployment.md) |
+| **Companion gems** (`:companions` generator) | [.claude/docs/companions.md](.claude/docs/companions.md) |
+| **Documentation standards** — when and how to add to `docs/` | [.claude/docs/documentation.md](.claude/docs/documentation.md) |
+<!-- tsykvas-template:end -->
+
+<!-- tsykvas-template:start v=0.1.0 section=tldr -->
+## TL;DR
+
+- **Stack**: Rails 8, Ruby 3.x, PostgreSQL, Slim + ViewComponent, Hotwire (Turbo + Stimulus), Devise + Pundit, simple_form, solid_queue/cache/cable, Kamal.
+- **Concepts Pattern**: every feature lives in `app/concepts/<namespace>/<feature>/{operation,component}/`. Controllers are one-liner `endpoint OperationClass, ComponentClass` calls.
+- **Operation contract** (`Base::Operation::Base`): override `perform!(params:, current_user:)`; set `self.model`, `self.redirect_path`, `notice(...)`; **always call** `authorize!` / `policy_scope` / `authorize_and_save!` / `skip_authorize` (enforced by `OperationsMethods#check_authorization_is_called`).
+- **Component contract** (`Base::Component::Base`): pure presentation, constructor kwargs use **specific data names** — `initialize(events:)`, never `initialize(model:)`. Pair each `.rb` with adjacent `.html.slim`.
+- **Forms**: keep `_params` inline for simple CRUD; promote to `<Concept>::Form` when the form has virtual attributes, pre-assignment cleanup, sub-operation calls, or aggregates multiple AR records.
+- **Quick commands**: `bin/dev`, `bundle exec rspec`, `bin/rubocop`, `bin/brakeman --no-pager`, `bin/rails zeitwerk:check`.
+<!-- tsykvas-template:end -->
+
+<!-- tsykvas-template:start v=0.1.0 section=tree -->
+## What lives where
+
+```
+app/
+├── concepts/                       # Feature code (operations + components + slim)
+│   ├── <namespace>/<feature>/      # e.g. crm/property/, admin/user/
+│   ├── shared/                     # Cross-domain UI (navbar, sidebar, etc.)
+│   └── base/                       # Base::Operation::Base, Base::Component::Base, Btn, Table, ...
+├── controllers/
+│   ├── application_controller.rb   # Pundit + OperationsMethods + redirect dispatch
+│   ├── concerns/operations_methods.rb  # The `endpoint` helper
+│   ├── home_controller.rb          # Landing page scaffolded by install
+│   └── <namespace>/base_controller.rb
+├── models/                         # AR models — validations + associations only
+├── policies/                       # Pundit; default-deny ApplicationPolicy
+├── jobs/                           # SolidQueue Active Jobs
+├── javascript/controllers/         # Stimulus
+├── views/layouts/                  # Per-domain layout files (admin / crm / ...)
+└── views/devise/                   # Devise overrides (when added)
+config/
+├── routes.rb                       # `root "home#index"` after install
+├── deploy.yml                      # Kamal
+├── queue.yml + recurring.yml       # SolidQueue
+├── cache.yml + cable.yml           # SolidCache + SolidCable
+└── locales/*.yml
+db/
+├── schema.rb                       # Primary
+└── {cache,queue,cable}_schema.rb   # Solid* secondary DBs
+spec/                               # Mirrors app/ structure
+.claude/{docs,commands,agents}/     # This guide + commands + subagents
+```
+<!-- tsykvas-template:end -->
+
+If you change anything under `app/concepts/base/`, `app/controllers/concerns/operations_methods.rb`, `app/controllers/application_controller.rb`, or any `app/policies/**/base_policy.rb`, run `/update-rules` so the docs above stay in sync.

data/lib/generators/tsykvas_rails_template/install/templates/app/concepts/base/component/base.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "view_component"
+
+class Base::Component::Base < ViewComponent::Base
+end

data/lib/generators/tsykvas_rails_template/install/templates/app/concepts/base/operation/base.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "pundit"
+
+class Base::Operation::Base
+  attr_accessor :result
+
+  def self.call(**args)
+    ops = new(**args).tap(&:call)
+    ops.result
+  end
+
+  def initialize(**attrs)
+    @attrs = attrs
+    @result = ::Base::Operation::Result.new
+  end
+
+  def call
+    perform!(**@attrs)
+    copy_errors_from_result_to_model
+    @result
+  rescue ActiveRecord::RecordInvalid => e
+    add_errors e.record&.errors
+    copy_errors_from_result_to_model
+    @result
+  end
+
+  private
+
+  def copy_errors_from_result_to_model
+    return if model.nil? || !model.respond_to?(:errors)
+
+    result.errors[:base].each do |message|
+      model.errors.add(:base, message) unless model.errors[:base].include?(message)
+    end
+  end
+
+  def notice(text, level: :notice)
+    @result[:notice] = {
+      text:,
+      level:
+    }
+  end
+
+  def redirect_path=(path)
+    @result[:redirect_path] = path
+  end
+
+  def redirect_path
+    @result[:redirect_path]
+  end
+
+  def model=(model)
+    @result[:model] = model
+  end
+
+  def model
+    @result[:model]
+  end
+
+  def add_error(key, message)
+    @result.errors.add :base, key, message:
+  end
+
+  def add_errors(from)
+    return if from.nil?
+
+    from.each do |error|
+      from[error.attribute].each do |error_msg|
+        @result.errors.add(error.attribute, error_msg)
+      end
+    end
+  end
+
+  def invalid!
+    @result.invalid!
+  end
+
+  ### Run sub operations ###
+
+  def run_operation(operation_class, parameters)
+    manually_handle_errors = parameters[:manually_handle_errors].present?
+    parameters.except!(:manually_handle_errors)
+    run_result = operation_class.new(**parameters).tap(&:call).result
+    result.sub_results << run_result
+    if !manually_handle_errors && run_result.present? && run_result.failure?
+      add_errors run_result.errors
+      raise ActiveRecord::RecordInvalid
+    end
+    run_result
+  end
+
+  ### Authorization methods ###
+
+  def authorize!(record, query, policy: Pundit.policy!(@attrs[:current_user], record), fail_message: nil)
+    if policy.public_send(query)
+      @result[:pundit] = true
+      return
+    end
+
+    raise Pundit::NotAuthorizedError, fail_message if fail_message.present?
+
+    raise Pundit::NotAuthorizedError, query:, record:, policy:
+  end
+
+  def policy_scope(scope)
+    @result[:pundit_scope] = true
+    Pundit.policy_scope!(@attrs[:current_user], scope)
+  end
+
+  def skip_authorize
+    @result[:pundit] = true
+  end
+
+  def skip_policy_scope
+    @result[:pundit_scope] = true
+  end
+
+  def authorize_and_save!(auth_method = nil)
+    auth_method ||= model.new_record? ? :create? : :update?
+    authorize! model, auth_method
+    model.save!
+  end
+end

data/lib/generators/tsykvas_rails_template/install/templates/app/concepts/base/operation/result.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class Base::Operation::Result
+  include ActiveModel::Validations
+
+  def initialize
+    @attrs = {}
+    @forced_invalid = false
+  end
+
+  delegate :[], :[]=, :fetch, to: :@attrs
+
+  def model
+    @attrs[:model]
+  end
+
+  def redirect_path
+    @attrs[:redirect_path]
+  end
+
+  def sub_results
+    @attrs[:sub_results] ||= []
+  end
+
+  def success?
+    return false unless !@forced_invalid && errors.empty?
+    return false unless model.nil? || !model.respond_to?(:errors) ? true : model.errors.empty?
+
+    sub_results.all?(&:success?)
+  end
+
+  def failure?
+    !success?
+  end
+
+  def invalid!
+    @forced_invalid = true
+  end
+
+  def error_message
+    errors[:base].join(" ")
+  end
+
+  def all_error_messages
+    errors.map(&:message)
+  end
+
+  # Translated message for use in flash notices and alerts.
+  def message
+    @attrs.dig(:notice, :text)
+  end
+
+  def message_level
+    @attrs.dig(:notice, :level)
+  end
+end

data/lib/generators/tsykvas_rails_template/install/templates/app/concepts/home/component/index.html.slim

@@ -0,0 +1,49 @@
+.container.py-5
+  .row.justify-content-center
+    .col-lg-8
+      .card.shadow-sm
+        .card-body.p-4
+          h1.card-title.h2.mb-3= message
+
+          .alert.alert-success.d-flex.align-items-center.mb-4 role="alert"
+            span.badge.bg-success.me-2 OK
+            span Bootstrap 5.3 is installed and configured (this card, the alert, the modal button — all Bootstrap).
+
+          h2.h5.text-muted Next steps
+
+          ul.list-group.list-group-flush.mb-4
+            li.list-group-item
+              | Run
+              =< " "
+              code bin/rails g tsykvas_rails_template:companions
+              =< " "
+              | to add the recommended dev/test gems.
+            li.list-group-item
+              | Run
+              =< " "
+              code bin/rails g tsykvas_rails_template:concept Foo
+              =< " "
+              | to scaffold a new concept.
+            li.list-group-item
+              | Open Claude Code and run <code>/tsykvas-claude</code> to tailor docs to your stack.
+
+          .d-flex.flex-wrap.gap-2
+            a.btn.btn-primary href="https://github.com/tsykvas/tsykvas_rails_template" target="_blank" rel="noopener"
+              | Documentation
+            button.btn.btn-outline-secondary type="button" data-bs-toggle="modal" data-bs-target="#tsykvasWelcomeModal"
+              | Open a Bootstrap modal
+
+  / Bootstrap modal — opening it proves the JS bundle (window.bootstrap) loaded.
+  #tsykvasWelcomeModal.modal.fade tabindex="-1" aria-labelledby="tsykvasWelcomeModalLabel" aria-hidden="true"
+    .modal-dialog.modal-dialog-centered
+      .modal-content
+        .modal-header
+          h5#tsykvasWelcomeModalLabel.modal-title Bootstrap modal demo
+        .modal-body
+          p
+            | If this opened, the Bootstrap JS bundle is wired through
+            =< " "
+            code app/javascript/application.js
+            | .
+        .modal-footer
+          button.btn.btn-secondary type="button" data-bs-dismiss="modal" Close

data/lib/generators/tsykvas_rails_template/install/templates/app/concepts/home/component/index.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class Home::Component::Index < ::Base::Component::Base
+  def initialize(message:)
+    @message = message
+  end
+
+  private
+
+  attr_reader :message
+end

data/lib/generators/tsykvas_rails_template/install/templates/app/concepts/home/operation/index.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+# Canonical example operation. Replace with real logic when the home page
+# becomes more than a placeholder. Demonstrates the three required calls:
+# `authorize!`, `skip_policy_scope`, and assigning `self.model`.
+class Home::Operation::Index < ::Base::Operation::Base
+  def perform!(params:, current_user:)
+    authorize! :home, :index?
+    skip_policy_scope
+
+    self.model = OpenStruct.new(
+      message: "Welcome — your app is wired up with tsykvas_rails_template."
+    )
+  end
+end