dtb 1.0.0.rc1

data/lib/dtb/has_default_implementation.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "errors"
+
+module DTB
+  # Provides a base implementation for running a Query, which can be expanded on
+  # by extending the #run method.
+  #
+  # In their simplest form, queries provide a default scope, and then all
+  # filters, and columns are applied automatically on top.
+  #
+  # If a query does not provide a default scope, then it should override the run
+  # method to craft the query, which might be required for more complex queries.
+  #
+  # @example Defining a default_scope on a query
+  #   class OrdersQuery < DTB::Query
+  #     default_scope { Current.user.orders }
+  #
+  #     column :number, ->(scope) { scope.select(:number, :id) }
+  #     column :buyer, ->(scope) { scope.select(:buyer_id).includes(:buyer) }
+  #     # ...
+  #   end
+  #
+  # @example Overwriting the #run method for more control
+  #   class OrdersQuery < DTB::Query
+  #     column :number, ->(scope) { scope.select(:number, :id) }
+  #     column :buyer, ->(scope) { scope.select(:buyer_id).includes(:buyer) }
+  #     # ...
+  #
+  #     def run
+  #       scope = Current.user.orders
+  #       scope = columns.call(scope)
+  #       scope = filters.call(scope)
+  #       scope
+  #     end
+  #   end
+  #
+  module HasDefaultImplementation
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Define the default scope for this query.
+      #
+      # @yield a block that should return an initial scope for the query.
+      # @yieldreturn [Object] an object compatible with your
+      #   {QueryBuilder} proc's input.
+      # @return [void]
+      def default_scope(&block)
+        @default_scope = block if block
+        @default_scope
+      end
+    end
+
+    # @return [Object, nil] the default scope defined for this query, if any.
+    def default_scope
+      self.class.default_scope
+    end
+
+    # Runs the query, returning the result of applying all the query builders on
+    # top of the default scope.
+    #
+    # @return [Object] the result of running the query.
+    # @raise {NotImplementedError} if no default scope is defined.
+    def run
+      if default_scope
+        instance_exec(&default_scope)
+      else
+        fail DTB::NotImplementedError, <<~ERROR
+          Either add a `default_scope` to your Query to apply all columns and
+          filters by default, or override the `#run` method to manually build
+          the query from the respective atoms.
+        ERROR
+      end
+    end
+  end
+end

data/lib/dtb/has_empty_state.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "empty_state"
+require_relative "has_options"
+
+module DTB
+  # This mixin provides access to {EmptyState empty state configuration} to both
+  # queries and data tables.
+  #
+  # @example Configuring a default partial to render empty states
+  #   class ApplicationQuery < DTB::Query
+  #     options[:empty_state][:render_with] = "data_tables/empty_state"
+  #   end
+  #
+  # @example Rendering the empty state of a data table
+  #   <% if data_table.empty? %>
+  #     <%= render data_table.empty_state.renderer(data_table: data_table) %>
+  #   <% end %>
+  #
+  # @example A sample default empty state partial
+  #   <div class="empty_state">
+  #     <h2><%= empty_state.title %><h2>
+  #     <p><%= empty_state.explanation %></p>
+  #
+  #     <% if data_table.filtered? %>
+  #       <p><%= empty_state.update_filters %></p>
+  #     <% end %>
+  #   <div>
+  module HasEmptyState
+    extend ActiveSupport::Concern
+    include HasOptions
+
+    included do
+      # @!group Options
+
+      # @!attribute [rw] empty_state
+      #   @return [OptionsMap] a set of options for handling the empty state.
+      #   @see EmptyState
+      nested_options :empty_state, EmptyState.options
+
+      # @!endgroup
+    end
+
+    # @return [EmptyState] access information about the empty state to render
+    #   for this query, if there are no results.
+    def empty_state
+      @empty_state ||= EmptyState.new(options[:empty_state].merge(context: self))
+    end
+
+    # (see BuildsDataTable#to_data_table)
+    def to_data_table
+      super.merge(empty_state: empty_state)
+    end
+  end
+end

