lcp 0.1.0

data/lib/lcp_ruby/dsl/presenter_builder.rb

@@ -0,0 +1,1272 @@
+require_relative "source_location_capture"
+
+module LcpRuby
+  module Dsl
+    class PresenterBuilder
+      include SourceLocationCapture
+
+      # Builds a condition hash from a DSL block.
+      # Usage: condition = PresenterBuilder.condition { field(:status).eq("active") }
+      def self.condition(&block)
+        ConditionBuilder.build(&block)
+      end
+
+      def initialize(name)
+        @name = name.to_s
+        @model_name = nil
+        @label_value = nil
+        @label_source_loc = nil
+        @slug_value = nil
+        @icon_value = nil
+        @menu_position_value = nil
+        @default_value = false
+        @index_hash = nil
+        @show_hash = nil
+        @form_hash = nil
+        @search_hash = nil
+        @actions = []
+        @options = {}
+        @dialog_hash = nil
+        @export_hash = nil
+        @import_hash = nil
+        @controller_value = nil
+        @action_controllers_value = nil
+        @record_aliases = {}
+      end
+
+      # Top-level setters
+      def model(value)
+        @model_name = value.to_s
+      end
+
+      def label(value)
+        @label_value = value.to_s
+        @label_source_loc = capture_source_loc
+      end
+
+      def slug(value)
+        @slug_value = value.to_s
+      end
+
+      def icon(value)
+        @icon_value = value.to_s
+      end
+
+      # #15 — Position hint for the auto-created view group when this is the
+      # only presenter on the model. Lifts the entry out of the alphabetical
+      # 900+index tier into a configurator-controlled position. Ignored when
+      # an explicit view group YAML exists for the model.
+      def menu_position(value)
+        @menu_position_value = value.to_i
+      end
+
+      # B19 — Marks this presenter as the canonical link target for its model.
+      # Used by Presenter::Enrichment when the model has multiple presenters
+      # and a column/field uses `link: true` without a per-link `link_presenter:`
+      # override. Exactly one presenter per model may be marked default.
+      def default(value = true)
+        @default_value = value == true
+      end
+
+      def read_only(value = true)
+        @options["read_only"] = value
+      end
+
+      def embeddable(value = true)
+        @options["embeddable"] = value
+      end
+
+      def redirect_after(create: nil, update: nil)
+        ra = {}
+        ra["create"] = create.to_s if create
+        ra["update"] = update.to_s if update
+        @options["redirect_after"] = ra
+      end
+
+      def empty_value(value)
+        @options["empty_value"] = value
+      end
+
+      def max_inline_actions(value)
+        @options["max_inline_actions"] = value.to_i
+      end
+
+      def scope(value)
+        @options["scope"] = value.to_s
+      end
+
+      def controller(name)
+        @controller_value = name.to_s
+      end
+
+      def action_controllers(mapping)
+        @action_controllers_value = HashUtils.stringify_deep(mapping)
+      end
+
+      def record_alias(name, **opts)
+        @record_aliases[name.to_s] = HashUtils.stringify_deep(opts)
+      end
+
+      def dialog(size: nil, closable: nil, title_key: nil)
+        @dialog_hash = {}
+        @dialog_hash["size"] = size.to_s if size
+        @dialog_hash["closable"] = closable unless closable.nil?
+        @dialog_hash["title_key"] = title_key.to_s if title_key
+      end
+
+      def export(formats: nil, max_records: nil, save_history: nil, fields: nil, csv_delimiter: nil)
+        @export_hash = {}
+        @export_hash["formats"] = formats.map(&:to_s) if formats
+        @export_hash["max_records"] = max_records if max_records
+        @export_hash["save_history"] = save_history unless save_history.nil?
+        @export_hash["fields"] = fields.map(&:to_s) if fields
+        @export_hash["csv_delimiter"] = csv_delimiter if csv_delimiter
+      end
+
+      def import(formats: nil, max_rows: nil, max_file_size: nil, csv_delimiter: nil, csv_encoding: nil, parsing: nil,
+                 nested_associations: nil, nested_blank_strategy: nil)
+        @import_hash = {}
+        @import_hash["formats"] = formats.map(&:to_s) if formats
+        @import_hash["max_rows"] = max_rows if max_rows
+        @import_hash["max_file_size"] = max_file_size if max_file_size
+        @import_hash["csv_delimiter"] = csv_delimiter if csv_delimiter
+        @import_hash["csv_encoding"] = csv_encoding.to_s if csv_encoding
+        @import_hash["parsing"] = HashUtils.stringify_deep(parsing) if parsing
+        @import_hash["nested_associations"] = nested_associations.map(&:to_s) if nested_associations
+        @import_hash["nested_blank_strategy"] = nested_blank_strategy.to_s if nested_blank_strategy
+      end
+
+      # View blocks
+      def index(&block)
+        builder = IndexBuilder.new
+        builder.instance_eval(&block)
+        @index_hash = builder.to_hash
+      end
+
+      def show(&block)
+        builder = ShowBuilder.new
+        builder.instance_eval(&block)
+        @show_hash = builder.to_hash
+      end
+
+      def form(&block)
+        builder = FormBuilder.new
+        builder.instance_eval(&block)
+        @form_hash = builder.to_hash
+      end
+
+      def search(enabled: nil, &block)
+        if block
+          builder = SearchBuilder.new
+          builder.instance_eval(&block)
+          @search_hash = builder.to_hash
+        elsif !enabled.nil?
+          @search_hash = { "enabled" => enabled }
+        end
+      end
+
+      # Flat actions
+      def action(name, type:, on:, **options)
+        source_loc = capture_source_loc
+        action_hash = {
+          "name" => name.to_s,
+          "type" => type.to_s
+        }
+        action_hash["_source_loc"] = source_loc if source_loc
+        if options.key?(:label)
+          action_hash["label"] = options[:label]
+          action_hash["_label_source_loc"] = source_loc
+        end
+        action_hash["icon"] = options[:icon].to_s if options.key?(:icon)
+        action_hash["confirm"] = options[:confirm].is_a?(Hash) ? HashUtils.stringify_deep(options[:confirm]) : options[:confirm] if options.key?(:confirm)
+        action_hash["confirm_message"] = options[:confirm_message] if options.key?(:confirm_message)
+        action_hash["style"] = options[:style].to_s if options.key?(:style)
+        action_hash["dialog"] = HashUtils.stringify_deep(options[:dialog]) if options.key?(:dialog)
+        action_hash["record"] = options[:record].to_s if options.key?(:record)
+        action_hash["visible"] = options[:visible] if options.key?(:visible)
+        action_hash["visible_when"] = resolve_condition(options[:visible_when]) if options.key?(:visible_when)
+        action_hash["disable_when"] = resolve_condition(options[:disable_when]) if options.key?(:disable_when)
+
+        # Batch action options
+        %i[min_selection max_selection max_batch_records result_log select_all_filter
+           execution background_threshold strategy].each do |key|
+          action_hash[key.to_s] = options[key] if options.key?(key)
+        end
+        action_hash["fields"] = options[:fields].map(&:to_s) if options.key?(:fields)
+
+        if options.key?(:batch)
+          val = options[:batch]
+          action_hash["batch"] = val.is_a?(Hash) ? HashUtils.stringify_deep(val) : val
+        end
+
+        # Pipeline / sugar attributes for single actions
+        action_hash["pipeline"] = HashUtils.stringify_deep(options[:pipeline]) if options.key?(:pipeline)
+        action_hash["transition"] = options[:transition].to_s if options.key?(:transition)
+        action_hash["action"] = options[:action].to_s if options.key?(:action)
+
+        @actions << { on: on.to_s, hash: action_hash }
+      end
+
+      # Form-specific action shorthand (routes to on: "form" context)
+      def form_action(name, **options)
+        source_loc = capture_source_loc
+        action_hash = { "name" => name.to_s }
+        action_hash["type"] = options[:type].to_s if options.key?(:type)
+        action_hash["_source_loc"] = source_loc if source_loc
+        if options.key?(:label)
+          action_hash["label"] = options[:label]
+          action_hash["_label_source_loc"] = source_loc
+        end
+        if options.key?(:submitting_label)
+          action_hash["submitting_label"] = options[:submitting_label]
+          action_hash["_submitting_label_source_loc"] = source_loc
+        end
+        action_hash["icon"] = options[:icon].to_s if options.key?(:icon)
+        action_hash["style"] = options[:style].to_s if options.key?(:style)
+        if options.key?(:redirect)
+          action_hash["redirect"] = options[:redirect].is_a?(Hash) ? HashUtils.stringify_deep(options[:redirect]) : options[:redirect].to_s
+        end
+        action_hash["only_on"] = options[:only_on].to_s if options.key?(:only_on)
+        action_hash["confirm"] = options[:confirm].is_a?(Hash) ? HashUtils.stringify_deep(options[:confirm]) : options[:confirm] if options.key?(:confirm)
+        action_hash["confirm_message"] = options[:confirm_message] if options.key?(:confirm_message)
+        action_hash["set_fields"] = HashUtils.stringify_deep(options[:set_fields]) if options.key?(:set_fields)
+        action_hash["pipeline"] = HashUtils.stringify_deep(options[:pipeline]) if options.key?(:pipeline)
+        action_hash["transition"] = options[:transition].to_s if options.key?(:transition)
+        action_hash["action"] = options[:action].to_s if options.key?(:action)
+        action_hash["dialog_behavior"] = options[:dialog_behavior].to_s if options.key?(:dialog_behavior)
+        action_hash["result"] = HashUtils.stringify_deep(options[:result]) if options.key?(:result)
+        action_hash["position"] = options[:position].to_s if options.key?(:position)
+        action_hash["visible_when"] = resolve_condition(options[:visible_when]) if options.key?(:visible_when)
+        action_hash["disable_when"] = resolve_condition(options[:disable_when]) if options.key?(:disable_when)
+        action_hash["only_roles"] = Array(options[:only_roles]).map(&:to_s) if options.key?(:only_roles)
+        action_hash["except_roles"] = Array(options[:except_roles]).map(&:to_s) if options.key?(:except_roles)
+
+        @actions << { on: "form", hash: action_hash }
+      end
+
+      def to_hash
+        hash = { "name" => @name }
+        hash["model"] = @model_name if @model_name
+        hash["label"] = @label_value if @label_value
+        hash["_label_source_loc"] = @label_source_loc if @label_source_loc
+        hash["slug"] = @slug_value if @slug_value
+        hash["icon"] = @icon_value if @icon_value
+        hash["menu_position"] = @menu_position_value if @menu_position_value
+        hash["default"] = true if @default_value
+        hash["record_aliases"] = @record_aliases unless @record_aliases.empty?
+
+        hash["index"] = @index_hash if @index_hash
+        hash["show"] = @show_hash if @show_hash
+        hash["form"] = @form_hash if @form_hash
+        hash["search"] = @search_hash if @search_hash
+        hash["dialog"] = @dialog_hash if @dialog_hash
+        hash["export"] = @export_hash if @export_hash
+        hash["import"] = @import_hash if @import_hash
+
+        unless @actions.empty?
+          hash["actions"] = build_actions_hash
+        end
+
+        hash["controller"] = @controller_value if @controller_value
+        hash["action_controllers"] = @action_controllers_value if @action_controllers_value
+
+        # Options are stored at the top level for PresenterDefinition.from_hash
+        @options.each { |k, v| hash[k] = v }
+
+        hash
+      end
+
+      def to_yaml
+        { "presenter" => to_hash }.to_yaml
+      end
+
+      # Merge this builder's output on top of a parent hash.
+      # Keys defined by the child replace the parent's values entirely (section-level replace).
+      def to_hash_with_parent(parent_hash)
+        child_hash = to_hash
+        merged = parent_hash.deep_dup
+
+        # `default: true` is intrinsic to a single presenter — never inherits.
+        # The validator enforces exactly one default per model; auto-propagation
+        # via `inherits:` would always violate that.
+        merged.delete("default")
+
+        # Always override these from child if defined
+        %w[name label slug icon default record_aliases read_only embeddable redirect_after empty_value scope max_inline_actions controller action_controllers].each do |key|
+          merged[key] = child_hash[key] if child_hash.key?(key)
+        end
+
+        # Section-level replace: child replaces parent entirely for these keys
+        %w[index show form search actions dialog export import].each do |key|
+          merged[key] = child_hash[key] if child_hash.key?(key)
+        end
+
+        # Model is always from parent unless child overrides
+        merged["model"] = child_hash["model"] if child_hash.key?("model")
+
+        merged
+      end
+
+      private
+
+      def build_actions_hash
+        grouped = {}
+        @actions.each do |entry|
+          key = entry[:on]
+          grouped[key] ||= []
+          grouped[key] << entry[:hash]
+        end
+        grouped
+      end
+
+      # Resolves a condition from either a Hash or a ConditionBuilder block (Proc)
+      def resolve_condition(value)
+        case value
+        when Proc
+          ConditionBuilder.build(&value)
+        when Hash
+          stringify_visible_when(value)
+        else
+          value
+        end
+      end
+
+      def stringify_visible_when(condition)
+        return nil unless condition.is_a?(Hash)
+
+        result = {}
+        condition.each do |k, v|
+          key = k.to_s
+          result[key] = case v
+          when Symbol then v.to_s
+          when Array then v.map { |item|
+            case item
+            when Symbol then item.to_s
+            when Hash then stringify_visible_when(item)
+            else item
+            end
+          }
+          when Hash then stringify_visible_when(v)
+          else v
+          end
+        end
+        result
+      end
+    end
+
+    class IndexBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @reorderable_value = nil
+        @layout_value = nil
+        @render_with_value = nil
+        @default_view = nil
+        @default_sort = nil
+        @per_page_value = nil
+        @per_page_options_value = nil
+        @views_available = nil
+        @columns = []
+        @row_click_value = nil
+        @empty_message_value = nil
+        @actions_position_value = nil
+        @includes_list = nil
+        @eager_load_list = nil
+        @description_value = nil
+        @tree_view_value = nil
+        @default_expanded_value = nil
+        @reparentable_value = nil
+        @tile_hash = nil
+        @card_hash = nil
+        @kanban_hash = nil
+        @sort_fields = []
+        @summary_hash = nil
+        @item_classes = []
+        @query_mode_value = nil
+        @group_by_value = nil
+        @having_value = nil
+        @limit_value = nil
+        @default_scope_value = nil
+        @show_record_count_value = nil
+        @pagination_ends_value = nil
+      end
+
+      def reorderable(value = true)
+        @reorderable_value = value
+      end
+
+      def render_with(partial)
+        @render_with_value = partial.to_s
+      end
+
+      def description(text)
+        @description_value = text
+        @description_source_loc = capture_source_loc
+      end
+
+      def default_view(value)
+        @default_view = value.to_s
+      end
+
+      def default_sort(field, direction = :asc)
+        @default_sort = { "field" => field.to_s, "direction" => direction.to_s }
+      end
+
+      def per_page(value)
+        @per_page_value = value
+      end
+
+      def views_available(*values)
+        @views_available = values.flatten.map(&:to_s)
+      end
+
+      def query_mode(value)
+        @query_mode_value = value.to_s
+      end
+
+      def group_by(fields)
+        @group_by_value = Array(fields).map do |f|
+          if f.is_a?(Hash)
+            HashUtils.stringify_deep(f)
+          else
+            f.to_s
+          end
+        end
+      end
+
+      def having(&block)
+        result = block.call
+        conditions = result.is_a?(Array) ? result : [ result ]
+        @having_value = conditions.map { |h| HashUtils.stringify_deep(h) }
+      end
+
+      def limit(value)
+        @limit_value = value
+      end
+
+      def default_scope(value)
+        @default_scope_value = value.to_s
+      end
+
+      def row_click(value, target: nil)
+        if target
+          @row_click_value = { "mode" => value.to_s, "target" => target.to_s }
+        else
+          @row_click_value = value.to_s
+        end
+      end
+
+      def empty_message(value)
+        @empty_message_value = value
+      end
+
+      def actions_position(value)
+        @actions_position_value = value.to_s
+      end
+
+      def column(field_name, **options)
+        source_loc = capture_source_loc
+        col = { "field" => field_name.to_s }
+        options.each do |k, v|
+          col[k.to_s] = v.is_a?(Symbol) ? v.to_s : HashUtils.stringify_deep(v)
+        end
+        col["_source_loc"] = source_loc if source_loc
+        col["_label_source_loc"] = source_loc if source_loc && options.key?(:label)
+        @columns << col
+      end
+
+      def includes(*assocs)
+        @includes_list = assocs.flatten.map { |a| a.is_a?(Hash) ? HashUtils.stringify_deep(a) : a.to_s }
+      end
+
+      def eager_load(*assocs)
+        @eager_load_list = assocs.flatten.map { |a| a.is_a?(Hash) ? HashUtils.stringify_deep(a) : a.to_s }
+      end
+
+      def tree_view(value = true)
+        @tree_view_value = value
+      end
+
+      def default_expanded(value)
+        @default_expanded_value = value
+      end
+
+      def reparentable(value = true)
+        @reparentable_value = value
+      end
+
+      def layout(value)
+        @layout_value = value.to_s
+      end
+
+      def tile(&block)
+        builder = TileBuilder.new
+        builder.instance_eval(&block)
+        @tile_hash = builder.to_hash
+      end
+
+      def card(&block)
+        builder = CardBuilder.new
+        builder.instance_eval(&block)
+        @card_hash = builder.to_hash
+      end
+
+      def kanban(&block)
+        builder = KanbanBuilder.new
+        builder.instance_eval(&block)
+        @kanban_hash = builder.to_hash
+      end
+
+      def sort_field(field, label: nil)
+        entry = { "field" => field.to_s }
+        if label
+          entry["label"] = label
+          entry["_label_source_loc"] = capture_source_loc
+        end
+        @sort_fields << entry
+      end
+
+      def per_page_options(*values)
+        @per_page_options_value = values.flatten
+      end
+
+      def show_record_count(value = true)
+        @show_record_count_value = value
+      end
+
+      def pagination_ends(value = true)
+        @pagination_ends_value = value
+      end
+
+      def summary(&block)
+        builder = SummaryBuilder.new
+        builder.instance_eval(&block)
+        @summary_hash = builder.to_hash
+      end
+
+      def item_class(classes, **kwargs)
+        condition = kwargs[:when]
+        rule = { "class" => classes.to_s, "when" => HashUtils.stringify_deep(condition) }
+        @item_classes << rule
+      end
+
+      def to_hash
+        hash = {}
+        hash["render_with"] = @render_with_value if @render_with_value
+        hash["layout"] = @layout_value if @layout_value
+        hash["query_mode"] = @query_mode_value if @query_mode_value
+        hash["group_by"] = @group_by_value if @group_by_value
+        hash["having"] = @having_value if @having_value
+        hash["limit"] = @limit_value if @limit_value
+        hash["reorderable"] = @reorderable_value unless @reorderable_value.nil?
+        hash["description"] = @description_value if @description_value
+        hash["_description_source_loc"] = @description_source_loc if @description_source_loc
+        hash["default_view"] = @default_view if @default_view
+        hash["views_available"] = @views_available if @views_available
+        hash["default_sort"] = @default_sort if @default_sort
+        hash["per_page"] = @per_page_value if @per_page_value
+        hash["per_page_options"] = @per_page_options_value if @per_page_options_value
+        hash["show_record_count"] = @show_record_count_value unless @show_record_count_value.nil?
+        hash["pagination_ends"] = @pagination_ends_value unless @pagination_ends_value.nil?
+        hash["table_columns"] = @columns unless @columns.empty?
+        hash["tile"] = @tile_hash if @tile_hash
+        hash["card"] = @card_hash if @card_hash
+        hash["kanban"] = @kanban_hash if @kanban_hash
+        hash["sort_fields"] = @sort_fields unless @sort_fields.empty?
+        hash["summary"] = @summary_hash if @summary_hash
+        hash["row_click"] = @row_click_value if @row_click_value
+        hash["empty_message"] = @empty_message_value if @empty_message_value
+        hash["actions_position"] = @actions_position_value if @actions_position_value
+        hash["includes"] = @includes_list if @includes_list
+        hash["eager_load"] = @eager_load_list if @eager_load_list
+        hash["tree_view"] = @tree_view_value unless @tree_view_value.nil?
+        hash["default_expanded"] = @default_expanded_value unless @default_expanded_value.nil?
+        hash["reparentable"] = @reparentable_value unless @reparentable_value.nil?
+        hash["item_classes"] = @item_classes unless @item_classes.empty?
+        hash["default_scope"] = @default_scope_value if @default_scope_value
+        hash
+      end
+    end
+
+    # Tile-layout-specific configuration. Card zone keys live in the sibling
+    # `card { ... }` block (CardBuilder).
+    class TileBuilder
+      def initialize
+        @hash = {}
+      end
+
+      def columns(value)
+        @hash["columns"] = value
+      end
+
+      def to_hash
+        @hash.dup
+      end
+    end
+
+    # Shared across all card-based layouts (tiles, kanban, future). Resolves
+    # to `index_config["card"]`; consumed by LcpRuby::Display::CardHelper.
+    class CardBuilder
+      def initialize
+        @hash = {}
+        @fields = []
+      end
+
+      def title_field(name)
+        @hash["title_field"] = name.to_s
+      end
+
+      def subtitle_field(name, renderer: nil, options: nil)
+        @hash["subtitle_field"] = name.to_s
+        @hash["subtitle_renderer"] = renderer.to_s if renderer
+        @hash["subtitle_options"] = HashUtils.stringify_deep(options) if options
+      end
+
+      def description_field(name, max_lines: nil)
+        @hash["description_field"] = name.to_s
+        @hash["description_max_lines"] = max_lines if max_lines
+      end
+
+      def image_field(name, alt: nil)
+        @hash["image_field"] = name.to_s
+        @hash["image_alt_field"] = alt.to_s if alt
+      end
+
+      def avatar_field(name, alt: nil)
+        @hash["avatar_field"] = name.to_s
+        @hash["avatar_alt_field"] = alt.to_s if alt
+      end
+
+      def color_field(name, map: nil)
+        @hash["color_field"] = name.to_s
+        @hash["color_map"] = HashUtils.stringify_deep(map) if map
+      end
+
+      def actions(value)
+        @hash["actions"] = value.to_s
+      end
+
+      def render_with(partial)
+        @hash["render_with"] = partial.to_s
+      end
+
+      def field(name, **options)
+        f = { "field" => name.to_s }
+        options.each do |k, v|
+          f[k.to_s] = v.is_a?(Symbol) ? v.to_s : HashUtils.stringify_deep(v)
+        end
+        @fields << f
+      end
+
+      def to_hash
+        result = @hash.dup
+        result["fields"] = @fields unless @fields.empty?
+        result
+      end
+    end
+
+    # Kanban-layout-specific configuration. Card zone keys live in the sibling
+    # `card { ... }` block (CardBuilder). See docs/design/kanban_view.md.
+    class KanbanBuilder
+      def initialize
+        @hash = {}
+      end
+
+      # Accepts a Class (autoload-safe) or a String. Stores the class name; the
+      # validator and controller resolve via safe_constantize at boot/request time.
+      def provider(class_or_string)
+        @hash["provider"] = class_or_string.is_a?(String) ? class_or_string : class_or_string.name
+      end
+
+      def group_by(name)
+        @hash["group_by"] = name.to_s
+      end
+
+      def column_order(*values)
+        @hash["column_order"] = values.flatten.map { |v| v.is_a?(Symbol) ? v.to_s : v }
+      end
+
+      def cards_per_column(value)
+        @hash["cards_per_column"] = value
+      end
+
+      def within_column_order(expression)
+        @hash["within_column_order"] = expression.to_s
+      end
+
+      def show_null_column(value = true)
+        @hash["show_null_column"] = value
+      end
+
+      def to_hash
+        @hash.dup
+      end
+    end
+
+    class SummaryBuilder
+      def initialize
+        @enabled_value = true
+        @fields = []
+      end
+
+      def enabled(value = true)
+        @enabled_value = value
+      end
+
+      def field(name, function:, **options)
+        f = { "field" => name.to_s, "function" => function.to_s }
+        f["label"] = options[:label] if options[:label]
+        f["renderer"] = options[:renderer].to_s if options[:renderer]
+        f["options"] = HashUtils.stringify_deep(options[:options]) if options[:options]
+        @fields << f
+      end
+
+      def to_hash
+        hash = { "enabled" => @enabled_value }
+        hash["fields"] = @fields unless @fields.empty?
+        hash
+      end
+    end
+
+    class SectionBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @fields = []
+      end
+
+      def field(name, **options)
+        field_hash = { "field" => name.to_s }
+        options.each do |k, v|
+          field_hash[k.to_s] = v.is_a?(Symbol) ? v.to_s : HashUtils.stringify_deep(v)
+        end
+        field_hash["_label_source_loc"] = capture_source_loc if options.key?(:label)
+        @fields << field_hash
+      end
+
+      def divider(label: nil)
+        d = { "type" => "divider" }
+        if label
+          d["label"] = label
+          d["_label_source_loc"] = capture_source_loc
+        end
+        @fields << d
+      end
+
+      def info(text)
+        @fields << { "type" => "info", "text" => text }
+      end
+
+      def to_fields
+        @fields
+      end
+    end
+
+    # Builder for nested_fields blocks that supports both flat fields and sub-sections.
+    # Using both `field` and `section` in the same block is not allowed.
+    class NestedSectionBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @fields = []
+        @sub_sections = []
+      end
+
+      def field(name, **options)
+        if @sub_sections.any?
+          raise ArgumentError, "Cannot mix field and section calls in nested_fields — use one or the other"
+        end
+
+        field_hash = { "field" => name.to_s }
+        options.each do |k, v|
+          field_hash[k.to_s] = v.is_a?(Symbol) ? v.to_s : HashUtils.stringify_deep(v)
+        end
+        @fields << field_hash
+      end
+
+      def section(title = nil, key: nil, columns: nil, collapsible: false, collapsed: false,
+                  visible_when: nil, disable_when: nil, &block)
+        if @fields.any?
+          raise ArgumentError, "Cannot mix field and section calls in nested_fields — use one or the other"
+        end
+        raise ArgumentError, "section requires either a title or key:" if title.nil? && key.nil?
+
+        ss = {}
+        ss["title"] = title if title
+        ss["_label_source_loc"] = capture_source_loc if title
+        ss["section_key"] = key.to_s if key
+        ss["columns"] = columns if columns
+        ss["collapsible"] = collapsible if collapsible
+        ss["collapsed"] = collapsed if collapsed
+        ss["visible_when"] = HashUtils.stringify_deep(visible_when) if visible_when
+        ss["disable_when"] = HashUtils.stringify_deep(disable_when) if disable_when
+
+        if block
+          builder = SectionBuilder.new
+          builder.instance_eval(&block)
+          ss["fields"] = builder.to_fields
+        end
+
+        @sub_sections << ss
+      end
+
+      def has_sub_sections?
+        @sub_sections.any?
+      end
+
+      def to_fields
+        @fields
+      end
+
+      def to_sub_sections
+        @sub_sections
+      end
+    end
+
+    class ShowBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @layout = []
+        @includes_list = nil
+        @eager_load_list = nil
+        @description_value = nil
+        @copy_url_value = nil
+        @render_with_value = nil
+      end
+
+      def description(text)
+        @description_value = text
+        @description_source_loc = capture_source_loc
+      end
+
+      def copy_url(value)
+        @copy_url_value = value
+      end
+
+      def render_with(partial)
+        @render_with_value = partial.to_s
+      end
+
+      def custom_section(title = nil, partial:, key: nil, visible_when: nil)
+        raise ArgumentError, "custom_section requires either a title or key:" if title.nil? && key.nil?
+        entry = {
+          "type" => "custom",
+          "partial" => partial.to_s
+        }
+        entry["section"] = title if title
+        entry["section_key"] = key.to_s if key
+        entry["visible_when"] = stringify_deep(visible_when) if visible_when
+        @layout << entry
+      end
+
+      def section(title = nil, key: nil, columns: 1, description: nil, responsive: nil,
+                  visible_when: nil, disable_when: nil,
+                  type: nil, association: nil, &block)
+        raise ArgumentError, "section requires either a title or key:" if title.nil? && key.nil?
+        section_hash = { "columns" => columns }
+        section_hash["section"] = title if title
+        section_hash["_label_source_loc"] = capture_source_loc if title
+        section_hash["section_key"] = key.to_s if key
+        section_hash["type"] = type.to_s if type
+        section_hash["association"] = association.to_s if association
+        section_hash["description"] = description if description
+        section_hash["responsive"] = stringify_deep(responsive) if responsive
+        section_hash["visible_when"] = stringify_deep(visible_when) if visible_when
+        section_hash["disable_when"] = stringify_deep(disable_when) if disable_when
+        if block
+          builder = SectionBuilder.new
+          builder.instance_eval(&block)
+          section_hash["fields"] = builder.to_fields
+        end
+        @layout << section_hash
+      end
+
+      def json_items_list(title = nil, json_field:, key: nil, target_model: nil, columns: nil,
+                          empty_message: nil, visible_when: nil, disable_when: nil, &block)
+        raise ArgumentError, "json_items_list requires either a title or key:" if title.nil? && key.nil?
+        entry = {
+          "type" => "json_items_list",
+          "json_field" => json_field.to_s
+        }
+        entry["section"] = title if title
+        entry["section_key"] = key.to_s if key
+        entry["target_model"] = target_model.to_s if target_model
+        entry["columns"] = columns if columns
+        entry["empty_message"] = empty_message if empty_message
+        entry["visible_when"] = stringify_deep(visible_when) if visible_when
+        entry["disable_when"] = stringify_deep(disable_when) if disable_when
+        if block
+          builder = NestedSectionBuilder.new
+          builder.instance_eval(&block)
+          if builder.has_sub_sections?
+            entry["sub_sections"] = builder.to_sub_sections
+          else
+            entry["fields"] = builder.to_fields
+          end
+        end
+        @layout << entry
+      end
+
+      def association_list(title = nil, association:, key: nil, display_template: nil, link: nil, link_through: nil,
+                                sort: nil, limit: nil, empty_message: nil, scope: nil,
+                                visible_when: nil, disable_when: nil)
+        raise ArgumentError, "association_list requires either a title or key:" if title.nil? && key.nil?
+        entry = {
+          "type" => "association_list",
+          "association" => association.to_s
+        }
+        entry["section"] = title if title
+        entry["section_key"] = key.to_s if key
+        entry["display_template"] = display_template.to_s if display_template
+        entry["link"] = link unless link.nil?
+        entry["link_through"] = link_through.to_s if link_through
+        entry["sort"] = stringify_deep(sort) if sort
+        entry["limit"] = limit if limit
+        entry["empty_message"] = empty_message if empty_message
+        entry["scope"] = scope.to_s if scope
+        entry["visible_when"] = stringify_deep(visible_when) if visible_when
+        entry["disable_when"] = stringify_deep(disable_when) if disable_when
+        @layout << entry
+      end
+
+      def includes(*assocs)
+        @includes_list = assocs.flatten.map { |a| a.is_a?(Hash) ? HashUtils.stringify_deep(a) : a.to_s }
+      end
+
+      def eager_load(*assocs)
+        @eager_load_list = assocs.flatten.map { |a| a.is_a?(Hash) ? HashUtils.stringify_deep(a) : a.to_s }
+      end
+
+      def to_hash
+        hash = {}
+        hash["description"] = @description_value if @description_value
+        hash["_description_source_loc"] = @description_source_loc if @description_source_loc
+        hash["copy_url"] = @copy_url_value unless @copy_url_value.nil?
+        hash["render_with"] = @render_with_value if @render_with_value
+        hash["layout"] = @layout
+        hash["includes"] = @includes_list if @includes_list
+        hash["eager_load"] = @eager_load_list if @eager_load_list
+        hash
+      end
+
+      private
+
+      def stringify_deep(value)
+        HashUtils.stringify_deep(value)
+      end
+    end
+
+    class FormBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @sections = []
+        @layout_value = nil
+        @includes_list = nil
+        @eager_load_list = nil
+        @description_value = nil
+      end
+
+      def description(text)
+        @description_value = text
+        @description_source_loc = capture_source_loc
+      end
+
+      def layout(value)
+        @layout_value = value.to_s
+      end
+
+      def custom_section(title = nil, partial:, key: nil, visible_when: nil, additional_permitted_params: nil)
+        raise ArgumentError, "custom_section requires either a title or key:" if title.nil? && key.nil?
+        section_hash = {
+          "type" => "custom",
+          "partial" => partial.to_s
+        }
+        section_hash["title"] = title if title
+        section_hash["section_key"] = key.to_s if key
+        section_hash["visible_when"] = stringify_deep(visible_when) if visible_when
+        if additional_permitted_params
+          section_hash["additional_permitted_params"] = additional_permitted_params.map do |p|
+            p.is_a?(Hash) ? stringify_deep(p) : p.to_s
+          end
+        end
+        @sections << section_hash
+      end
+
+      def section(title = nil, key: nil, columns: 1, description: nil, responsive: nil, collapsible: false, collapsed: false,
+                  visible_when: nil, disable_when: nil, &block)
+        raise ArgumentError, "section requires either a title or key:" if title.nil? && key.nil?
+        section_hash = { "columns" => columns }
+        section_hash["title"] = title if title
+        section_hash["_label_source_loc"] = capture_source_loc if title
+        section_hash["section_key"] = key.to_s if key
+        section_hash["description"] = description if description
+        section_hash["responsive"] = stringify_deep(responsive) if responsive
+        section_hash["collapsible"] = collapsible if collapsible
+        section_hash["collapsed"] = collapsed if collapsed
+        section_hash["visible_when"] = stringify_deep(visible_when) if visible_when
+        section_hash["disable_when"] = stringify_deep(disable_when) if disable_when
+        if block
+          builder = SectionBuilder.new
+          builder.instance_eval(&block)
+          section_hash["fields"] = builder.to_fields
+        end
+        @sections << section_hash
+      end
+
+      def nested_fields(title = nil, association: nil, json_field: nil, target_model: nil,
+                        key: nil, description: nil, allow_add: true, allow_remove: true,
+                        min: nil, max: nil, add_label: nil, empty_message: nil,
+                        sortable: false, columns: nil, visible_when: nil, disable_when: nil, &block)
+        if association && json_field
+          raise ArgumentError, "nested_fields cannot have both association: and json_field:"
+        end
+        unless association || json_field
+          raise ArgumentError, "nested_fields requires either association: or json_field:"
+        end
+
+        section_hash = {
+          "type" => "nested_fields",
+          "allow_add" => allow_add,
+          "allow_remove" => allow_remove
+        }
+        section_hash["title"] = title if title
+        section_hash["section_key"] = key.to_s if key
+        section_hash["association"] = association.to_s if association
+        section_hash["json_field"] = json_field.to_s if json_field
+        section_hash["target_model"] = target_model.to_s if target_model
+        section_hash["description"] = description if description
+        section_hash["columns"] = columns if columns
+        section_hash["min"] = min if min
+        section_hash["max"] = max if max
+        section_hash["add_label"] = add_label if add_label
+        section_hash["empty_message"] = empty_message if empty_message
+        section_hash["sortable"] = sortable if sortable
+        section_hash["visible_when"] = stringify_deep(visible_when) if visible_when
+        section_hash["disable_when"] = stringify_deep(disable_when) if disable_when
+        if block
+          builder = NestedSectionBuilder.new
+          builder.instance_eval(&block)
+          if builder.has_sub_sections?
+            section_hash["sub_sections"] = builder.to_sub_sections
+          else
+            section_hash["fields"] = builder.to_fields
+          end
+        end
+        @sections << section_hash
+      end
+
+      def includes(*assocs)
+        @includes_list = assocs.flatten.map { |a| a.is_a?(Hash) ? HashUtils.stringify_deep(a) : a.to_s }
+      end
+
+      def eager_load(*assocs)
+        @eager_load_list = assocs.flatten.map { |a| a.is_a?(Hash) ? HashUtils.stringify_deep(a) : a.to_s }
+      end
+
+      def to_hash
+        hash = {}
+        hash["description"] = @description_value if @description_value
+        hash["_description_source_loc"] = @description_source_loc if @description_source_loc
+        hash["sections"] = @sections
+        hash["layout"] = @layout_value if @layout_value
+        hash["includes"] = @includes_list if @includes_list
+        hash["eager_load"] = @eager_load_list if @eager_load_list
+        hash
+      end
+
+      private
+
+      def stringify_deep(value)
+        HashUtils.stringify_deep(value)
+      end
+    end
+
+    class SearchBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @enabled = true
+        @searchable_fields_list = nil
+        @placeholder_value = nil
+        @filters = []
+        @auto_search_value = nil
+        @debounce_ms_value = nil
+        @min_query_length_value = nil
+        @default_scope_value = nil
+        @advanced_filter_hash = nil
+        @parameters = []
+        @columns_value = nil
+        @responsive_value = nil
+      end
+
+      def enabled(value)
+        @enabled = value
+      end
+
+      def searchable_fields(*fields)
+        @searchable_fields_list = fields.flatten.map(&:to_s)
+      end
+
+      def placeholder(value)
+        @placeholder_value = value
+        @placeholder_source_loc = capture_source_loc
+      end
+
+      def auto_search(value = true)
+        @auto_search_value = value
+      end
+
+      def debounce_ms(value)
+        @debounce_ms_value = value
+      end
+
+      def min_query_length(value)
+        @min_query_length_value = value
+      end
+
+      def default_scope(value)
+        @default_scope_value = value.to_s
+      end
+
+      def filter(name, label:, default: false, scope: nil)
+        filter_hash = { "name" => name.to_s, "label" => label }
+        filter_hash["_label_source_loc"] = capture_source_loc
+        filter_hash["default"] = true if default
+        filter_hash["scope"] = scope.to_s if scope
+        @filters << filter_hash
+      end
+
+      def columns(value)
+        @columns_value = value
+      end
+
+      def responsive(value)
+        @responsive_value = value
+      end
+
+      def parameter(name, type:, field: nil, **opts)
+        param_hash = { "name" => name.to_s, "type" => type.to_s }
+        param_hash["field"] = field.to_s if field
+        opts.each { |k, v| param_hash[k.to_s] = v.is_a?(Symbol) ? v.to_s : HashUtils.stringify_deep(v) }
+        @parameters << param_hash
+      end
+
+      def advanced_filter(&block)
+        builder = AdvancedFilterBuilder.new
+        builder.instance_eval(&block)
+        @advanced_filter_hash = builder.to_hash
+      end
+
+      def to_hash
+        hash = { "enabled" => @enabled }
+        hash["searchable_fields"] = @searchable_fields_list if @searchable_fields_list
+        hash["placeholder"] = @placeholder_value if @placeholder_value
+        hash["auto_search"] = @auto_search_value unless @auto_search_value.nil?
+        hash["debounce_ms"] = @debounce_ms_value if @debounce_ms_value
+        hash["min_query_length"] = @min_query_length_value if @min_query_length_value
+        hash["default_scope"] = @default_scope_value if @default_scope_value
+        hash["predefined_filters"] = @filters unless @filters.empty?
+        hash["columns"] = @columns_value if @columns_value
+        hash["responsive"] = HashUtils.stringify_deep(@responsive_value) if @responsive_value
+        hash["parameters"] = @parameters unless @parameters.empty?
+        hash["advanced_filter"] = @advanced_filter_hash if @advanced_filter_hash
+        hash
+      end
+    end
+
+    class AdvancedFilterBuilder
+      include SourceLocationCapture
+
+      def initialize
+        @hash = { "enabled" => true }
+      end
+
+      def enabled(value)
+        @hash["enabled"] = value
+      end
+
+      def max_conditions(value)
+        @hash["max_conditions"] = value
+      end
+
+      def max_association_depth(value)
+        @hash["max_association_depth"] = value
+      end
+
+      def default_combinator(value)
+        @hash["default_combinator"] = value.to_s
+      end
+
+      def allow_or_groups(value)
+        @hash["allow_or_groups"] = value
+      end
+
+      def query_language(value)
+        @hash["query_language"] = value
+      end
+
+      def max_nesting_depth(value)
+        @hash["max_nesting_depth"] = value
+      end
+
+      def filterable_fields(*fields)
+        @hash["filterable_fields"] = fields.flatten.map(&:to_s)
+      end
+
+      def filterable_fields_except(*fields)
+        @hash["filterable_fields_except"] = fields.flatten.map(&:to_s)
+      end
+
+      def field_options(name, operators: nil)
+        @hash["field_options"] ||= {}
+        opts = {}
+        opts["operators"] = operators.map(&:to_s) if operators
+        @hash["field_options"][name.to_s] = opts
+      end
+
+      def preset(name, label:, conditions:)
+        @hash["presets"] ||= []
+        @hash["presets"] << {
+          "name" => name.to_s,
+          "label" => label,
+          "_label_source_loc" => capture_source_loc,
+          "conditions" => conditions.map { |c| c.transform_keys(&:to_s) }
+        }
+      end
+
+      def saved_filters(&block)
+        builder = SavedFiltersBuilder.new
+        builder.instance_eval(&block)
+        @hash["saved_filters"] = builder.to_hash
+      end
+
+      def to_hash
+        @hash
+      end
+    end
+
+    class SavedFiltersBuilder
+      def initialize
+        @hash = {}
+      end
+
+      def enabled(value)
+        @hash["enabled"] = value
+      end
+
+      def display(value)
+        @hash["display"] = value.to_s
+      end
+
+      def max_visible_pinned(value)
+        @hash["max_visible_pinned"] = value
+      end
+
+      def to_hash
+        @hash
+      end
+    end
+  end
+end