paper_trail-human 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfb8c783e819dfade94289a84366e1d04f13f711339c6c08ca471d4a2daac52c
-  data.tar.gz: 6ff6a8161a65ee10cc25a84c77f5986a33c9a13b285854efc7e8fce30597f198
+  metadata.gz: 3b4f76ffb9c3e73defa2048c879473a97d861f58831bd5277dcf85ad0d8656a3
+  data.tar.gz: e1bddce4e11cddb78b79fded41c9d874fc5b5b680f6d90c859a3f455d10f356e
 SHA512:
-  metadata.gz: dcc23c680e095752b9413ece751ebb82c5d4b3b8bf060811d01acfb775f4b803f2a65a318f175d40e288716b2bf6a13e35ca56a586391187900d60a1f2b0ec5c
-  data.tar.gz: '08542e032fd13d2e8ad3a9ae4949145ca5bf82d0e5290cbc2387393df0cbf1de8ebb4724fb16ea756b96394a5a43e4add686f4f9b14612f9cd7c85b78e0fe22c'
+  metadata.gz: d78f8fa3b717ba035f6aa9cfc2e52ae6f5d72caae5bd581cd9a79490fc6b25ddf91d165d07a358b9ee6a3e168c0647ee37d2f6c6168e23df5124f8f5c98e12fe
+  data.tar.gz: 4cbfc5c62c108a1a36377e3dd75ff789b86b1ceb10374b93c846961fefe8dfb33df92168d1ee726af33ac7982d1d998bf2aa576fddb5f3be2adabc5530bea225

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.6.0] - 2026-06-02
+
+### Added
+- `:relation` resolver now supports arrays of IDs, resolving each to its attribute value
+
 ## [0.5.0] - 2026-06-01
 
 ### Added

data/README.md

