rails-hyperdrive-layered-rails 0.1.0

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/anyway-config.md

@@ -0,0 +1,212 @@
+# Anyway Config
+
+Configuration management with typed attributes and multiple sources.
+
+**GitHub**: https://github.com/palkan/anyway_config
+**Layer**: Infrastructure
+
+## Contents
+
+- Installation
+- Basic Usage
+- Base Config Class
+- Nested Configuration
+- Type Coercion
+- Validation
+- Environment Sources (Priority)
+- Local Overrides
+- Testing
+- Rails Credentials
+
+## Installation
+
+```ruby
+# Gemfile
+gem "anyway_config"
+
+# Generate config
+rails generate anyway:config stripe
+```
+
+## Basic Usage
+
+### Define Config
+
+```ruby
+# app/configs/stripe_config.rb
+class StripeConfig < Anyway::Config
+  attr_config :api_key,
+              :webhook_secret,
+              :publishable_key,
+              currency: "usd"
+
+  required :api_key, :webhook_secret
+end
+```
+
+### YAML Source
+
+```yaml
+# config/stripe.yml
+default:
+  currency: usd
+
+development:
+  api_key: sk_test_xxx
+  webhook_secret: whsec_xxx
+  publishable_key: pk_test_xxx
+
+production:
+  api_key: <%= ENV["STRIPE_API_KEY"] %>
+  webhook_secret: <%= ENV["STRIPE_WEBHOOK_SECRET"] %>
+  publishable_key: <%= ENV["STRIPE_PUBLISHABLE_KEY"] %>
+```
+
+### Access Config
+
+```ruby
+StripeConfig.new.api_key
+# Or with singleton pattern
+StripeConfig.api_key
+```
+
+## Base Config Class
+
+```ruby
+# app/configs/application_config.rb
+class ApplicationConfig < Anyway::Config
+  class << self
+    def instance
+      @instance ||= new
+    end
+
+    delegate_missing_to :instance
+  end
+end
+
+class StripeConfig < ApplicationConfig
+  # ...
+end
+
+# Usage
+StripeConfig.api_key
+```
+
+## Nested Configuration
+
+```ruby
+class EmailConfig < ApplicationConfig
+  attr_config :from_address,
+              :reply_to,
+              smtp: {
+                host: "localhost",
+                port: 25,
+                username: nil,
+                password: nil
+              }
+end
+
+# Access
+EmailConfig.smtp.host
+EmailConfig.smtp.port
+```
+
+## Type Coercion
+
+```ruby
+class AppConfig < ApplicationConfig
+  attr_config :port,
+              :debug,
+              :allowed_hosts
+
+  coerce_types port: :integer,
+               debug: :boolean,
+               allowed_hosts: { type: :string, array: true }
+end
+```
+
+## Validation
+
+```ruby
+class DatabaseConfig < ApplicationConfig
+  attr_config :host, :port, :pool_size
+
+  required :host
+
+  on_load do
+    raise_validation_error("port must be positive") if port && port <= 0
+    raise_validation_error("pool_size must be positive") if pool_size <= 0
+  end
+end
+```
+
+## Environment Sources (Priority)
+
+1. **Environment variables** (highest)
+   - `STRIPE_API_KEY`, `STRIPE_CURRENCY`
+
+2. **Local files** (gitignored)
+   - `config/stripe.local.yml`
+
+3. **Environment YAML**
+   - `config/stripe.yml` (under environment key)
+
+4. **Default values** (lowest)
+   - `attr_config currency: "usd"`
+
+```ruby
+# Override via ENV
+STRIPE_CURRENCY=eur rails console
+StripeConfig.currency  #=> "eur"
+```
+
+## Local Overrides
+
+```yaml
+# config/stripe.local.yml (gitignored)
+api_key: sk_test_local_override
+```
+
+## Testing
+
+```ruby
+RSpec.describe PaymentService do
+  let(:config) do
+    StripeConfig.new(
+      api_key: "test_key",
+      webhook_secret: "test_secret",
+      currency: "eur"
+    )
+  end
+
+  it "uses configured currency" do
+    service = described_class.new(config: config)
+    # ...
+  end
+end
+
+# Or with environment override
+RSpec.describe "with config" do
+  around do |example|
+    with_env("STRIPE_CURRENCY" => "gbp") { example.run }
+  end
+
+  it "uses environment value" do
+    expect(StripeConfig.new.currency).to eq("gbp")
+  end
+end
+```
+
+## Rails Credentials
+
+```ruby
+class SecretsConfig < ApplicationConfig
+  attr_config :secret_key_base,
+              :api_credentials
+
+  # Load from Rails credentials
+  def values
+    Rails.application.credentials.to_h
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/rubanok.md

@@ -0,0 +1,246 @@
+# Rubanok
+
+Transform controller params into database queries.
+
+**GitHub**: https://github.com/palkan/rubanok
+**Layer**: Presentation/Application boundary
+
+## Contents
+
+- Installation
+- Basic Usage
+- Param Mapping with `map`
+- Matching with `match`
+- Failure Strategy for Invalid Params
+- Nested Params
+- Sorting
+- Pagination
+- With Form Object
+- Testing
+
+## Installation
+
+```ruby
+# Gemfile
+gem "rubanok"
+```
+
+## Basic Usage
+
+### Define Processor
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  # Simple equality match
+  map :status
+
+  # With transformation
+  map :author_id do |author_id:|
+    raw.where(author_id: author_id)
+  end
+
+  # Search
+  map :q do |q:|
+    raw.where("title ILIKE ?", "%#{q}%")
+  end
+
+  # Sorting
+  map :sort do |sort:|
+    field, dir = sort.split("_")
+    raw.order(field => dir)
+  end
+end
+```
+
+### Controller Integration
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = rubanok_process(Post.all, params)
+    # Or with explicit processor
+    @posts = rubanok_process(Post.all, params, with: PostsProcessor)
+  end
+end
+```
+
+## Param Mapping with `map`
+
+### Simple Match
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  # Maps params[:status] to where(status: value)
+  map :status
+
+  # With alias
+  map :state, to: :status
+end
+```
+
+### Custom Mapping
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  map :published do |published:|
+    if published == "true"
+      raw.where.not(published_at: nil)
+    else
+      raw.where(published_at: nil)
+    end
+  end
+end
+```
+
+### Multiple Params
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  map :min_date, :max_date do |min_date: nil, max_date: nil|
+    scope = raw
+    scope = scope.where("created_at >= ?", min_date) if min_date
+    scope = scope.where("created_at <= ?", max_date) if max_date
+    scope
+  end
+end
+```
+
+## Matching with `match`
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  # Match specific values
+  match :order, ->(dir) { dir.in?(%w[asc desc]) } do |order:|
+    raw.order(created_at: order)
+  end
+
+  # Match with type checking
+  match :page, ->(v) { v.to_i.positive? } do |page:|
+    raw.page(page.to_i)
+  end
+end
+```
+
+## Failure Strategy for Invalid Params
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  # Raise on invalid params
+  fail_when :status, ->(v) { !Post.statuses.key?(v) }
+
+  # Or custom handling
+  match :status, ->(v) { Post.statuses.key?(v) } do |status:|
+    raw.where(status: status)
+  end
+end
+```
+
+## Nested Params
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  nested :filter do
+    map :status
+    map :author_id
+  end
+end
+
+# Processes params[:filter][:status], params[:filter][:author_id]
+```
+
+## Sorting
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  SORTABLE_FIELDS = %w[title created_at views_count].freeze
+
+  map :sort_by, :sort_order do |sort_by: "created_at", sort_order: "desc"|
+    field = SORTABLE_FIELDS.include?(sort_by) ? sort_by : "created_at"
+    dir = sort_order == "asc" ? :asc : :desc
+    raw.order(field => dir)
+  end
+end
+```
+
+## Pagination
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  DEFAULT_PER_PAGE = 20
+  MAX_PER_PAGE = 100
+
+  map :page, :per_page do |page: 1, per_page: DEFAULT_PER_PAGE|
+    page = [page.to_i, 1].max
+    per_page = [[per_page.to_i, 1].max, MAX_PER_PAGE].min
+
+    raw.offset((page - 1) * per_page).limit(per_page)
+  end
+end
+```
+
+## With Form Object
+
+```ruby
+class PostsFilterForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :status, :string
+  attribute :author_id, :integer
+  attribute :q, :string
+  attribute :sort_by, :string, default: "created_at"
+  attribute :sort_order, :string, default: "desc"
+
+  validates :status, inclusion: { in: Post.statuses.keys }, allow_blank: true
+end
+
+class PostsController < ApplicationController
+  def index
+    @filter = PostsFilterForm.new(filter_params)
+
+    if @filter.valid?
+      @posts = rubanok_process(Post.all, @filter.attributes)
+    else
+      @posts = Post.none
+    end
+  end
+
+  private
+
+  def filter_params
+    params.fetch(:filter, {}).permit(:status, :author_id, :q, :sort_by, :sort_order)
+  end
+end
+```
+
+## Testing
+
+```ruby
+RSpec.describe PostsProcessor do
+  let(:scope) { Post.all }
+
+  describe "status filter" do
+    it "filters by status" do
+      result = described_class.call(scope, status: "published")
+
+      expect(result.to_sql).to include("status")
+    end
+  end
+
+  describe "search" do
+    it "searches by title" do
+      result = described_class.call(scope, q: "ruby")
+
+      expect(result.to_sql).to include("ILIKE")
+    end
+  end
+
+  describe "sorting" do
+    it "sorts by field" do
+      result = described_class.call(scope, sort: "title_asc")
+
+      expect(result.to_sql).to include("ORDER BY")
+    end
+  end
+end
+```

data/lib/rails-hyperdrive-layered-rails/hyperdrive/skills/layered-rails/references/gems/view-component.md

@@ -0,0 +1,223 @@
+# ViewComponent
+
+Framework for building reusable, testable view components.
+
+**GitHub**: https://github.com/viewcomponent/view_component
+**Layer**: Presentation
+
+## Contents
+
+- Installation
+- Basic Usage
+- Slots
+- Collections
+- Inline Components
+- Stimulus Integration
+- Previews
+- Testing
+
+## Installation
+
+```ruby
+# Gemfile
+gem "view_component"
+
+# Generate component
+rails generate component UserAvatar user size
+```
+
+## Basic Usage
+
+### Define Component
+
+```ruby
+# app/components/user_avatar_component.rb
+class UserAvatarComponent < ViewComponent::Base
+  def initialize(user:, size: :medium)
+    @user = user
+    @size = size
+  end
+
+  private
+
+  def size_class
+    case @size
+    when :small then "w-8 h-8"
+    when :medium then "w-12 h-12"
+    when :large then "w-16 h-16"
+    end
+  end
+end
+```
+
+```erb
+<%# app/components/user_avatar_component.html.erb %>
+<div class="avatar <%= size_class %>">
+  <% if @user.avatar.attached? %>
+    <%= image_tag @user.avatar, class: "rounded-full" %>
+  <% else %>
+    <span class="avatar-initials"><%= @user.initials %></span>
+  <% end %>
+</div>
+```
+
+### Render Component
+
+```erb
+<%= render(UserAvatarComponent.new(user: @user, size: :large)) %>
+```
+
+## Slots
+
+### Single Slot
+
+```ruby
+class CardComponent < ViewComponent::Base
+  renders_one :header
+  renders_one :footer
+end
+```
+
+```erb
+<%# Template %>
+<div class="card">
+  <% if header? %>
+    <header><%= header %></header>
+  <% end %>
+
+  <div class="card-body"><%= content %></div>
+
+  <% if footer? %>
+    <footer><%= footer %></footer>
+  <% end %>
+</div>
+```
+
+```erb
+<%# Usage %>
+<%= render(CardComponent.new) do |card| %>
+  <% card.with_header { "Title" } %>
+  <p>Body content</p>
+  <% card.with_footer { "Footer text" } %>
+<% end %>
+```
+
+### Multiple Slots
+
+```ruby
+class ListComponent < ViewComponent::Base
+  renders_many :items, ItemComponent
+
+  class ItemComponent < ViewComponent::Base
+    def initialize(title:)
+      @title = title
+    end
+  end
+end
+```
+
+## Collections
+
+```ruby
+class PostComponent < ViewComponent::Base
+  with_collection_parameter :post
+
+  def initialize(post:)
+    @post = post
+  end
+end
+
+# Render collection
+<%= render(PostComponent.with_collection(@posts)) %>
+```
+
+## Inline Components
+
+```ruby
+class StatusBadgeComponent < ViewComponent::Base
+  def initialize(status:)
+    @status = status
+  end
+
+  def call
+    content_tag :span, @status.titleize, class: "badge #{badge_class}"
+  end
+
+  private
+
+  def badge_class
+    case @status.to_sym
+    when :active then "badge-success"
+    when :pending then "badge-warning"
+    else "badge-secondary"
+    end
+  end
+end
+```
+
+## Stimulus Integration
+
+```ruby
+class DropdownComponent < ViewComponent::Base
+  def initialize(label:)
+    @label = label
+  end
+end
+```
+
+```erb
+<div data-controller="dropdown">
+  <button data-action="dropdown#toggle"><%= @label %></button>
+  <div data-dropdown-target="menu" class="hidden">
+    <%= content %>
+  </div>
+</div>
+```
+
+## Previews
+
+```ruby
+# test/components/previews/user_avatar_component_preview.rb
+class UserAvatarComponentPreview < ViewComponent::Preview
+  def small
+    render(UserAvatarComponent.new(user: User.first, size: :small))
+  end
+
+  def medium
+    render(UserAvatarComponent.new(user: User.first, size: :medium))
+  end
+
+  def large
+    render(UserAvatarComponent.new(user: User.first, size: :large))
+  end
+end
+```
+
+Access at: `/rails/view_components/user_avatar_component/small`
+
+## Testing
+
+```ruby
+RSpec.describe UserAvatarComponent, type: :component do
+  it "renders avatar for user with image" do
+    user = create(:user, :with_avatar)
+    render_inline(described_class.new(user: user))
+
+    expect(page).to have_css("img.rounded-full")
+  end
+
+  it "renders initials without image" do
+    user = build(:user, name: "John Doe")
+    render_inline(described_class.new(user: user))
+
+    expect(page).to have_css(".avatar-initials", text: "JD")
+  end
+
+  it "applies size class" do
+    user = build(:user)
+    render_inline(described_class.new(user: user, size: :large))
+
+    expect(page).to have_css(".w-16.h-16")
+  end
+end
+```