forest_admin_datasource_customizer 1.15.2 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5fccaec1c5eb87a11da4d020ba35ce4c44e0ca32b144e13d2630931f98b3a9a
-  data.tar.gz: 13556c1d9ea603bc48acfa475023436b0736b8c26f202933193e27224543bcd3
+  metadata.gz: 3540f2fae58db61afffd231a97a223103cc7e9c05c7ce91310a119fc1338ffd2
+  data.tar.gz: 7b885c7eb13546cd8cdf740951598251e0288483db93df84351574294b8a4c5b
 SHA512:
-  metadata.gz: 76797ecde75f6753b1ec0e1e09afa18a9bc4f26dd1d37d82d17b4a100dda0e7de1fbc826649e3a6417d9f3fe9d51646ea2f3818c36ea14452d2bf291d7ffba7c
-  data.tar.gz: 1001aaa27f0f3ee65c124fbbb97a902b8783fd53854667dcc9620dc1a15ab8d564ef071cded27651eb63c1846ca0d5f05a42af51b02f2bd6813def824ac405d3
+  metadata.gz: 8257cf2500f96bbd7c04a91c63427f2546cc8ceb98542a42f07745a83bc6e71717a0df0bddba8675c60d81b0b6238ae80913fa042aa7bd0ff5d594c8825785f6
+  data.tar.gz: 9275c5c61c2fe517c2848a01295dec3383ca7e84d03a80d1e31b30ee459c9229384da056d1586a66ca3776e6f16444d92a732465af67b6aae3c12de8af81a3c7

data/lib/forest_admin_datasource_customizer/collection_customizer.rb

@@ -1,6 +1,7 @@
 module ForestAdminDatasourceCustomizer
   class CollectionCustomizer
     include ForestAdminDatasourceToolkit::Validations
+    include DSL::CollectionHelpers
     attr_reader :datasource_customizer, :stack, :name
 
     def initialize(datasource_customizer, stack, name)

data/lib/forest_admin_datasource_customizer/datasource_customizer.rb

@@ -1,5 +1,6 @@
 module ForestAdminDatasourceCustomizer
   class DatasourceCustomizer
+    include DSL::DatasourceHelpers
     attr_reader :stack, :datasources
 
     def initialize(_db_config = {})
@@ -60,8 +61,8 @@ module ForestAdminDatasourceCustomizer
       push_customization { plugin.new.run(self, nil, options) }
     end
 
-    def customize_collection(name, handle)
-      handle.call(get_collection(name))
+    def customize_collection(name)
+      yield(get_collection(name))
     end
 
     def remove_collection(*names)

