typed_eav 0.1.0

data/lib/generators/typed_eav/scaffold/templates/controllers/typed_eav_controller.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+class TypedEAVController < ApplicationController
+  include TypedEAVControllerConcern
+
+  # Fail-closed authorization. The generated admin manages field DEFINITIONS
+  # (schema-like data visible across entity types and tenants), so we pretend
+  # these routes don't exist unless the host app explicitly grants access.
+  # `head :not_found` is intentional — a 403 leaks that these routes exist.
+  #
+  # TO ENABLE ACCESS, edit the `authorize_typed_eav_admin!` method below
+  # directly in this file (defining a same-named method in ApplicationController
+  # does NOT override it — Ruby looks up methods on the subclass first).
+  # Examples to paste into the private method:
+  #
+  #   # Pundit
+  #   def authorize_typed_eav_admin!
+  #     authorize :typed_eav, :manage?
+  #   end
+  #
+  #   # CanCanCan
+  #   def authorize_typed_eav_admin!
+  #     authorize! :manage, TypedEAV::Field::Base
+  #   end
+  #
+  #   # Host-app admin predicate
+  #   def authorize_typed_eav_admin!
+  #     head :not_found unless current_user&.admin?
+  #   end
+  before_action :authorize_typed_eav_admin!
+  before_action :set_field, only: %i[show edit update destroy]
+
+  def index
+    @fields = scoped_fields.order(:entity_type, :scope, :sort_order, :name)
+  end
+
+  def show; end
+
+  def new
+    type_class = resolve_type_class(params[:type])
+    @field = type_class.new
+  end
+
+  def edit; end
+
+  def create
+    type_class = resolve_type_class(params.dig(:typed_eav_field, :field_type) || params[:type])
+    ambient = ensure_scope!
+    attrs = field_params(type_class, creating: true)
+    attrs[:scope] = ambient
+    attrs[:section_id] = verified_section_id(
+      params.dig(:typed_eav_field, :section_id),
+      attrs[:entity_type],
+      ambient
+    )
+    @field = type_class.new(attrs)
+
+    if @field.save
+      redirect_to edit_typed_eav_field_path(@field), status: :see_other,
+        notice: "Field created."
+    else
+      render :new, status: :unprocessable_content
+    end
+  end
+
+  def update
+    attrs = field_params(@field.class, creating: false)
+    attrs[:section_id] = verified_section_id(
+      params.dig(:typed_eav_field, :section_id),
+      @field.entity_type,
+      @field.scope
+    )
+
+    if @field.update(attrs)
+      redirect_to edit_typed_eav_field_path(@field), status: :see_other,
+        notice: "Field updated."
+    else
+      render :edit, status: :unprocessable_content
+    end
+  end
+
+  def destroy
+    @field.destroy!
+    redirect_to typed_eav_fields_path, status: :see_other, notice: "Field deleted."
+  end
+
+  # POST /typed_eav_fields/:typed_eav_field_id/field_options/add_option
+  def add_option
+    @field = scoped_fields.find(params[:typed_eav_field_id])
+    # Lock the field row during option creation so two concurrent creates
+    # can't observe the same `count` and assign the same sort_order.
+    @field.with_lock do
+      next_order = (@field.field_options.maximum(:sort_order) || 0) + 1
+      @field.field_options.create!(
+        label: params[:option_label],
+        value: params[:option_value],
+        sort_order: next_order
+      )
+    end
+    redirect_to edit_typed_eav_field_path(@field), status: :see_other
+  end
+
+  # DELETE /typed_eav_fields/:typed_eav_field_id/field_options/remove_option
+  def remove_option
+    @field = scoped_fields.find(params[:typed_eav_field_id])
+    @field.field_options.find(params[:option_id]).destroy!
+    redirect_to edit_typed_eav_field_path(@field), status: :see_other
+  end
+
+  private
+
+  # Default: block all access. Host app must override to grant access.
+  # `head :not_found` is intentional — a 403 leaks that these admin
+  # routes exist.
+  def authorize_typed_eav_admin!
+    head :not_found
+  end
+
+  def set_field
+    @field = scoped_fields.find(params[:id])
+  end
+
+  # Base relation filtered to the current ambient scope. Fields with
+  # scope=NULL (global fields visible to all partitions) are always
+  # included. Fail-closed semantics:
+  #   - unscoped?               -> ALL fields across every scope (admin override)
+  #   - scope present           -> fields for that scope UNION globals
+  #   - scope nil, require_scope=true  -> raise TypedEAV::ScopeRequired
+  #   - scope nil, require_scope=false -> globals only (scope=NULL); never
+  #                                       leaks other tenants' rows.
+  # Use `TypedEAV.with_scope(value) { }` or configure
+  # `TypedEAV.config.scope_resolver` to set the scope.
+  def scoped_fields
+    # Inside `TypedEAV.unscoped { }` the caller has explicitly opted into
+    # cross-scope visibility (admin/migration paths). Skip the scope filter
+    # entirely so the scaffold remains usable instead of raising under
+    # require_scope=true.
+    return TypedEAV::Field::Base.all if TypedEAV.unscoped?
+
+    scope = TypedEAV.current_scope
+    return TypedEAV::Field::Base.where(scope: [scope, nil]) if scope
+
+    if TypedEAV.config.require_scope
+      raise TypedEAV::ScopeRequired,
+        "TypedEAV.current_scope is nil and require_scope is enabled; " \
+        "wrap the request in TypedEAV.with_scope(value) { } or configure " \
+        "TypedEAV.config.scope_resolver."
+    end
+
+    TypedEAV::Field::Base.where(scope: nil)
+  end
+
+  # Resolve the ambient scope for writes. Mirrors `scoped_fields` semantics:
+  #   - unscoped?               -> returns nil (admin override; new field is global)
+  #   - scope present           -> returns the scope value
+  #   - scope nil, require_scope=true  -> raises TypedEAV::ScopeRequired
+  #   - scope nil, require_scope=false -> returns nil (global-field creation)
+  def ensure_scope!
+    # Inside `TypedEAV.unscoped { }` we deliberately bypass the require_scope
+    # guard so admin tools can create global fields without first declaring an
+    # ambient scope. Wrap in `with_scope` to write into a specific tenant.
+    return nil if TypedEAV.unscoped?
+
+    scope = TypedEAV.current_scope
+    return scope if scope
+
+    if TypedEAV.config.require_scope
+      raise TypedEAV::ScopeRequired,
+        "TypedEAV.current_scope is nil and require_scope is enabled; " \
+        "wrap the request in TypedEAV.with_scope(value) { } or configure " \
+        "TypedEAV.config.scope_resolver."
+    end
+
+    nil
+  end
+
+  # Server-side verification that the requested section exists within the
+  # caller's entity_type + scope (or globals). `Section.for_entity` unions
+  # scope=NULL globals with the scoped rows, matching field visibility.
+  # Returns nil if `id` is blank. Raises ActiveRecord::RecordNotFound (Rails
+  # renders 404) if the id does not belong to a section the caller can see,
+  # blocking cross-tenant assignment via a forged section_id.
+  def verified_section_id(id, entity_type, scope)
+    return nil if id.blank?
+    TypedEAV::Section.for_entity(entity_type, scope: scope).find(id).id
+  end
+
+  def resolve_type_class(type_name)
+    return TypedEAV::Field::Text if type_name.blank?
+    TypedEAV.config.field_class_for(type_name)
+  rescue ArgumentError
+    TypedEAV::Field::Text
+  end
+
+  # Data-driven permitted params based on what the field type exposes via
+  # store_accessor. Much cleaner than a massive case statement per type.
+  #
+  # NOTE: `scope` and `section_id` are intentionally NOT in the permit list.
+  # `scope` is derived server-side from the ambient scope in `create`; a
+  # client-supplied value would let any authenticated user write into another
+  # tenant's partition. `section_id` is verified against a scoped Section
+  # lookup via `verified_section_id` on both create and update.
+  def field_params(type_class, creating:)
+    base = %i[name required sort_order]
+    base += %i[entity_type] if creating
+
+    # Collect store_accessor keys from options (min, max, min_length, etc.)
+    option_keys = option_keys_for(type_class)
+
+    # Default value is scalar for most types, array for array types
+    if type_class.method_defined?(:array_field?) && type_class.allocate.array_field?
+      permitted = base + option_keys + [default_value: []]
+    else
+      permitted = base + option_keys + %i[default_value]
+    end
+
+    params.require(:typed_eav_field).permit(*permitted).tap do |attrs|
+      attrs.transform_values! do |value|
+        value.is_a?(Array) ? compact_array_param(value) : value
+      end
+    end
+  end
+
+  # Introspect which option keys the field type exposes
+  def option_keys_for(type_class)
+    return [] unless type_class.respond_to?(:stored_attributes)
+    (type_class.stored_attributes[:options] || []).map(&:to_sym)
+  rescue StandardError
+    []
+  end
+end

