magicka 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bb01a5f327547f6240b632c197db84720e4d4db15cf1c8db5670f22a71c57f7
-  data.tar.gz: 19b15da94bc310d043362e8f11cd10763c169c2ec37d8c04ed1f1b9fd214971c
+  metadata.gz: c084543fe6654f6bf8e182380dee9d814629d2aa43a4c322463488e1653b463c
+  data.tar.gz: 055c1153460da2568ab52b8ffb0c071a9ca72850d03def8f8cb1af05f88fbed1
 SHA512:
-  metadata.gz: 84ff51739e85682fba655c81d69217735808c3b450d13a4d26dc9f890a5bbb04f1fc89c107f900b984f8c2d2eaccbfb5b39c3a3f2c8539427bf13b4b93cef244
-  data.tar.gz: 3116e9ed5c060ac7faf810c3f752cded1442bbf745e668f0044ca0a531a5f426943988f12ac7f34e75c1c60e5003ee7e1d314d404e3ca63666a2fa483c1d76f2
+  metadata.gz: 6801f95aaddcac8a9d85820c5dd2725a9c6dc75f37317ec70324ffe00fedfba7630562e9918a2e25b43d511b0be6292b1dac1c392d4b2ab013741ef48cb773bb
+  data.tar.gz: f8d8689c93d72a1da5888d2c91667ffe6f0a831d13ec767239b764415658dfb53ce59a9185f45759886d563b0683a4b2da70089803a7129d35d9344208952fbe

data/.circleci/config.yml

@@ -18,18 +18,15 @@ workflows:
               only: /\d+\.\d+\.\d+/
             branches:
               only:
-                - master
+                - main
 jobs:
   test:
     docker:
-      - image: darthjee/circleci_rails_gems:1.2.0
+      - image: darthjee/circleci_rails_gems:2.1.0
         environment:
           PROJECT: magicka
     steps:
       - checkout
-      - run:
-          name: Prepare Coverage Test Report
-          command: cc-test-reporter before-build
       - run:
           name: Bundle Install
           command: bundle install
@@ -37,11 +34,11 @@ jobs:
           name: RSpec
           command: bundle exec rspec
       - run:
-          name: Coverage Test Report
-          command: cc-test-reporter after-build --exit-code $?
+          name: Upload coverage to Codacy
+          command: bash <(curl -Ls https://coverage.codacy.com/get.sh) report -r coverage/lcov/project.lcov
   checks:
     docker:
-      - image: darthjee/circleci_rails_gems:1.2.0
+      - image: darthjee/circleci_rails_gems:2.1.0
         environment:
           PROJECT: magicka
     steps:
@@ -66,7 +63,7 @@ jobs:
           command: check_specs
   build-and-release:
     docker:
-      - image: darthjee/circleci_rails_gems:1.2.0
+      - image: darthjee/circleci_rails_gems:2.1.0
         environment:
           PROJECT: magicka
     steps:

data/.github/copilot-instructions.md

@@ -0,0 +1,229 @@
+# GitHub Copilot Instructions for Magicka
+
+## Project Overview
+
+Magicka is a Ruby gem that facilitates the creation of HTML templates for forms and
+displaying data, especially when working with JS applications like AngularJS. Its main
+feature is providing a unified way to create form inputs and data display elements using
+the same partial templates, avoiding HTML repetition by defining templates once and
+reusing them for both forms and display views.
+
+### How It Works
+
+- Uses aggregators like `magicka_form` and `magicka_display` that render the same
+  elements differently
+- A single partial can be used for both creating forms (`new.html.erb`) and displaying
+  data (`show.html.erb`)
+- Each element is paired with an element class, a template, and a method in an aggregator
+- Supports conditional rendering (e.g., `form.only(:form)` for form-specific content)
+
+### Real-World Usage
+
+The gem is used in several projects that demonstrate practical implementation patterns
+and best practices:
+
+- darthjee/oak
+- darthjee/plague_inc
+- darthjee/paperboy
+
+---
+
+## Language Requirements
+
+- All pull requests, comments, documentation, and code must be written in **English**
+- Maintain consistency in terminology and naming conventions across the codebase
+
+---
+
+## Testing Requirements
+
+- Tests are **mandatory** for all code changes
+- Files without tests should be included in `check_specs.yml`
+- Ensure comprehensive test coverage for new features and changes
+- Test both form and display rendering scenarios
+- Test template generation and element rendering
+
+---
+
+## Documentation Requirements
+
+- Use **YARD** format for all documentation
+- Document all public methods, classes, and modules
+- Include examples showing both `magicka_form` and `magicka_display` usage
+- Document template creation and customization options
+- Provide clear examples of element classes and aggregators
+
+---
+
+## Code Style and Design Principles
+
+- Follow Sandi Metz principles from *99 Bottles of OOP*
+- Keep classes and methods focused with **single responsibilities**
+- Avoid violations of the **Law of Demeter**
+- Prefer small, well-defined methods over large, complex ones
+- Aim for **high cohesion and low coupling**
+- Separate concerns: element classes, templates, and aggregators should have distinct
+  responsibilities
+
+---
+
+## Project-Specific Guidelines
+
+### Template Design
+
+- Keep templates **DRY** (Don't Repeat Yourself)
+- A single partial should work for both form and display contexts
+- Use aggregator methods to handle context-specific rendering
+- Minimize HTML duplication by leveraging the template system
+
+### Element Classes
+
+- Each form element should have a corresponding element class
+- Element classes should encapsulate rendering logic
+- Keep element classes small and focused
+
+### Aggregators
+
+- Different aggregators (form vs display) should share method signatures
+- Aggregators should handle the context (form vs display) transparently
+- Support conditional rendering for context-specific content
+
+### Best Practices
+
+- When adding new element types, ensure they work in both form and display contexts
+- Test template rendering in multiple scenarios
+- Consider AngularJS integration patterns when applicable
+- Follow Rails conventions and best practices
+- Maintain backward compatibility when making changes
+
+---
+
+## Implementation Pattern
+
+When implementing new features, follow this pattern:
+
+```ruby
+# 1. Element class with single responsibility
+module Magicka
+  class MyElement < Magicka::Element
+    with_attribute_locals :label, :field, :id
+  end
+end
+
+# 2. Register the element with both Form and Display aggregators
+Magicka::Form.with_element(Magicka::MyElement)
+Magicka::Display.with_element(Magicka::MyElement)
+```
+
+```erb
+<%# 3. Template for rendering (templates/form/_my_element.html.erb) %>
+<div>
+  <label for="<%= field %>"><%= label %></label>
+  <input type="text" id="<%= id %>" name="<%= field %>" />
+</div>
+```
+
+```ruby
+# 4. Tests for both form and display contexts
+RSpec.describe Magicka::MyElement do
+  it 'renders in form context' do
+    # ...
+  end
+
+  it 'renders in display context' do
+    # ...
+  end
+end
+```
+
+```ruby
+# 5. YARD documentation with examples
+# @example Using in a form partial
+#   <%= form.my_element(:field_name) %>
+#
+# @example Using in a display partial
+#   <%= display.my_element(:field_name) %>
+```
+
+---
+
+## Usage Examples
+
+### Basic Setup
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  helper Magicka::Helper
+end
+```
+
+### Shared Partial
+
+```erb
+<%# app/views/people/_person_form.html.erb %>
+<%= form.input(:first_name) %>
+<%= form.input(:last_name) %>
+<%= form.input(:age) %>
+<%= form.select(:gender, options: %w[MALE FEMALE]) %>
+
+<%= form.only(:form) do %>
+  <%# This block only appears in a form context %>
+  <%= form.button(ng_click: 'controller.save', text: 'Save') %>
+<% end %>
+```
+
+### Form View
+
+```erb
+<%# app/views/people/new.html.erb %>
+<% magicka_form('controller.person') do |form| %>
+  <%= render partial: 'person_form', locals: { form: form } %>
+<% end %>
+```
+
+### Display View
+
+```erb
+<%# app/views/people/show.html.erb %>
+<% magicka_display('controller.person') do |form| %>
+  <%= render partial: 'person_form', locals: { form: form } %>
+<% end %>
+```
+
+### Custom Element
+
+```ruby
+# config/initializers/magicka.rb
+module Magicka
+  class MyTextInput < Magicka::Element
+    with_attribute_locals :label, :field, :id
+  end
+end
+
+Magicka::Form.with_element(Magicka::MyTextInput)
+```
+
+```erb
+<%# templates/form/_my_text_input.html.erb %>
+<div>
+  <label for="<%= field %>"><%= label %></label>
+  <input type="text" id="<%= id %>" name="<%= field %>" />
+</div>
+```
+
+## Sinclair Usage
+
+Magicka uses the **sinclair** gem extensively. Refer to [.github/sinclair-usage.md](.github/sinclair-usage.md) for the full usage guide.
+
+Key features used in this project:
+
+- **`Sinclair`** – Dynamically add instance/class methods to existing classes via builders
+- **`Sinclair::Model`** – Quick plain-Ruby models with keyword initializers and equality support
+- **`Sinclair::Options`** – Validated option/parameter objects with defaults
+- **`Sinclair::Configurable`** – Read-only application configuration with defaults
+- **`Sinclair::Comparable`** – Attribute-based `==` for models
+- **`Sinclair::Matchers`** – RSpec matchers to test builder behaviour (`add_method`, `add_class_method`, `change_method`)
+
+When building new features, prefer sinclair patterns for dynamic method generation, option handling, and plain-Ruby models over raw `attr_accessor` / `define_method` approaches.
+

data/.github/magicka-usage.md

@@ -0,0 +1,394 @@
+# Magicka Usage Guide
+
+Magicka is a Ruby gem that enables template reuse for both forms and data display in
+Rails applications. Its main benefit is eliminating HTML duplication by allowing a
+single partial to work in both form creation and data display contexts.
+
+## Basic Setup
+
+```ruby
+# Gemfile
+gem 'magicka'
+```
+
+```bash
+bundle install
+```
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  helper Magicka::Helper
+end
+```
+
+## Required: HTML Templates
+
+> **Important:** Magicka does not ship any HTML templates. You must create all template
+> files yourself — including those for the built-in elements (`input`, `select`,
+> `button`, and the display-context `text`). No element will render until its
+> corresponding template exists in your application.
+
+### Template Paths for Built-In Elements
+
+Each element resolves its template path from a folder configured on the element class.
+All paths below are relative to `app/views/`.
+
+| Element method | Context | Template file | Available locals |
+|----------------|---------|---------------|------------------|
+| `form.input` | form | `templates/forms/_input.html.erb` | `field`, `label`, `ng_model`, `ng_errors`, `placeholder` |
+| `form.input` | display | `templates/display/_text.html.erb` | `field`, `label`, `ng_model`, `ng_errors` |
+| `form.select` | form | `templates/forms/_select.html.erb` | `field`, `label`, `ng_model`, `ng_errors`, `options` |
+| `form.select` | display | `templates/display/_text.html.erb` | `field`, `label`, `ng_model`, `ng_errors` |
+| `form.button` | form | `templates/forms/_button.html.erb` | `text`, `ng_click`, `ng_disabled`, `classes` |
+
+`ng_model` and `ng_errors` are AngularJS expression strings (e.g.,
+`"controller.person.first_name"` and `"controller.person.errors.first_name"`).
+
+### Minimal Starter Templates
+
+These examples show the minimal markup needed to get each element working. Adapt them
+to match your application's HTML structure and CSS framework.
+
+**`app/views/templates/forms/_input.html.erb`**
+```erb
+<div>
+  <label for="<%= field %>"><%= label %></label>
+  <input type="text"
+         id="<%= field %>"
+         ng-model="<%= ng_model %>"
+         placeholder="<%= placeholder %>" />
+  <span ng-show="<%= ng_errors %>">Invalid value</span>
+</div>
+```
+
+**`app/views/templates/forms/_select.html.erb`**
+```erb
+<div>
+  <label for="<%= field %>"><%= label %></label>
+  <select id="<%= field %>" ng-model="<%= ng_model %>">
+    <% options.each do |option| %>
+      <option value="<%= option %>"><%= option %></option>
+    <% end %>
+  </select>
+  <span ng-show="<%= ng_errors %>">Invalid selection</span>
+</div>
+```
+
+**`app/views/templates/forms/_button.html.erb`**
+```erb
+<button class="<%= classes %>"
+        ng-click="<%= ng_click %>"
+        ng-disabled="<%= ng_disabled %>">
+  <%= text %>
+</button>
+```
+
+**`app/views/templates/display/_text.html.erb`** (used by both `input` and `select` in
+display context)
+```erb
+<div>
+  <label><%= label %></label>
+  <span>{{ <%= ng_model %> }}</span>
+</div>
+```
+
+---
+
+## Core Concepts
+
+### Aggregators
+
+Magicka provides two aggregators that share the same interface but render elements
+differently based on context:
+
+- **`magicka_form`** — renders elements as interactive form inputs
+- **`magicka_display`** — renders elements as read-only display values
+
+Both aggregators expose the same methods (`input`, `select`, `button`, `only`,
+`except`, `with_model`), so a single partial can be passed to either without
+modification.
+
+## Basic Usage Pattern
+
+Define one shared partial that works for both contexts:
+
+**Form view (`new.html.erb` or `edit.html.erb`):**
+```erb
+<% magicka_form('controller.person') do |form| %>
+  <%= render partial: 'person_form', locals: { form: form } %>
+<% end %>
+```
+
+**Display view (`show.html.erb`):**
+```erb
+<% magicka_display('controller.person') do |form| %>
+  <%= render partial: 'person_form', locals: { form: form } %>
+<% end %>
+```
+
+**Shared partial (`_person_form.html.erb`):**
+```erb
+<%= form.input(:first_name) %>
+<%= form.input(:last_name) %>
+<%= form.input(:age) %>
+<%= form.select(:gender, options: %w[MALE FEMALE]) %>
+
+<%= form.only(:form) do %>
+  <!-- This block only appears in a form, not in display mode -->
+  <%= form.button(ng_click: 'controller.save', text: 'Save') %>
+<% end %>
+```
+
+## Available Methods
+
+### Input Fields
+
+```erb
+<%# Renders a text input (form) or the field's display value (display) %>
+<%= form.input(:field_name) %>
+
+<%# With a custom label %>
+<%= form.input(:field_name, label: 'Custom Label') %>
+
+<%# With a placeholder %>
+<%= form.input(:field_name, placeholder: 'Enter value...') %>
+```
+
+### Select / Dropdown
+
+```erb
+<%# Renders a <select> element (form) or the selected value (display) %>
+<%= form.select(:field_name, options: %w[option_a option_b option_c]) %>
+
+<%# With a custom label %>
+<%= form.select(:role, label: 'User Role', options: %w[admin user guest]) %>
+```
+
+### Button
+
+```erb
+<%# Renders a button (form only — becomes a noop in display context) %>
+<%= form.button(text: 'Save', ng_click: 'controller.save') %>
+
+<%# With a disabled condition %>
+<%= form.button(text: 'Save', ng_click: 'controller.save', ng_disabled: 'controller.saving') %>
+```
+
+`form.button` is automatically a no-op in display context, so it is safe to call it
+outside of an `only(:form)` block when you do not need other conditional logic around
+it.
+
+### Nested Model Scope
+
+```erb
+<%# Scope a block of fields to a nested model %>
+<%= form.with_model(:address) do |address_form| %>
+  <%= address_form.input(:street) %>
+  <%= address_form.input(:city) %>
+  <%= address_form.input(:zip_code) %>
+<% end %>
+```
+
+## Conditional Rendering
+
+Use `only` and `except` to render content selectively based on the current context.
+
+```erb
+<%# Only in form context %>
+<%= form.only(:form) do %>
+  <%= form.button(ng_click: 'controller.save', text: 'Save') %>
+<% end %>
+```
+
+```erb
+<%# Only in display context %>
+<%= form.only(:display) do %>
+  <div class="timestamps">
+    Created at: <%= @person.created_at %>
+  </div>
+<% end %>
+```
+
+```erb
+<%# Everything except form context (equivalent to only(:display) when there are two contexts) %>
+<%= form.except(:form) do %>
+  <p class="read-only-note">This record is read-only.</p>
+<% end %>
+```
+
+## Best Practices
+
+- **Single Partial Pattern**: Always create one partial that works for both form and
+  display contexts. Name it descriptively (e.g., `_person_form.html.erb`).
+- **Context Parameter Naming**: Use `form` as the local variable name even in display
+  contexts — this keeps partial signatures consistent.
+- **Template Organization**: Keep partials DRY by relying on Magicka's dual-context
+  rendering rather than duplicating markup.
+- **Conditional Content**: Use `form.only(:form)` for submit buttons and other
+  form-only elements; use `form.only(:display)` for read-only annotations.
+- **Model Binding**: Pass the AngularJS model path (e.g., `'controller.person'`) as
+  the first argument to `magicka_form` and `magicka_display`.
+- **Labels**: Labels default to the capitalized, underscore-stripped field name
+  (e.g., `:first_name` → `'First name'`). Override with `label:` when needed.
+
+## Common Patterns
+
+### Simple CRUD Form
+
+```erb
+<%# _user_form.html.erb %>
+<%= form.input(:name) %>
+<%= form.input(:email) %>
+<%= form.input(:phone, label: 'Phone Number') %>
+<%= form.select(:role, options: %w[admin user guest]) %>
+
+<%= form.only(:form) do %>
+  <%= form.button(text: 'Save User', ng_click: 'controller.save') %>
+<% end %>
+```
+
+### Nested Attributes
+
+```erb
+<%# _company_form.html.erb %>
+<%= form.input(:name, label: 'Company Name') %>
+
+<%= form.with_model(:address) do |address_form| %>
+  <%= address_form.input(:street) %>
+  <%= address_form.input(:city) %>
+  <%= address_form.input(:country) %>
+<% end %>
+```
+
+### Combining Conditional Blocks
+
+```erb
+<%= form.input(:title) %>
+<%= form.input(:body) %>
+
+<%= form.only(:form) do %>
+  <%= form.select(:status, options: %w[draft published archived]) %>
+  <%= form.button(text: 'Publish', ng_click: 'controller.publish') %>
+<% end %>
+
+<%= form.only(:display) do %>
+  <p>Status: <%= @article.status %></p>
+  <p>Last updated: <%= @article.updated_at %></p>
+<% end %>
+```
+
+## Integration with AngularJS
+
+Magicka was designed with AngularJS in mind. The `ng_model` and `ng_errors` locals are
+generated automatically for each form element based on the aggregator's model path and
+the field name.
+
+### Automatic AngularJS Bindings
+
+Given `magicka_form('controller.person')` and `form.input(:first_name)`, Magicka
+automatically makes these locals available to the element template:
+
+| Local | Generated value |
+|-------|----------------|
+| `ng_model` | `"controller.person.first_name"` |
+| `ng_errors` | `"controller.person.errors.first_name"` |
+
+### Button Attributes
+
+```erb
+<%= form.button(
+  text: 'Save',
+  ng_click: 'controller.save()',
+  ng_disabled: 'controller.form.$invalid'
+) %>
+```
+
+### Example AngularJS Controller Pattern
+
+```erb
+<%# new.html.erb %>
+<div ng-controller="PersonController as controller">
+  <% magicka_form('controller.person') do |form| %>
+    <%= render partial: 'person_form', locals: { form: form } %>
+  <% end %>
+</div>
+```
+
+```erb
+<%# show.html.erb %>
+<div ng-controller="PersonController as controller">
+  <% magicka_display('controller.person') do |form| %>
+    <%= render partial: 'person_form', locals: { form: form } %>
+  <% end %>
+</div>
+```
+
+## Custom Elements
+
+You can extend Magicka with custom element types that integrate with both aggregators.
+
+```ruby
+# config/initializers/magicka.rb
+module Magicka
+  class DatePicker < Magicka::Element
+    with_attribute_locals :label, :field, :min_date, :max_date
+    template_folder 'templates/form'
+  end
+end
+
+Magicka::Form.with_element(Magicka::DatePicker)
+Magicka::Display.with_element(Magicka::DatePicker)
+```
+
+```erb
+<%# templates/form/_date_picker.html.erb %>
+<div class="date-picker">
+  <label for="<%= field %>"><%= label %></label>
+  <input type="date"
+         id="<%= field %>"
+         name="<%= field %>"
+         min="<%= min_date %>"
+         max="<%= max_date %>" />
+</div>
+```
+
+```erb
+<%# Use in a shared partial %>
+<%= form.date_picker(:birth_date, min_date: '1900-01-01', max_date: '2099-12-31') %>
+```
+
+## Real-World Examples
+
+The following projects use Magicka and demonstrate practical integration patterns:
+
+- **[darthjee/oak](https://github.com/darthjee/oak)** — authentication and
+  authorization patterns with Magicka forms
+- **[darthjee/plague_inc](https://github.com/darthjee/plague_inc)** — game-specific
+  forms and display views
+- **[darthjee/paperboy](https://github.com/darthjee/paperboy)** — content management
+  forms with edit/view modes
+
+## Common Use Cases
+
+- **User registration and profile display** — same partial for sign-up form and profile page
+- **Admin panels** — identical partial switches between edit mode and read-only view
+- **Data entry with preview** — form and display side by side using the same partial
+- **Multi-step forms with review** — final step renders the same partial in display mode
+- **API-backed forms** — display context shows persisted values; form context allows editing
+
+## Tips for GitHub Copilot
+
+- When creating a form, always plan the display view at the same time and write a single
+  shared partial.
+- Create the shared partial (`_<resource>_form.html.erb`) before writing the form and
+  display views.
+- Always name the block variable `form` in both `magicka_form` and `magicka_display`
+  for consistency across partials.
+- Use `form.only(:form)` to wrap submit buttons so they do not appear in display mode.
+- Prefer `form.button(...)` over raw `<button>` tags — it automatically becomes a
+  no-op in display context.
+- Use `form.with_model(:nested_model)` instead of changing the parent aggregator's
+  model for nested resource sections.
+- Lean on automatic label derivation (`:first_name` → `'First name'`) and only supply
+  an explicit `label:` when the default is not descriptive enough.