typed_eav 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 392d8c372c1b70b4b710cef0b9f67d79531fb237bbca37419906ed468ced365f
-  data.tar.gz: e8d9fd82f5d0d3a2cd894f89090a31522882c0606f28e691be373aacccf73cce
+  metadata.gz: 2584a7a3e9eab294e874931c8202f2dae2082be6a036bd419fce7df3fdd94f56
+  data.tar.gz: 7d24090e4969e89bb268f89510b46ce034d8f9f045054c0d6d80828c4cd3006c
 SHA512:
-  metadata.gz: 0fa26b021b7d5223f1af10e016dad89c546102f8f807d00fa6d3ea8d07a95a3e91948fa67e09137b2d93bb4cba38bf0ed2a91887812a7777fef4821bd87db190
-  data.tar.gz: 195ee963d09d43cb358ff2f39ee4f62bd131cb75fbb110bbe6a00e569c5b693fbd21313e27f899e492edc9ebb921a1021bd432aa754059df4f609d6fa50cd30a
+  metadata.gz: 4aeaa932e2dff4d5ab22ae95c66d98953b93163fc9580445f05a365ce1489a56cfdbaf998e47548d5fe468227341eec170409eafad5191449cb96201039900d0
+  data.tar.gz: 1b626f58647506b2d0317e382d0fd2d8ebf7daae1c11e84dc9d58b1929107af9c62854c19c39a6244e9957d1e20ccb7b3c924c7aee9a77aa19414453c356e534