data/lib/generators/typed_eav/scaffold/templates/helpers/typed_eav_helper.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module TypedEAVHelper
+  # ─── Value Input Rendering ───────────────────────────────────
+
+  # Render all typed field inputs for a record's form. Owns the
+  # `fields_for :typed_values` builder so the submitted params are
+  # shaped correctly for `accepts_nested_attributes_for :typed_values`.
+  #
+  #   <%= render_typed_value_inputs(form: f, record: @contact) %>
+  #
+  # The controller's strong params must permit:
+  #
+  #   typed_values_attributes: [:id, :field_id, :value, :_destroy,
+  #                             { value: [] }]
+  #
+  def render_typed_value_inputs(form:, record:)
+    # Index the in-scope definitions by id. Used both to look up sort_order
+    # without touching `v.field` (avoids per-value field load when typed_values
+    # was preloaded but `:field` was not) AND to thread the resolved field
+    # into `render_typed_value_input` so it doesn't re-trigger that lookup.
+    fields_by_id = record.typed_eav_definitions.index_by(&:id)
+
+    typed_values = record.initialize_typed_values.sort_by do |v|
+      # Newly-built values may have field_id=nil but carry an in-memory
+      # `field` object; fall back to that to avoid sorting them all to 0.
+      field = fields_by_id[v.field_id] || v.field
+      field&.sort_order || 0
+    end
+
+    parts = typed_values.map do |typed_value|
+      form.fields_for(:typed_values, typed_value, child_index: nested_child_index(typed_value)) do |vf|
+        render_typed_value_input(form: vf, typed_value: typed_value, fields_by_id: fields_by_id)
+      end
+    end
+    safe_join(parts)
+  end
+
+  # Render a single typed value input. Expects `form` to be a typed-value
+  # builder (from `fields_for :typed_values`) — it emits the hidden `id` /
+  # `field_id` inputs nested attributes need to resolve the row, then
+  # delegates to the type-specific partial for the value input itself.
+  #
+  # Advanced callers that own their own `fields_for` block can invoke this
+  # directly:
+  #
+  #   <%= form.fields_for :typed_values, typed_value do |vf| %>
+  #     <%= render_typed_value_input(form: vf, typed_value: vf.object) %>
+  #   <% end %>
+  #
+  # Pass `fields_by_id:` (a {field_id => Field} map) when iterating many
+  # values to avoid triggering a per-value `typed_value.field` query in the
+  # association-loaded-but-`:field`-not-preloaded case.
+  def render_typed_value_input(form:, typed_value:, fields_by_id: nil)
+    field = (fields_by_id && fields_by_id[typed_value.field_id]) || typed_value.field
+    partial_name = value_input_partial(field)
+
+    hidden = "".html_safe
+    hidden << form.hidden_field(:id) if typed_value.persisted?
+    hidden << form.hidden_field(:field_id, value: field.id)
+
+    hidden + render(partial: partial_name, locals: {
+      form: form,
+      typed_value: typed_value,
+      field: field,
+    })
+  end
+
+  # Render an array field with add/remove buttons (Stimulus-powered).
+  #
+  #   <%= render_array_field(form: f, name: :value, value: [1,2,3],
+  #         field_method: :number_field, field_opts: { min: 0 }) %>
+  #
+  def render_array_field(form:, name:, value:, field_method:, field_opts: {})
+    render partial: "shared/array_field", locals: {
+      form: form,
+      name: name,
+      value: value,
+      field_method: field_method,
+      field_opts: field_opts,
+    }
+  end
+
+  # ─── Field Management Form Rendering ─────────────────────────
+
+  # Render the field definition form (for creating/editing field definitions).
+  def render_typed_eav_form(field:)
+    partial = field_form_partial(field)
+    render partial: partial, locals: { field: field }
+  end
+
+  # ─── Search/Filter Form Rendering ───────────────────────────
+
+  # Render a search form for filtering entities by typed fields.
+  #
+  #   <%= render_typed_eav_search(fields: Contact.typed_eav_definitions, url: contacts_path) %>
+  #
+  def render_typed_eav_search(fields:, url:)
+    render partial: "typed_eav/finders/form", locals: {
+      fields: fields,
+      url: url,
+    }
+  end
+
+  # ─── Operator Labels ────────────────────────────────────────
+
+  def typed_eav_operator_label(operator)
+    {
+      eq: "equals",
+      not_eq: "does not equal",
+      gt: "greater than",
+      gteq: "greater than or equal",
+      lt: "less than",
+      lteq: "less than or equal",
+      between: "between",
+      contains: "contains",
+      not_contains: "does not contain",
+      starts_with: "starts with",
+      ends_with: "ends with",
+      any_eq: "includes",
+      all_eq: "includes all",
+      is_null: "is empty",
+      is_not_null: "is not empty",
+    }[operator.to_sym] || operator.to_s.humanize
+  end
+
+  private
+
+  # Distinct `child_index` for each nested value so Rails generates unique
+  # param names. Use the object id for new records (stable within a request),
+  # the record id for persisted rows.
+  def nested_child_index(typed_value)
+    typed_value.persisted? ? typed_value.id : "new_#{typed_value.object_id}"
+  end
+
+  # Resolve the value input partial for a field type.
+  # Falls back to a generic text input if no specific partial exists.
+  def value_input_partial(field)
+    type_key = field.field_type_name
+    partial = "typed_eav/values/inputs/#{type_key}"
+    lookup_context.exists?(partial, [], true) ? partial : "typed_eav/values/inputs/text"
+  end
+
+  # Resolve the field definition form partial.
+  def field_form_partial(field)
+    type_key = field.field_type_name
+    partial = "typed_eav/forms/#{type_key}"
+    lookup_context.exists?(partial, [], true) ? partial : "typed_eav/forms/base"
+  end
+end