data/lib/dtb/has_filters.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "builds_data_table"
+require_relative "filter"
+require_relative "filter_set"
+require_relative "has_default_implementation"
+require_relative "has_options"
+require_relative "has_url"
+
+module DTB
+  # This mixin provides {Query Queries} with a set of filter objects that can be
+  # used to modify the query and to render the filters form in the view.
+  # Including this module gives you access to the {.filter} class method, which
+  # you can use to define filters in your query.
+  #
+  # @example (see .filter)
+  module HasFilters
+    extend ActiveSupport::Concern
+    include HasDefaultImplementation
+    include BuildsDataTable
+    include HasOptions
+    include HasUrl
+
+    included do
+      # @!group Options
+
+      # @!attribute [rw] filters
+      #   @return [OptionsMap] a set of options for handling the filters form.
+      #   @see FilterSet
+      nested_options :filters, FilterSet.options
+
+      # @!attribute [rw] default_params
+      #   @return [Hash] the Hash of parameters to use when no filters are
+      #     defined by users.
+      option :default_params, default: {}
+
+      # @!attribute [rw] default_filter_type
+      #   @return [Class<Filter>] the default subclass of {Filter} to use unless
+      #     one is specified.
+      #   @see .filter
+      option :default_filter_type, default: Filter
+
+      # @!endgroup
+    end
+
+    class_methods do
+      # Defines a new Filter that will be added to this Query.
+      #
+      # @example Adding a filter to match the +name+ column to the input value exactly
+      #   filter :name
+      #
+      # @example Adding a filter to find things with a name that contains the value
+      #   filter :name,
+      #     ->(scope, value) { scope.where("name ILIKE ?", "%#{value}%") }
+      #
+      # @example Overriding the type of filter object
+      #   filter :name,
+      #     type: ContainsTextFilter
+      #
+      # @example Overriding the renderer used for a specific filter
+      #   # Instead of rendering "filters/contains_text_filter", this would
+      #   # render "example/partial" in the filters form.
+      #   filter :name,
+      #     type: ContainsTextFilter,
+      #     partial: "example/partial"
+      #
+      # @example Add a filter only if the user has permissions
+      #   filter :name,
+      #     type: ContainsTextFilter,
+      #     if: -> { Current.user.has_permission? }
+      #
+      # @param name [Symbol]
+      # @param query [Proc] The filter's {QueryBuilder} proc. This proc should
+      #   receive two parameters: the query's current +scope+ and the filter's
+      #   +value+ and should return a modified +scope+.
+      #
+      #   By default, this will add a simple
+      #   {https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where +where+} clause
+      #   for matching a column with the same +name+ as the filter having an
+      #   exact match on the proc's input +value+.
+      # @param type [Class<Column>] The type of filter to use. Defaults to
+      #   whatever is set as the {default_filter_type}.
+      # @param opts [Hash] Any other options required by the +type+.
+      # @return [void]
+      def filter(name, query = ->(scope, value) { scope.where(name => value) }, type: options[:default_filter_type], **opts)
+        filter_definitions << {type: type, name: name, query: query, options: opts}
+      end
+
+      # @api private
+      # @return [Array<Hash>]
+      def filter_definitions
+        @filter_definitions ||= []
+      end
+    end
+
+    # @return [Hash] the input parameters including the filters.
+    attr_reader :params
+
+    # @return [FilterSet] the set of filters defined on this object.
+    def filters
+      return @filters if defined?(@filters)
+
+      values = params.fetch(options[:filters][:param], options[:default_params])
+
+      filters = self.class.filter_definitions.map do |dfn|
+        name = dfn[:name]
+        dfn[:type].new(name, value: values[name], context: self, **dfn[:options], &dfn[:query])
+      end
+
+      filter_options = {submit_url: url, reset_url: reset_url}
+        .merge(options[:filters])
+        .compact
+
+      @filters = FilterSet.new(filters, filter_options)
+    end
+
+    # @return [String, nil] the URL to reset the filters and go back to the
+    #   initial state. Defaults to removing the configured {FilterSet#param
+    #   filters' param name} from the query string.
+    def reset_url
+      @filters_reset_url ||= override_query_params(
+        options[:filters][:param] => nil
+      )
+    end
+
+    # @overload initialize(params = {}, options = {})
+    #   @param params [Hash] the Hash of params submitted by the user. These will
+    #     be accessible within the Query as {params}.
+    #   @param options [Hash] the Hash of {options} to configure this object.
+    #   @see HasOptions#initialize
+    def initialize(params = {}, *args, &block)
+      super(*args, &block)
+      @params = params
+    end
+
+    # Applies all defined filters to the query being built.
+    #
+    # @return (see HasDefaultImplementation#run)
+    def run
+      filters.call(super)
+    end
+
+    # (see BuildsDataTable#to_data_table)
+    def to_data_table
+      super.merge(filters: filters)
+    end
+  end
+end