data/lib/forest_admin_datasource_customizer/dsl/builders/action_builder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module ForestAdminDatasourceCustomizer
+  module DSL
+    # ActionBuilder provides a fluent DSL for building custom actions
+    #
+    # @example Simple action
+    #   action :approve, scope: :bulk do
+    #     execute do
+    #       success "Records approved!"
+    #     end
+    #   end
+    #
+    # @example Action with form
+    #   action :export, scope: :global do
+    #     description "Export all data"
+    #     generates_file!
+    #
+    #     form do
+    #       field :format, type: :string, widget: 'Dropdown',
+    #             options: [{ label: 'CSV', value: 'csv' }]
+    #     end
+    #
+    #     execute do
+    #       format = form_value(:format)
+    #       file content: generate_csv, name: "export.#{format}"
+    #     end
+    #   end
+    class ActionBuilder
+      def initialize(scope:)
+        @scope = normalize_scope(scope)
+        @form_fields = nil
+        @execute_block = nil
+        @description = nil
+        @submit_button_label = nil
+        @generate_file = false
+      end
+
+      # Set the action description
+      # @param text [String] description text
+      def description(text)
+        @description = text
+      end
+
+      # Set custom submit button label
+      # @param label [String] button label
+      def submit_button_label(label)
+        @submit_button_label = label
+      end
+
+      # Mark action as generating a file
+      def generates_file!
+        @generate_file = true
+      end
+
+      # Define the action form using FormBuilder DSL
+      # @param block [Proc] block to build the form
+      def form(&block)
+        form_builder = FormBuilder.new
+        form_builder.instance_eval(&block)
+        @form_fields = form_builder.fields
+      end
+
+      # Define the action execution logic
+      # The block is executed in the context of an ExecutionContext
+      # which provides helper methods like success, error, file, etc.
+      #
+      # @param block [Proc] execution block
+      def execute(&block)
+        @execute_block = proc do |context, result_builder|
+          executor = ExecutionContext.new(context, result_builder)
+          executor.instance_eval(&block)
+          executor.result
+        end
+      end
+
+      # Build and return the BaseAction instance
+      # @return [Decorators::Action::BaseAction] the action
+      def to_action
+        raise ArgumentError, 'execute block is required' unless @execute_block
+
+        Decorators::Action::BaseAction.new(
+          scope: @scope,
+          form: @form_fields,
+          is_generate_file: @generate_file,
+          description: @description,
+          submit_button_label: @submit_button_label,
+          &@execute_block
+        )
+      end
+
+      private
+
+      # Normalize scope symbols to ActionScope constants
+      # @param scope [String, Symbol] the scope
+      # @return [String] normalized scope
+      def normalize_scope(scope)
+        scope_map = {
+          single: Decorators::Action::Types::ActionScope::SINGLE,
+          bulk: Decorators::Action::Types::ActionScope::BULK,
+          global: Decorators::Action::Types::ActionScope::GLOBAL
+        }
+
+        return scope if scope.is_a?(String) && scope_map.value?(scope)
+
+        scope_sym = scope.to_s.downcase.to_sym
+        scope_map[scope_sym] || raise(ArgumentError, "Invalid scope: #{scope}")
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_customizer/dsl/builders/chart_builder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module ForestAdminDatasourceCustomizer
+  module DSL
+    # ChartBuilder provides a fluent DSL for building charts
+    #
+    # @example Simple value chart
+    #   chart :total_revenue do
+    #     value 12345
+    #   end
+    #
+    # @example Chart with previous value
+    #   chart :monthly_sales do
+    #     value 784, 760
+    #   end
+    #
+    # @example Distribution chart
+    #   chart :status_breakdown do
+    #     distribution({ 'Active' => 150, 'Inactive' => 50 })
+    #   end
+    class ChartBuilder
+      def initialize(context, result_builder)
+        @context = context
+        @result_builder = result_builder
+      end
+
+      # Access the context
+      attr_reader :context
+
+      # Return a simple value chart
+      # @param current [Numeric] current value
+      # @param previous [Numeric] previous value (optional)
+      def value(current, previous = nil)
+        if previous
+          @result_builder.value(current, previous)
+        else
+          @result_builder.value(current)
+        end
+      end
+
+      # Return a distribution chart
+      # @param data [Hash] distribution data
+      # @example
+      #   distribution({ 'Category A' => 10, 'Category B' => 20 })
+      def distribution(data)
+        @result_builder.distribution(data)
+      end
+
+      # Return an objective chart
+      # @param current [Numeric] current value
+      # @param target [Numeric] target value
+      # @example
+      #   objective 235, 300
+      def objective(current, target)
+        @result_builder.objective(current, target)
+      end
+
+      # Return a percentage chart
+      # @param value [Numeric] percentage value
+      # @example
+      #   percentage 75.5
+      def percentage(value)
+        @result_builder.percentage(value)
+      end
+
+      # Return a time-based chart
+      # @param data [Array<Hash>] time series data
+      # @example
+      #   time_based([
+      #     { label: 'Jan', values: { sales: 100 } },
+      #     { label: 'Feb', values: { sales: 150 } }
+      #   ])
+      def time_based(data)
+        @result_builder.time_based(data)
+      end
+
+      # Return a leaderboard chart
+      # @param data [Array<Hash>] leaderboard data
+      # @example
+      #   leaderboard([
+      #     { key: 'User 1', value: 100 },
+      #     { key: 'User 2', value: 90 }
+      #   ])
+      def leaderboard(data)
+        @result_builder.leaderboard(data)
+      end
+
+      # Smart chart - automatically detects the best chart type
+      # @param data [Hash, Array, Numeric] chart data
+      # @example
+      #   smart 1234
+      #   smart({ 'A' => 10, 'B' => 20 })
+      def smart(data)
+        @result_builder.smart(data)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_customizer/dsl/builders/form_builder.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ForestAdminDatasourceCustomizer
+  module DSL
+    # FormBuilder provides a fluent DSL for building action forms
+    #
+    # @example
+    #   form do
+    #     field :email, type: :string, widget: 'TextInput'
+    #     field :age, type: :number
+    #     field :photo, type: :file
+    #
+    #     page do
+    #       field :address, type: :string
+    #       field :city, type: :string
+    #     end
+    #   end
+    class FormBuilder
+      attr_reader :fields
+
+      def initialize
+        @fields = []
+      end
+
+      # Add a field to the form
+      # @param name [String, Symbol] field name
+      # @param type [String, Symbol] field type (:string, :number, :boolean, :date, :file, etc.)
+      # @param widget [String] optional widget type
+      # @param options [Array<Hash>] options for dropdown/radio widgets
+      # @param readonly [Boolean] whether field is read-only
+      # @param default [Object] default value
+      # @param description [String] field description
+      # @param placeholder [String] placeholder text
+      # @param block [Proc] optional proc for computed values
+      def field(name, type:, widget: nil, options: nil, readonly: false, default: nil,
+                description: nil, placeholder: nil, &block)
+        field_def = {
+          label: name.to_s,
+          type: normalize_type(type)
+        }
+
+        field_def[:widget] = widget if widget
+        field_def[:options] = options if options
+        field_def[:is_read_only] = readonly if readonly
+        field_def[:default_value] = default if default
+        field_def[:description] = description if description
+        field_def[:placeholder] = placeholder if placeholder
+        field_def[:value] = block if block
+
+        @fields << field_def
+      end
+
+      # Add a page layout to group fields
+      # @param block [Proc] block containing nested fields
+      def page(&block)
+        page_builder = FormBuilder.new
+        page_builder.instance_eval(&block)
+
+        @fields << {
+          type: 'Layout',
+          component: 'Page',
+          elements: page_builder.fields
+        }
+      end
+
+      # Add a row layout to arrange fields horizontally
+      # @param block [Proc] block containing nested fields
+      def row(&block)
+        row_builder = FormBuilder.new
+        row_builder.instance_eval(&block)
+
+        @fields << {
+          type: 'Layout',
+          component: 'Row',
+          fields: row_builder.fields
+        }
+      end
+
+      # Add a separator
+      def separator
+        @fields << { type: 'Layout', component: 'Separator' }
+      end
+
+      # Add a HTML block
+      # @param content [String] HTML content
+      def html(content)
+        @fields << {
+          type: 'Layout',
+          component: 'HtmlBlock',
+          content: content
+        }
+      end
+
+      private
+
+      # Normalize type symbols to Forest Admin type strings
+      # @param type [String, Symbol] the type
+      # @return [String] normalized type
+      def normalize_type(type)
+        type_map = {
+          string: 'String',
+          number: 'Number',
+          integer: 'Number',
+          boolean: 'Boolean',
+          date: 'Date',
+          datetime: 'Date',
+          time: 'Time',
+          json: 'Json',
+          file: 'File',
+          enum: 'Enum'
+        }
+
+        type_sym = type.to_s.downcase.to_sym
+        type_map[type_sym] || type.to_s
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_customizer/dsl/context/execution_context.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module ForestAdminDatasourceCustomizer
+  module DSL
+    # ExecutionContext provides a cleaner API for action execution blocks
+    # It wraps the context and result_builder to provide direct access to common methods
+    #
+    # @example
+    #   collection.action :export do
+    #     execute do
+    #       format = form_value(:format)
+    #       data = generate_export(format)
+    #       file content: data, name: "export.#{format}"
+    #     end
+    #   end
+    class ExecutionContext
+      attr_reader :context, :result_builder, :result
+
+      def initialize(context, result_builder)
+        @context = context
+        @result_builder = result_builder
+        @result = nil
+      end
+
+      # Access form values by field name
+      # @param key [String, Symbol] the field name
+      # @return [Object] the form field value
+      def form_value(key)
+        @context.get_form_value(key.to_s)
+      end
+
+      # Get a single record (for single actions)
+      # @param fields [Array<String>] fields to retrieve
+      # @return [Hash] the record
+      def record(fields = [])
+        @context.get_record(fields)
+      end
+
+      # Get multiple records (for bulk actions)
+      # @param fields [Array<String>] fields to retrieve
+      # @return [Array<Hash>] the records
+      def records(fields = [])
+        @context.get_records(fields)
+      end
+
+      # Access the datasource for querying other collections
+      # @return [Object] the datasource
+      def datasource
+        @context.datasource
+      end
+
+      # Access caller information (user, permissions, etc.)
+      # @return [Object] the caller context
+      def caller
+        @context.caller
+      end
+
+      # Return a success result
+      # @param message [String] success message
+      # @param invalidated [Array<String>] collections to invalidate
+      # @param html [String] optional HTML content
+      # @return [Hash] the success result
+      def success(message = 'Success', invalidated: nil, html: nil)
+        options = {}
+        options[:invalidated] = invalidated if invalidated && !invalidated.empty?
+        options[:html] = html if html
+
+        @result = @result_builder.success(
+          message: message,
+          options: options
+        )
+      end
+
+      # Return an error result
+      # @param message [String] error message
+      # @param html [String] optional HTML content
+      # @return [Hash] the error result
+      def error(message = 'Error', html: nil)
+        options = {}
+        options[:html] = html if html
+
+        @result = @result_builder.error(
+          message: message,
+          options: options
+        )
+      end
+
+      # Return a file download result
+      # @param content [String] file content
+      # @param name [String] file name
+      # @param mime_type [String] MIME type
+      # @return [Hash] the file result
+      def file(content:, name: 'file', mime_type: 'application/octet-stream')
+        @result = @result_builder.file(
+          content: content,
+          name: name,
+          mime_type: mime_type
+        )
+      end
+
+      # Return a webhook result
+      # @param url [String] webhook URL
+      # @param method [String] HTTP method
+      # @param headers [Hash] HTTP headers
+      # @param body [Hash] request body
+      # @return [Hash] the webhook result
+      def webhook(url, method: 'POST', headers: {}, body: {})
+        @result = @result_builder.webhook(
+          url: url,
+          method: method,
+          headers: headers,
+          body: body
+        )
+      end
+
+      # Return a redirect result
+      # @param path [String] redirect path
+      # @return [Hash] the redirect result
+      def redirect(path)
+        @result = @result_builder.redirect_to(path: path)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_customizer/dsl/helpers/collection_helpers.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require_relative '../builders/chart_builder'
+
+module ForestAdminDatasourceCustomizer
+  module DSL
+    # CollectionHelpers provides Rails-like DSL methods for collection customization
+    # These methods are included in CollectionCustomizer to provide a more idiomatic Ruby API
+    # rubocop:disable Naming/PredicatePrefix
+    module CollectionHelpers
+      # Define a computed field with a cleaner syntax
+      #
+      # @example Simple computed field
+      #   computed_field :full_name, type: 'String', depends_on: [:first_name, :last_name] do |records|
+      #     records.map { |r| "#{r['first_name']} #{r['last_name']}" }
+      #   end
+      #
+      # @example Computed relation
+      #   computed_field :related_items, type: ['RelatedItem'], depends_on: [:id] do |records, context|
+      #     records.map { |r| fetch_related(r['id']) }
+      #   end
+      #
+      # @param name [String, Symbol] field name
+      # @param type [String, Array<String>] field type (or array of types for relations)
+      # @param depends_on [Array<String, Symbol>] fields this computation depends on
+      # @param default [Object] default value
+      # @param enum_values [Array] enum values if type is enum
+      # @param block [Proc] computation block receiving (records, context)
+      def computed_field(name, type:, depends_on: [], default: nil, enum_values: nil, &block)
+        raise ArgumentError, 'Block is required for computed field' unless block
+
+        add_field(
+          name.to_s,
+          Decorators::Computed::ComputedDefinition.new(
+            column_type: type,
+            dependencies: Array(depends_on).map(&:to_s),
+            values: block,
+            default_value: default,
+            enum_values: enum_values
+          )
+        )
+      end
+
+      # Define a custom action with a fluent DSL
+      #
+      # @example Simple action
+      #   action :approve, scope: :single do
+      #     execute do
+      #       success "Approved!"
+      #     end
+      #   end
+      #
+      # @example Action with form
+      #   action :export, scope: :global do
+      #     description "Export all customers"
+      #     generates_file!
+      #
+      #     form do
+      #       field :format, type: :string, widget: 'Dropdown',
+      #             options: [{ label: 'CSV', value: 'csv' }]
+      #     end
+      #
+      #     execute do
+      #       format = form_value(:format)
+      #       file content: generate_csv, name: "export.#{format}"
+      #     end
+      #   end
+      #
+      # @param name [String, Symbol] action name
+      # @param scope [Symbol] action scope (:single, :bulk, :global)
+      # @param block [Proc] action definition block
+      def action(name, scope: :single, &block)
+        raise ArgumentError, 'Block is required for action' unless block
+
+        builder = ActionBuilder.new(scope: scope)
+        builder.instance_eval(&block)
+        add_action(name.to_s, builder.to_action)
+      end
+
+      # Define a segment with a cleaner syntax
+      #
+      # @example Static segment
+      #   segment 'Active users' do
+      #     { field: 'is_active', operator: 'Equal', value: true }
+      #   end
+      #
+      # @example Dynamic segment
+      #   segment 'High value customers' do
+      #     { field: 'lifetime_value', operator: 'GreaterThan', value: 10000 }
+      #   end
+      #
+      # @param name [String] segment name
+      # @param block [Proc] block returning condition tree
+      def segment(name, &block)
+        raise ArgumentError, 'Block is required for segment' unless block
+
+        add_segment(name, &block)
+      end
+
+      # Add a before hook for an operation
+      #
+      # @example
+      #   before :create do |context|
+      #     # Validate or transform data before create
+      #   end
+      #
+      # @param operation [String, Symbol] operation name (:create, :update, :delete, :list, :aggregate)
+      # @param block [Proc] hook handler
+      def before(operation, &block)
+        raise ArgumentError, 'Block is required for before hook' unless block
+
+        add_hook('Before', operation.to_s.capitalize, &block)
+      end
+
+      # Add an after hook for an operation
+      #
+      # @example
+      #   after :create do |context|
+      #     # Send notification after create
+      #   end
+      #
+      # @param operation [String, Symbol] operation name (:create, :update, :delete, :list, :aggregate)
+      # @param block [Proc] hook handler
+      def after(operation, &block)
+        raise ArgumentError, 'Block is required for after hook' unless block
+
+        add_hook('After', operation.to_s.capitalize, &block)
+      end
+
+      # ActiveRecord-style belongs_to relation
+      #
+      # @example
+      #   belongs_to :author, foreign_key: :author_id
+      #
+      # @param name [String, Symbol] relation name
+      # @param collection [String, Symbol] target collection name (defaults to pluralized name)
+      # @param foreign_key [String, Symbol] foreign key field
+      def belongs_to(name, collection: nil, foreign_key: nil)
+        raise ArgumentError, 'Relation name is required for belongs_to' if name.nil? || name.to_s.empty?
+
+        collection_name = collection&.to_s || "#{name}s"
+        foreign_key_name = foreign_key&.to_s || "#{name}_id"
+
+        add_many_to_one_relation(
+          name.to_s,
+          collection_name,
+          { foreign_key: foreign_key_name }
+        )
+      end
+
+      # ActiveRecord-style has_many relation
+      #
+      # @example
+      #   has_many :books, origin_key: :author_id
+      #
+      # @param name [String, Symbol] relation name
+      # @param collection [String, Symbol] target collection name (defaults to name)
+      # @param origin_key [String, Symbol] origin key field
+      # @param foreign_key [String, Symbol] foreign key field (for many-to-many)
+      # @param through [String, Symbol] through collection (for many-to-many)
+      def has_many(name, collection: nil, origin_key: nil, foreign_key: nil, through: nil)
+        raise ArgumentError, 'Relation name is required for has_many' if name.nil? || name.to_s.empty?
+
+        collection_name = collection&.to_s || name.to_s
+
+        if through
+          # Many-to-many relation
+          add_many_to_many_relation(
+            name.to_s,
+            collection_name,
+            through.to_s,
+            {
+              origin_key: origin_key&.to_s,
+              foreign_key: foreign_key&.to_s
+            }.compact
+          )
+        else
+          # One-to-many relation
+          add_one_to_many_relation(
+            name.to_s,
+            collection_name,
+            { origin_key: origin_key&.to_s }.compact
+          )
+        end
+      end
+
+      # ActiveRecord-style has_one relation
+      #
+      # @example
+      #   has_one :profile, origin_key: :user_id
+      #
+      # @param name [String, Symbol] relation name
+      # @param collection [String, Symbol] target collection name (defaults to pluralized name)
+      # @param origin_key [String, Symbol] origin key field
+      def has_one(name, collection: nil, origin_key: nil)
+        raise ArgumentError, 'Relation name is required for has_one' if name.nil? || name.to_s.empty?
+
+        collection_name = collection&.to_s || "#{name}s"
+
+        add_one_to_one_relation(
+          name.to_s,
+          collection_name,
+          { origin_key: origin_key&.to_s }.compact
+        )
+      end
+
+      # Validate a field with a cleaner syntax
+      #
+      # @example Simple validation
+      #   validates :email, :email
+      #   validates :age, :greater_than, 18
+      #
+      # @param field_name [String, Symbol] field name
+      # @param operator [String, Symbol] validation operator
+      # @param value [Object] validation value (optional)
+      def validates(field_name, operator, value = nil)
+        raise ArgumentError, 'Field name is required for validates' if field_name.nil? || field_name.to_s.empty?
+        raise ArgumentError, 'Operator is required for validates' if operator.nil? || operator.to_s.empty?
+
+        # Convert snake_case to PascalCase
+        operator_str = operator.to_s
+                               .split('_')
+                               .map(&:capitalize)
+                               .join
+        add_field_validation(field_name.to_s, operator_str, value)
+      end
+
+      # Hide fields from the schema
+      #
+      # @example
+      #   hide_fields :internal_id, :secret_token
+      #
+      # @param field_names [Array<String, Symbol>] fields to hide
+      def hide_fields(*field_names)
+        raise ArgumentError, 'At least one field name is required for hide_fields' if field_names.empty?
+
+        remove_field(*field_names.map(&:to_s))
+      end
+
+      # Add a chart at the collection level with a cleaner syntax
+      #
+      # @example Simple value chart
+      #   chart :num_records do
+      #     value 1234
+      #   end
+      #
+      # @example Distribution chart
+      #   chart :status_distribution do
+      #     distribution({
+      #       'Active' => 150,
+      #       'Inactive' => 50
+      #     })
+      #   end
+      #
+      # @example Chart with context
+      #   chart :monthly_stats do |context|
+      #     # Access the collection and calculate stats
+      #     value calculated_value
+      #   end
+      #
+      # @param name [String, Symbol] chart name
+      # @param block [Proc] chart definition block
+      def chart(name, &block)
+        raise ArgumentError, 'Block is required for chart' unless block
+
+        add_chart(name.to_s) do |context, result_builder|
+          builder = DSL::ChartBuilder.new(context, result_builder)
+          builder.instance_eval(&block)
+        end
+      end
+    end
+    # rubocop:enable Naming/PredicatePrefix
+  end
+end