data/lib/generators/typed_eav/scaffold/templates/javascript/controllers/array_field_controller.js

@@ -0,0 +1,64 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Manages dynamic add/remove of array field inputs.
+//
+// Usage:
+//   <div data-controller="array-field">
+//     <div data-array-field-target="template" style="display:none">
+//       <input type="text" name="values[]" value="" />
+//       <button data-action="click->array-field#remove">Remove</button>
+//     </div>
+//
+//     <!-- Existing items rendered server-side -->
+//     <div data-array-field-target="item">
+//       <input type="text" name="values[]" value="existing" />
+//       <button data-action="click->array-field#remove">Remove</button>
+//     </div>
+//
+//     <button data-action="click->array-field#add">Add</button>
+//   </div>
+//
+export default class extends Controller {
+  static targets = ["template", "item", "container"]
+
+  connect() {
+    if (this.hasTemplateTarget) {
+      this.templateTarget.style.display = "none"
+    }
+  }
+
+  add(event) {
+    event.preventDefault()
+
+    if (!this.hasTemplateTarget) return
+
+    const clone = this.templateTarget.cloneNode(true)
+
+    // Remove the template target data attribute so it becomes a regular item
+    delete clone.dataset.arrayFieldTarget
+    clone.style.removeProperty("display")
+
+    // Clear input values in the clone
+    clone.querySelectorAll("input, select, textarea").forEach(input => {
+      if (input.type === "checkbox" || input.type === "radio") {
+        input.checked = false
+      } else {
+        input.value = ""
+      }
+    })
+
+    // Insert before the "Add" button
+    event.target.before(clone)
+  }
+
+  remove(event) {
+    event.preventDefault()
+
+    // Walk up to the nearest item wrapper div
+    const item = event.target.closest("[data-array-field-target='item']") ||
+                 event.target.parentElement
+    if (item) {
+      item.remove()
+    }
+  }
+}