data/lib/dtb/has_i18n.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "i18n"
+
+module DTB
+  # This mixin provides a helper to lookup translations using the I18n gem's
+  # configured backends.
+  #
+  # By default, given a name and namespace, it will look up the translation
+  # under +{namespace}.{name}+. You can also give it a context object, and then
+  # if that object implements +ActiveModel::Translation+, it will first try to
+  # look it up using the +ActiveModel::Translation+ inheritance chain.
+  #
+  # Because {Query} objects implement +ActiveModel::Translation+, all lookups
+  # performed in the context of a Query object will use this strategy. See the
+  # examples below.
+  #
+  # Finally, a default can be provided, and it will be returned if none of the
+  # searched keys contain a translation.
+  #
+  # @example Looking up a translation without a context object
+  #   # Because no context object is given, this will only look for `labels.foo`
+  #   i18n_lookup(:foo, :labels)
+  #
+  # @example Looking up a translation with a plain context object
+  #   # In this case, `context` does not implement `ActiveModel::Translation`,
+  #   # so it will again, only look for `labels.foo`.
+  #   i18n_lookup(:foo, :labels, context: Object.new)
+  #
+  # @example Looking up a translation within a Query object.
+  #   # Queries implement ActiveModel::Translation, and provide a base i18n
+  #   # scope of `queries`. If we have this query object:
+  #   class SomeQuery < DTB::Query
+  #   end
+  #
+  #   # Then this will look up the translation in this priority order:
+  #   #
+  #   #   1. queries.labels.some_query.foo
+  #   #   2. queries.labels.dtb/query.foo
+  #   #   3. labels.foo
+  #   #
+  #   i18n_lookup(:foo, :labels, context: SomeQuery.new)
+  #
+  # @see https://api.rubyonrails.org/classes/ActiveModel/Translation.html
+  module HasI18n
+    extend ActiveSupport::Concern
+
+    # Look for a translation in the configured I18n backend.
+    #
+    # @param name [Symbol] the name of an attribute.
+    # @param namespace [Symbol] a namespace within the i18n sources.
+    # @param default [Object, nil] what to return if the given +name+/+namespace+
+    #   combination isn't found.
+    # @param context [Class<ActiveModel::Translation>, nil] a context object to
+    #   lookup translations following an inheritance chain.
+    # @see https://api.rubyonrails.org/classes/ActiveModel/Translation.html
+    def i18n_lookup(name, namespace, default: nil, context: nil)
+      defaults = []
+
+      if defined?(ActiveModel::Translation) && context.class.is_a?(ActiveModel::Translation)
+        scope = "#{context.class.i18n_scope}.#{namespace}"
+
+        defaults.concat(context.class.lookup_ancestors
+          .map { |klass| :"#{scope}.#{klass.model_name.i18n_key}.#{name}" })
+      end
+
+      defaults << :"#{namespace}.#{name}" << default
+
+      I18n.translate(defaults.shift, default: defaults)
+    end
+  end
+end