data/lib/forest_admin_datasource_customizer/dsl/helpers/datasource_helpers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../builders/chart_builder'
+
+module ForestAdminDatasourceCustomizer
+  module DSL
+    # DatasourceHelpers provides Rails-like DSL methods for datasource-level customization
+    # These methods are included in DatasourceCustomizer to provide a more idiomatic Ruby API
+    module DatasourceHelpers
+      # Add a chart at the datasource level with a cleaner syntax
+      #
+      # @example Simple value chart
+      #   chart :total_users do
+      #     value 1234
+      #   end
+      #
+      # @example Chart with context
+      #   chart :monthly_revenue do |context|
+      #     collection = context.datasource.get_collection('orders')
+      #     total = calculate_revenue(collection)
+      #     value total, previous_total
+      #   end
+      #
+      # @param name [String, Symbol] chart name
+      # @param block [Proc] chart definition block
+      def chart(name, &block)
+        add_chart(name.to_s) do |context, result_builder|
+          builder = ChartBuilder.new(context, result_builder)
+          builder.instance_eval(&block)
+        end
+      end
+
+      # Customize a collection with automatic conversion to string
+      #
+      # @example
+      #   collection :users do |c|
+      #     c.computed_field :full_name, type: 'String' { }
+      #   end
+      #
+      # @param name [String, Symbol] collection name
+      # @param block [Proc] customization block
+      def collection(name, &block)
+        customize_collection(name.to_s, &block)
+      end
+
+      # Hide/remove collections from Forest Admin
+      #
+      # @example
+      #   hide_collections :internal_logs, :debug_info
+      #
+      # @param names [Array<String, Symbol>] collection names to hide
+      def hide_collections(*names)
+        remove_collection(*names.map(&:to_s))
+      end
+
+      # Use a plugin with the datasource
+      # (Keeps existing syntax as it's already clean)
+      #
+      # @example
+      #   plugin MyCustomPlugin, option1: 'value'
+      #
+      # @param plugin_class [Class] plugin class
+      # @param options [Hash] plugin options
+      def plugin(plugin_class, options = {})
+        use(plugin_class, options)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_customizer/dsl.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ForestAdminDatasourceCustomizer
+  # DSL provides helpers for Forest Admin customization
+  # This module contains builder classes and helper methods that make
+  # the Forest Admin API more idiomatic and easier to use
+  module DSL
+  end
+end