data/lib/generators/typed_eav/scaffold/templates/javascript/controllers/typed_eav_form_controller.js

@@ -0,0 +1,32 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Manages the typed field definition form.
+// Handles dynamic scope toggling and type-specific option visibility.
+//
+// Usage:
+//   <form data-controller="typed-eav-form">
+//     <input data-typed-eav-form-target="scopeInput" />
+//     <input type="checkbox" data-typed-eav-form-target="disableScopeCheckbox"
+//            data-action="change->typed-eav-form#toggleScope" />
+//   </form>
+//
+export default class extends Controller {
+  static targets = ["scopeInput", "disableScopeCheckbox"]
+
+  connect() {
+    if (this.hasDisableScopeCheckboxTarget && this.hasDisableScopeCheckboxTarget) {
+      this.toggleScope()
+    }
+  }
+
+  toggleScope() {
+    if (!this.hasScopeInputTarget || !this.hasDisableScopeCheckboxTarget) return
+
+    const disabled = this.disableScopeCheckboxTarget.checked
+    this.scopeInputTarget.disabled = disabled
+
+    if (disabled) {
+      this.scopeInputTarget.value = ""
+    }
+  }
+}

data/lib/generators/typed_eav/scaffold/templates/views/shared/_array_field.html.erb

@@ -0,0 +1,23 @@
+<div data-controller="array-field">
+  <%# Hidden template for cloning new items %>
+  <div data-array-field-target="template" style="display: none;">
+    <%= form.public_send(field_method, name, { multiple: true, value: "", **field_opts }) %>
+    <% unless field_opts[:disabled] %>
+      <button type="button" data-action="click->array-field#remove">Remove</button>
+    <% end %>
+  </div>
+
+  <%# Existing values %>
+  <% Array(value).each do |value_element| %>
+    <div data-array-field-target="item">
+      <%= form.public_send(field_method, name, { multiple: true, value: value_element || "", **field_opts }) %>
+      <% unless field_opts[:disabled] %>
+        <button type="button" data-action="click->array-field#remove">Remove</button>
+      <% end %>
+    </div>
+  <% end %>
+
+  <% unless field_opts[:disabled] %>
+    <button type="button" data-action="click->array-field#add">Add</button>
+  <% end %>
+</div>

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/edit.html.erb