data/lib/dtb/has_options.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash/deep_merge"
+require_relative "options_map"
+
+module DTB
+  # Mixin that provides classes with the ability to define options that can be
+  # validated when initializing the object.
+  module HasOptions
+    extend ActiveSupport::Concern
+
+    included do
+      # @!attribute [rw] options
+      #   @return [OptionsMap]
+      class_attribute :options, instance_predicate: false
+
+      self.options = OptionsMap.new
+    end
+
+    class_methods do
+      # Adds a valid option to this class, optionally marking it as required, or
+      # setting a default value.
+      #
+      # @example Defining options
+      #   class SomeObject
+      #     include DTB::HasOptions
+      #
+      #     option :foo, required: true
+      #     option :bar, default: 1
+      #   end
+      #
+      #   obj = SomeObject.new(foo: "test")
+      #   obj.options #=> {foo: "test", bar: 1}
+      #
+      # @param name [Symbol]
+      # @param default The default value.
+      # @param required [Boolean] Whether to validate that the option is set
+      #   when instantiating the object.
+      # @return [void]
+      #
+      # @!macro [attach] option
+      #   @option options $1
+      def option(name, default: OptionsMap::UNSET_OPTION, required: false)
+        self.options = options.define(name, default: default, required: required)
+      end
+
+      # Adds a set of nested options to this class, matching a nested schema.
+      #
+      # @example Defining nested options
+      #   class Component
+      #     include DTB::HasOptions
+      #
+      #     option :foo
+      #     option :bar, default: "test"
+      #   end
+      #
+      #   class Container
+      #     include DTB::HasOptions
+      #
+      #     option :baz
+      #     nested_options :component, Component.options
+      #   end
+      #
+      #   container = Container.new(baz: 1, component: {foo: 2})
+      #   container.options #=> {baz: 1, component: {foo: 2, bar: "test"}}
+      #
+      # @param name [Symbol] The name to nest the options under.
+      # @param opts [OptionsMap] A map of options to use as a schema and default
+      #   values.
+      # @return [void]
+      def nested_options(name, opts = OptionsMap.new)
+        self.options = options.nest(name, opts)
+      end
+    end
+
+    # @param opts [Hash] An Options Hash. Options need to conform to the schema
+    #   defined via calls to {.option} and {.nested_options}.
+    # @raise [UnknownOptionsError] if given an option that was not defined via
+    #   {.option} or {.nested_options}.
+    # @raise [MissingOptionsError] if missing an option marked as +required+ via
+    #   {.option}
+    def initialize(opts = {})
+      self.options = options.deep_merge(opts).validate!
+      options.freeze
+    end
+  end
+end

data/lib/dtb/has_url.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "uri"
+require "active_support/concern"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/hash/deep_merge"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/to_query"
+require "rack/utils"
+require_relative "has_options"
+
+module DTB
+  # Allows objects to support having a URL, and provides a modifier method to
+  # change the query params on that URL (or any other URL-like String). This is
+  # useful to set a base URL in the options, and then be able to derive multiple
+  # URLs from that one.
+  module HasUrl
+    extend ActiveSupport::Concern
+    include HasOptions
+
+    included do
+      # @!group Options
+
+      # @!attribute [rw] url
+      #   @return [String, nil] A Base URL
+      #   @see HasFilters
+      option :url
+
+      # @!endgroup
+    end
+
+    def url
+      @url ||= options[:url]
+    end
+
+    # Returns a copy of the given URL (by default, the Base URL set via the
+    # +:url+ option), with overridden query parameters.
+    #
+    # @example Add a query parameter
+    #   object.options[:url] = "/test?foo=1"
+    #   object.override_query_params(bar: 2) #=> "/test?foo=1&bar=2"
+    #
+    # @example Remove query parameters
+    #   object.options[:url] = "/test?foo=1"
+    #   object.override_query_params(foo: nil) #=> "/test"
+    #
+    # @example Override a different URL
+    #   object.override_query_params("/list", foo: 1) #=> "/list?foo=1"
+    #
+    # @param base_url [String, nil] The URL to modify. If +nil+, this method does
+    #   nothing and returns +nil+.
+    # @param query [Hash] A Hash of query parameters to use.
+    # @return [String, nil]
+    def override_query_params(base_url = url, query = {})
+      base_url, query = url, base_url if base_url.is_a?(Hash)
+      return if base_url.nil?
+
+      uri = URI.parse(base_url)
+      params = Rack::Utils.parse_nested_query(uri.query).with_indifferent_access
+      uri.query = params.deep_merge(query).compact.to_query.presence
+      uri.to_s
+    end
+  end
+end