data/lib/forest_admin_datasource_customizer/version.rb

@@ -1,3 +1,3 @@
 module ForestAdminDatasourceCustomizer
-  VERSION = "1.15.2"
+  VERSION = "1.16.0"
 end

data/lib/forest_admin_datasource_customizer.rb

@@ -2,6 +2,11 @@ require_relative 'forest_admin_datasource_customizer/version'
 require 'zeitwerk'
 
 loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect('dsl' => 'DSL')
+# Collapse subdirectories to avoid creating nested modules
+loader.collapse("#{__dir__}/forest_admin_datasource_customizer/dsl/builders")
+loader.collapse("#{__dir__}/forest_admin_datasource_customizer/dsl/helpers")
+loader.collapse("#{__dir__}/forest_admin_datasource_customizer/dsl/context")
 loader.setup
 
 module ForestAdminDatasourceCustomizer

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forest_admin_datasource_customizer
 version: !ruby/object:Gem::Version
-  version: 1.15.2
+  version: 1.16.0
 platform: ruby
 authors:
 - Matthieu
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-28 00:00:00.000000000 Z
+date: 2025-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -210,6 +210,13 @@ files:
 - lib/forest_admin_datasource_customizer/decorators/write/write_datasource_decorator.rb
 - lib/forest_admin_datasource_customizer/decorators/write/write_replace/write_customization_context.rb
 - lib/forest_admin_datasource_customizer/decorators/write/write_replace/write_replace_collection_decorator.rb
+- lib/forest_admin_datasource_customizer/dsl.rb
+- lib/forest_admin_datasource_customizer/dsl/builders/action_builder.rb
+- lib/forest_admin_datasource_customizer/dsl/builders/chart_builder.rb
+- lib/forest_admin_datasource_customizer/dsl/builders/form_builder.rb
+- lib/forest_admin_datasource_customizer/dsl/context/execution_context.rb
+- lib/forest_admin_datasource_customizer/dsl/helpers/collection_helpers.rb
+- lib/forest_admin_datasource_customizer/dsl/helpers/datasource_helpers.rb
 - lib/forest_admin_datasource_customizer/plugins/add_external_relation.rb
 - lib/forest_admin_datasource_customizer/plugins/import_field.rb
 - lib/forest_admin_datasource_customizer/plugins/plugin.rb