data/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-06-01
+
+Adds a human display label for fields, distinct from the immutable machine
+slug `name` (issue #21). Fully additive — every change defaults to the
+pre-0.5.0 behavior. Existing rows (with `label` NULL) render exactly as
+before, and consumers that never set a label observe no difference.
+
+### Added
+
+- `label` — a nullable, free-text column on `typed_eav_fields`
+  (`20260507000000_add_label_to_typed_eav_fields.rb`). No index, no
+  default, no backfill: `label` never participates in uniqueness, lookup,
+  partitioning, or ordering, so an index would be dead weight. Run
+  `rails typed_eav:install:migrations` (or copy the migration) and migrate
+  to pick it up. `name` stays the immutable machine key.
+
+- `TypedEAV::Field::Base#display_name` — the canonical human-facing
+  display string. Returns the free-text `label` when present, otherwise
+  falls back to `name.humanize`. A blank (`""`) label falls back too (via
+  `presence`). This is the ONE accessor all rendering should use; existing
+  rows render unchanged.
+
+- `SchemaPortability` round-trips the label. `export_schema` emits the
+  **raw** `"label"` so `import_schema` reproduces it verbatim and
+  divergence detection treats a differing label as a difference; legacy
+  payloads with no `"label"` key import as NULL with no version gate.
+  `export_snapshot_schema` emits the **resolved** `"display_name"` instead
+  (render-oriented snapshots hand the consumer a ready-to-render string —
+  intentionally asymmetric to the raw-label regular export).
+
+### Changed
+
+- A label-only edit on a Field dispatches the `:update` event, not
+  `:rename`. `:rename` remains reserved for changes to the machine `name`.
+  Regression-pinned in `spec/regressions/issue_21_label_no_rename_spec.rb`.
+
+### References
+
+- Issue #21 — Field display label / `display_name` contract.
+
 ## [0.4.0] - 2026-05-26
 
 Closes four follow-up gaps (PRD #15) surfaced when a downstream Rails app

data/README.md

@@ -810,6 +810,7 @@ A few non-obvious contracts worth knowing about up front:
 - **Orphan-parent rows rejected**: a `Field` or `Section` row with `parent_scope` set but `scope` blank is invalid. The `Value`-side guard rejects cross-`(scope, parent_scope)` writes too.
 - **Event hooks fire from `after_commit`**: the `on_value_change` and `on_field_change` callbacks fire after the database write is durable; their exceptions never break a save. See §"Event hooks" for the full contract.
 - **Versioning is opt-in**: When enabled (`TypedEAV.config.versioning = true` on the gem; `versioned: true` per host), every `:create` / `:update` / `:destroy` event on a Value writes an append-only audit row in `typed_eav_value_versions`. See §"Versioning" for the full contract.
+- **`label` is cosmetic, `name` is the machine key**: A field's optional `label` is free-text human display, independent of the slug `name`. Render via `display_name`, which returns `label` when present else `name.humanize`. `label` has no uniqueness or format constraints (only a 255-char max) and never affects ordering, lookup, partitioning, or rename detection — editing only `label` fires `on_field_change` with `:update`, never `:rename`. Existing rows (`label` NULL) render unchanged. Schema export round-trips the raw `label` (legacy payloads without a `label` key import as NULL); snapshot export carries the resolved `display_name`.
 
 ## Event hooks
 

data/app/models/typed_eav/field/base.rb

@@ -45,6 +45,11 @@ module TypedEAV
 
       validates :name, presence: true, uniqueness: { scope: %i[entity_type scope parent_scope] }
       validates :name, exclusion: { in: RESERVED_NAMES, message: "is reserved" }
+      # `label` is optional free-text human display, independent of the machine
+      # slug `name` (issue #21). The ONLY guard is a max-length sanity bound —
+      # intentionally NO uniqueness and NO format/exclusion constraint. RESERVED_NAMES,
+      # slug-uniqueness, and rename detection all key on :name and never on :label.
+      validates :label, length: { maximum: 255 }, allow_nil: true
       validates :type, presence: true
       validates :entity_type, presence: true
       validate :validate_default_value
@@ -262,6 +267,16 @@ module TypedEAV
         self.class.name.demodulize.underscore
       end
 
+      # Canonical human-facing display string (issue #21). Returns the
+      # free-text `label` when present, otherwise falls back to humanizing the
+      # machine slug `name`. This is the ONE accessor all rendering should use;
+      # `name` stays the immutable machine key. A blank ("") label falls back
+      # too (via `presence`), so existing rows (label NULL) render exactly as
+      # they did before this column existed.
+      def display_name
+        label.presence || name.humanize
+      end
+
       def array_field?
         false
       end

data/db/migrate/20260507000000_add_label_to_typed_eav_fields.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class AddLabelToTypedEAVFields < ActiveRecord::Migration[7.1]
+  # Additive, nullable, free-text display label distinct from the machine
+  # slug `name` (issue #21). No index, no default, no backfill: `label` never
+  # participates in uniqueness, lookup, partitioning, or ordering, so an index
+  # would be dead weight. Reversible via `change` because `add_column`
+  # auto-inverts. Existing rows keep label NULL and render unchanged through
+  # the new `Field#display_name` (label.presence || name.humanize).
+  def change
+    add_column :typed_eav_fields, :label, :string, null: true
+  end
+end

data/lib/typed_eav/schema_portability.rb

@@ -113,6 +113,12 @@ module TypedEAV
           "entity_type" => field.entity_type,
           "scope" => field.scope,
           "parent_scope" => field.parent_scope,
+          # Raw label (issue #21) — NOT the resolved display_name. The regular
+          # export round-trips the stored value verbatim so import reproduces
+          # it exactly and divergence detection (field_export_row_equal?) treats
+          # a differing label as a difference. Legacy payloads lack this key →
+          # entry["label"] is nil on import → label stays NULL (no version gate).
+          "label" => field.label,
           "required" => field.required,
           "sort_order" => field.sort_order,
           "field_dependent" => field.field_dependent,
@@ -145,6 +151,12 @@ module TypedEAV
         entry = {
           "name" => field.name,
           "field_type_name" => field.field_type_name,
+          # RESOLVED display_name (issue #21), NOT the raw label — snapshots are
+          # render-oriented (CONTEXT decision 3). This is intentionally
+          # asymmetric to the regular export's raw "label": a snapshot consumer
+          # gets the ready-to-render string (label when present, else
+          # name.humanize) without re-deriving it.
+          "display_name" => field.display_name,
           "required" => field.required,
           "sort_order" => field.sort_order,
           "options" => field.options,
@@ -247,6 +259,7 @@ module TypedEAV
 
       def overwrite_field!(existing, entry)
         existing.assign_attributes(
+          label: entry["label"],
           required: entry["required"],
           sort_order: entry["sort_order"],
           field_dependent: entry["field_dependent"],

data/lib/typed_eav/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedEAV
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_eav
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - dchuk
@@ -86,6 +86,7 @@ files:
 - db/migrate/20260501000000_add_cascade_policy_to_typed_eav_fields.rb
 - db/migrate/20260505000000_create_typed_eav_value_versions.rb
 - db/migrate/20260506000001_add_version_group_id_to_typed_eav_value_versions.rb
+- db/migrate/20260507000000_add_label_to_typed_eav_fields.rb
 - lib/generators/typed_eav/install/install_generator.rb
 - lib/generators/typed_eav/scaffold/scaffold_generator.rb
 - lib/generators/typed_eav/scaffold/templates/config/initializers/typed_eav.rb