data/lib/dtb/options_map.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/deep_dup"
+require_relative "errors"
+
+module DTB
+  # Extends +Hash+ to allow for a lightweight "schema" of sorts. You can define
+  # which keys are allowed and which keys are required to be present, and then
+  # validate that the Hash meets this criteria.
+  #
+  #   options = OptionsMap.new
+  #   options.define!(:foo, required: true)
+  #   options.define!(:bar, default: 1)
+  #
+  #   options #=> { bar: 1 }
+  #   options.validate! #=> raises MissingOptionsError
+  #
+  #   options.update(foo: 2)
+  #   options.validate! #=> options
+  #
+  # Option Maps can also define "nested" maps of options, by using another
+  # +OptionsMap+ as a template. This is useful for top level objects that accept
+  # options for nested objects.
+  #
+  #   component_options = OptionsMap.new
+  #   component_options.define!(:foo, required: true)
+  #
+  #   top_level_options = OptionsMap.new
+  #   top_level_options.define!(:bar, default: true)
+  #   top_level_options.nest!(:component, component_options)
+  #
+  #   top_level_options.update(bar: false, component: {foo: true})
+  #   top_level_options.validate! #=> top_level_options
+  #
+  # @api private
+  # @see HasOptions
+  class OptionsMap < Hash
+    # @return [Set] The defined valid options.
+    attr_reader :valid_keys
+
+    # @return [Set] The options defined as required.
+    attr_reader :required_keys
+
+    def initialize(*) # :nodoc:
+      super
+      @valid_keys = Set.new
+      @required_keys = Set.new
+      @nested_options = {}
+    end
+
+    def initialize_copy(other) # :nodoc:
+      super
+      @valid_keys = other.valid_keys.dup
+      @required_keys = other.required_keys.dup
+    end
+
+    # Returns a copy of the options map with a new option defined.
+    #
+    # @param (see #define!)
+    # @return [OptionsMap] A new instance.
+    #
+    # @see HasOptions#option
+    def define(name, default: UNSET_OPTION, required: false)
+      deep_dup.define!(name, default: default, required: required)
+    end
+
+    # Defines a new option in this OptionsMap.
+    #
+    # @param name [Symbol]
+    # @param default [Object] A default value. If given, the options Hash will
+    #   be updated to include this option with this value.
+    # @param required [Boolean]
+    # @return [self]
+    def define!(name, default: UNSET_OPTION, required: false)
+      valid_keys << name
+      required_keys << name if required
+      update(name => default) if default != UNSET_OPTION
+      self
+    end
+
+    # Returns a copy of the options map which allows a nested set of options
+    # that conforms to a specific schema.
+    #
+    # @param (see #nest!)
+    # @return [OptionsMap] A new instance.
+    #
+    # @see HasOptions#nested_options
+    def nest(name, options = self.class.new)
+      deep_dup.nest!(name, options)
+    end
+
+    # Defines a new set of nested options.
+    #
+    # @example
+    #
+    #   component_options = OptionsMap.new
+    #   component_options.define!(:foo)
+    #   component_options.define!(:bar)
+    #
+    #   top_level_options = OptionsMap.new
+    #   top_level_options.define!(:qux)
+    #   top_level_options.nest!(:nested, component_options)
+    #
+    #   top_level_options.update(qux: 1, nested: {foo: 2, bar: 3})
+    #
+    # @param name [Symbol]
+    # @param options [OptionsMap] The schema for the nested options.
+    # @return [self]
+    def nest!(name, options = self.class.new)
+      valid_keys << name
+      @nested_options[name] = options
+      self[name] = options.deep_dup
+      self
+    end
+
+    # Enforces that all keys are defined as an option or nested options, that
+    # the required keys are all defined (irrespective of their value), and that
+    # all nested options hashes are equally valid.
+    #
+    # @return [self]
+    # @raise [UnknownOptionsError] if the Hash has any key that wasn't defined
+    #   as an option, or if any nested options Hash has this problem.
+    # @raise [MissingOptionsError] if any of the required keys aren't defined or
+    #   if any nested options Hash has this problem.
+    def validate!
+      fail UnknownOptionsError.new(self) if (keys.to_set - valid_keys).any?
+      fail MissingOptionsError.new(self) if (required_keys & keys) != required_keys
+
+      @nested_options.each do |key, schema|
+        options = self[key]
+        options = schema.merge(self[key]) unless options.respond_to?(:validate!)
+        options.validate!
+      end
+
+      self
+    end
+
+    # The default value for an option, which can be ignored. This allows specifying
+    # +nil+ as a valid default.
+    #
+    # @example
+    #     options = OptionsMap.new
+    #     options.define!(:foo, required: true)
+    #     options.define!(:bar, default: nil)
+    #     options #=> {bar: nil}
+    #
+    UNSET_OPTION = Object.new
+  end
+end