@@ -18,6 +18,7 @@ Resolves foreign keys to names, translates enums and constants, formats dates an
   - [2b. Per-Model Fields](#2b-per-model-fields)
   - [2c. Item Name](#2c-item-name)
   - [2d. After Format Hook](#2d-after-format-hook)
+  - [2e. Event Callbacks](#2e-event-callbacks)
 - [3. Resolvers](#3-resolvers)
   - [3a. Relation](#3a-relation)
   - [3b. Enum](#3b-enum)
@@ -32,13 +33,16 @@ Resolves foreign keys to names, translates enums and constants, formats dates an
   - [4c. Filtering Fields](#4c-filtering-fields)
   - [4d. Output Formats](#4d-output-formats)
 - [5. Timeline](#5-timeline)
-- [6. I18n](#6-i18n)
-  - [6a. Field Names](#6a-field-names)
-  - [6b. Event Labels](#6b-event-labels)
-- [7. Architecture](#7-architecture)
-- [8. Requirements](#8-requirements)
-- [9. Contributing](#9-contributing)
-- [10. License](#10-license)
+- [6. Extensibility](#6-extensibility)
+  - [6a. Custom Resolvers](#6a-custom-resolvers)
+  - [6b. Custom Formatters](#6b-custom-formatters)
+- [7. I18n](#7-i18n)
+  - [7a. Field Names](#7a-field-names)
+  - [7b. Event Labels](#7b-event-labels)
+- [8. Architecture](#8-architecture)
+- [9. Requirements](#9-requirements)
+- [10. Contributing](#10-contributing)
+- [11. License](#11-license)
 
 ## 1. Introduction
 
@@ -46,11 +50,13 @@ Resolves foreign keys to names, translates enums and constants, formats dates an
 
 | paper_trail-human | ruby    | activerecord | paper_trail |
 |-------------------|---------|--------------|-------------|
+| 0.5.x             | >= 3.1  | >= 6.1       | >= 12.0     |
+| 0.4.x             | >= 3.1  | >= 6.1       | >= 12.0     |
 | 0.3.x             | >= 3.1  | >= 6.1       | >= 12.0     |
 | 0.2.x             | >= 3.0  | >= 6.1       | >= 12.0     |
 | 0.1.x             | >= 2.7  | >= 5.2       | >= 9.0      |
 
-**CI matrix (0.3.x):**
+**CI matrix (0.5.x):**
 
 | Rails | PaperTrail | Ruby              |
 |-------|-----------|-------------------|
@@ -138,7 +144,7 @@ PaperTrail::Human.configure do |config|
     m.field :role, :enum, class_name: "UserRole", method: :label
     m.field :company_id, :relation, class_name: "Company", attribute: :name
     m.field :active, :boolean, true_label: "Active", false_label: "Inactive"
-    m.field :bio, :text, max_length: 100, show_diff_stats: true
+    m.field :bio, :text, max_length: 100, diff: true
     m.field :due_date, :date, format: "%d/%m/%Y"
     m.field :salary, :number, format: :currency, unit: "R$"
     m.field :score, :custom, resolve: ->(v) { "#{v} points" }
@@ -163,6 +169,8 @@ PaperTrail::Human.format(version)[:item_name]
 
 The `item_name` key is only present when the record exists and the attribute is configured.
 
+In batch mode (`format_collection`), item names are preloaded to prevent N+1 queries.
+
 ### 2d. After Format Hook
 
 Post-process every formatted result:
@@ -176,6 +184,24 @@ config.after_format = ->(result, version) {
 
 The lambda receives the formatted hash and the original `PaperTrail::Version`, and must return the hash.
 
+### 2e. Event Callbacks
+
+Register multiple callbacks that fire after formatting. Useful for side effects like logging, notifications, or external integrations:
+
+```ruby
+config.on_format do |result, version|
+  AuditLog.push(result) if result[:event] == "destroy"
+end
+
+config.on_format do |result, version|
+  SlackNotifier.notify(result)
+end
+```
+
+- Multiple callbacks, executed in order of registration
+- Fault-tolerant: errors in one callback don't block others or the return value
+- Runs after the `after_format` hook
+
 ## 3. Resolvers
 
 ### 3a. Relation
@@ -234,17 +260,32 @@ m.field :score, :custom, resolve: ->(value) { "#{value} points" }
 
 ### 3e. Text
 
-Truncates long text fields:
+Truncates long text fields with optional diff stats:
 
 ```ruby
 m.field :body, :text, max_length: 100, show_diff_stats: true
 # => "Lorem ipsum dolor sit amet..." (250 chars)
 ```
 
+**Diff mode** — shows line-level additions and deletions:
+
+```ruby
+m.field :body, :text, diff: true
+# => {
+#   field: "Body",
+#   previous_value: "Old text...",
+#   value: "New text...",
+#   additions: 5,
+#   deletions: 2,
+#   summary: "+5/-2 lines"
+# }
+```
+
 | Option | Description | Default |
 |--------|-------------|---------|
 | `max_length:` | Maximum characters before truncation | `80` |
 | `show_diff_stats:` | Append total char count | `false` |
+| `diff:` | Enable line-level diff stats | `false` |
 
 ### 3f. Date
 
@@ -302,7 +343,9 @@ Event-specific behavior:
 PaperTrail::Human.format_collection(user.versions)
 ```
 
-Same as `format` but for multiple versions. Relations are batch-loaded to prevent N+1 queries.
+Same as `format` but for multiple versions. Relations and item names are batch-loaded to prevent N+1 queries.
+
+When using `as:`, returns a single joined string (separated by blank lines for text/markdown, newlines for HTML).
 
 ### 4c. Filtering Fields
 
@@ -326,7 +369,7 @@ PaperTrail::Human.format(version, as: :html)
 # => HTML div with table (XSS-safe, escapes entities)
 ```
 
-Available formats: `:text`, `:markdown`, `:html`.
+Built-in formats: `:text`, `:markdown`, `:html`. Custom formats can be registered (see [6b. Custom Formatters](#6b-custom-formatters)).
 
 Works with both `format` and `format_collection`.
 
@@ -351,9 +394,61 @@ PaperTrail::Human.timeline(user.versions, group_by: :day)
 
 Supports `only:` and `except:` filters.
 
-## 6. I18n
+## 6. Extensibility
+
+### 6a. Custom Resolvers
+
+Register your own resolver types:
+
+```ruby
+class MoneyResolver
+  include PaperTrail::Human::Ports::Resolver
+
+  def initialize(currency: "USD", **)
+    @currency = currency
+  end
+
+  def resolve(value)
+    "#{@currency} #{format('%.2f', value.to_f)}"
+  end
+end
+
+PaperTrail::Human.configure do |config|
+  config.register_resolver :money, MoneyResolver
+
+  config.register "Order" do |m|
+    m.field :total, :money, currency: "R$"
+  end
+end
+```
+
+The resolver class must include `PaperTrail::Human::Ports::Resolver` and implement `#resolve(value)`.
+
+For resolvers that need both old and new values, implement `#resolve_pair?` returning `true` and `#resolve_change(previous_value, new_value)`.
+
+### 6b. Custom Formatters
+
+Register your own output formats:
+
+```ruby
+class JsonFormatter
+  def call(result)
+    result.to_json
+  end
+end
+
+PaperTrail::Human.configure do |config|
+  config.register_formatter :json, JsonFormatter
+end
+
+PaperTrail::Human.format(version, as: :json)
+```
+
+The formatter class must implement `#call(result)` and return a string.
+
+## 7. I18n
 
-### 6a. Field Names
+### 7a. Field Names
 
 Field names are resolved in this order:
 
@@ -363,7 +458,7 @@ Field names are resolved in this order:
 
 Example: `company_id` → looks up `activerecord.attributes.user.company_id` → falls back to `"Company"`.
 
-### 6b. Event Labels
+### 7b. Event Labels
 
 Enable translated event labels:
 
@@ -393,7 +488,7 @@ pt-BR:
       destroy: "Exclusão"
 ```
 
-## 7. Architecture
+## 8. Architecture
 
 Hexagonal (Ports & Adapters):
 
@@ -401,8 +496,9 @@ Hexagonal (Ports & Adapters):
 ┌─────────────────────────────────────────────┐
 │                   Core                       │
 │  ChangeExtractor · FieldFormatter            │
-│  EventTranslator · Presenter                 │
-│  BatchPresenter  · Timeline                  │
+│  EventTranslator · AfterFormat               │
+│  Presenter · BatchPresenter · Timeline       │
+│  ItemNameLoader · RelationLoader             │
 ├─────────────────────────────────────────────┤
 │                   Ports                       │
 │  Resolver (interface)                        │
@@ -411,25 +507,26 @@ Hexagonal (Ports & Adapters):
 │  Resolvers: Relation, Enum, Boolean,         │
 │             Custom, Text, Date, Number       │
 │  Formatters: Text, Markdown, Html            │
+│  (+ user-registered resolvers/formatters)    │
 └─────────────────────────────────────────────┘
 ```
 
 - **Core** — pure formatting logic, no external dependencies
 - **Ports** — `Resolver` interface that every adapter implements
-- **Adapters** — concrete implementations for resolving values and formatting output
+- **Adapters** — concrete implementations (lazy-loaded via `autoload`)
 
-The gem has zero dependencies beyond `activerecord` and `paper_trail`. The Railtie is optional — it works in non-Rails apps (Sinatra, Hanami, etc).
+The gem has zero dependencies beyond `activerecord` and `paper_trail`. Adapters are loaded on demand. The Railtie is optional — it works in non-Rails apps (Sinatra, Hanami, etc).
 
-## 8. Requirements
+## 9. Requirements
 
 - Ruby >= 3.1
 - Rails >= 6.1 (or standalone ActiveRecord)
 - PaperTrail >= 12.0
 
-## 9. Contributing
+## 10. Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on setting up the development environment, running tests, and submitting pull requests.
 
-## 10. License
+## 11. License
 
 MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/paper_trail/human/adapters/resolvers/relation.rb

@@ -14,6 +14,18 @@ module PaperTrail
           end
 
           def resolve(value)
+            return resolve_array(value) if value.is_a?(Array)
+
+            resolve_single(value)
+          end
+
+          private
+
+          def resolve_array(values)
+            values.map { |v| resolve_single(v) }
+          end
+
+          def resolve_single(value)
             return @cache[value] || @cache[value.to_i] || value if @cache.any?
 
             klass = safe_const_get(@class_name)

data/lib/paper_trail/human/version.rb

@@ -2,6 +2,6 @@
 
 module PaperTrail
   module Human
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail-human
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Gabriel