@@ -0,0 +1,47 @@
+<h1>Edit <%= @field.field_type_name.humanize %> Field: <%= @field.name %></h1>
+
+<%= render_typed_eav_form(field: @field) %>
+
+<% if @field.optionable? %>
+  <hr>
+  <h2>Options</h2>
+
+  <table>
+    <thead>
+      <tr><th>Label</th><th>Value</th><th>Order</th><th></th></tr>
+    </thead>
+    <tbody>
+      <% @field.field_options.sorted.each do |option| %>
+        <tr>
+          <td><%= option.label %></td>
+          <td><code><%= option.value %></code></td>
+          <td><%= option.sort_order %></td>
+          <td>
+            <%= button_to "Remove",
+              remove_option_typed_eav_field_field_options_path(@field, option_id: option.id),
+              method: :delete,
+              data: { turbo_confirm: "Remove this option?" } %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+
+  <%= form_with url: add_option_typed_eav_field_field_options_path(@field), method: :post do |f| %>
+    <div style="display: flex; gap: 0.5rem; align-items: end; margin-top: 0.5rem;">
+      <div>
+        <%= f.label :option_label, "Label" %>
+        <%= f.text_field :option_label, required: true %>
+      </div>
+      <div>
+        <%= f.label :option_value, "Value" %>
+        <%= f.text_field :option_value, required: true %>
+      </div>
+      <%= f.submit "Add Option" %>
+    </div>
+  <% end %>
+<% end %>
+
+<div style="margin-top: 1rem;">
+  <%= link_to "Back", typed_eav_fields_path %>
+</div>

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/finders/_form.html.erb

@@ -0,0 +1,80 @@
+<%# Search/filter form for querying entities by typed field values.
+    Usage: render_typed_eav_search(fields: Contact.typed_eav_definitions, url: contacts_path) %>
+
+<%= form_with url: url, method: :get, data: { turbo_frame: "_top" } do |f| %>
+  <fieldset>
+    <legend>Filter by Custom Fields</legend>
+
+    <div id="typed-eav-filters">
+      <% typed_eav_filter_params.each_with_index do |filter_params, idx| %>
+        <% filter_params = filter_params.to_h.with_indifferent_access if filter_params.respond_to?(:to_h) %>
+        <% field_name = filter_params[:n] || filter_params[:name] %>
+        <% field = fields.find { |af| af.name == field_name } %>
+        <% next unless field %>
+        <div class="typed-eav-filter" style="display: flex; gap: 0.5rem; margin-bottom: 0.5rem; align-items: end;">
+          <div>
+            <label>Field</label>
+            <select name="f[][n]">
+              <option value="">--</option>
+              <% fields.each do |af| %>
+                <option value="<%= af.name %>" <%= "selected" if af.name == field_name %>>
+                  <%= af.name.humanize %>
+                </option>
+              <% end %>
+            </select>
+          </div>
+          <div>
+            <label>Operator</label>
+            <select name="f[][op]">
+              <% field.class.supported_operators.each do |op| %>
+                <option value="<%= op %>"
+                  <%= "selected" if op.to_s == (filter_params[:op] || filter_params[:operator]).to_s %>>
+                  <%= typed_eav_operator_label(op) %>
+                </option>
+              <% end %>
+            </select>
+          </div>
+          <div>
+            <label>Value</label>
+            <input type="text" name="f[][v]"
+              value="<%= filter_params[:v] || filter_params[:value] %>" />
+          </div>
+        </div>
+      <% end %>
+
+      <%# Empty filter row for adding new filters %>
+      <div class="typed-eav-filter" style="display: flex; gap: 0.5rem; margin-bottom: 0.5rem; align-items: end;">
+        <div>
+          <label>Field</label>
+          <select name="f[][n]">
+            <option value="">--</option>
+            <% fields.each do |af| %>
+              <option value="<%= af.name %>"><%= af.name.humanize %></option>
+            <% end %>
+          </select>
+        </div>
+        <div>
+          <label>Operator</label>
+          <select name="f[][op]">
+            <option value="eq">equals</option>
+            <option value="not_eq">does not equal</option>
+            <option value="gt">greater than</option>
+            <option value="lt">less than</option>
+            <option value="contains">contains</option>
+            <option value="is_null">is empty</option>
+            <option value="is_not_null">is not empty</option>
+          </select>
+        </div>
+        <div>
+          <label>Value</label>
+          <input type="text" name="f[][v]" />
+        </div>
+      </div>
+    </div>
+
+    <div style="margin-top: 0.5rem;">
+      <%= f.submit "Search" %>
+      <%= link_to "Clear", url %>
+    </div>
+  </fieldset>
+<% end %>

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_boolean.html.erb

@@ -0,0 +1,12 @@
+<%= form_with(model: field, scope: :typed_eav_field,
+      url: field.persisted? ? typed_eav_field_path(field) : typed_eav_fields_path) do |f| %>
+  <%= render "typed_eav/forms/common_fields", f: f, field: field %>
+
+  <div>
+    <%= f.label :default_value %>
+    <%= f.select :default_value, [["None", ""], ["True", "true"], ["False", "false"]],
+          { selected: field.default_value.to_s } %>
+  </div>
+
+  <div><%= f.submit field.persisted? ? "Update" : "Create" %></div>
+<% end %>

data/lib/generators/typed_eav/scaffold/templates/views/typed_eav/forms/_color.html.erb

@@ -0,0 +1,11 @@
+<%= form_with(model: field, scope: :typed_eav_field,
+      url: field.persisted? ? typed_eav_field_path(field) : typed_eav_fields_path) do |f| %>
+  <%= render "typed_eav/forms/common_fields", f: f, field: field %>
+
+  <div>
+    <%= f.label :default_value %>
+    <%= f.text_field :default_value, value: field.default_value %>
+  </div>
+
+  <div><%= f.submit field.persisted? ? "Update" : "Create" %></div>
+<% end %>