dtb 1.0.0.rc1

data/lib/dtb/query.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "active_model/naming"
+require "active_model/translation"
+require_relative "builds_data_table"
+require_relative "has_default_implementation"
+require_relative "has_options"
+require_relative "has_columns"
+require_relative "has_filters"
+require_relative "has_empty_state"
+require_relative "renderable"
+
+module DTB
+  # Queries are the base classes that allow you to model both what data is
+  # fetched from the database and how it is rendered to users.
+  #
+  # A Query is nothing more than a collection of filters, columns, and an
+  # initial scope from which to start querying. For example:
+  #
+  #   class Blog::PostsQuery < DTB::Query
+  #     column :title, ->(scope) { scope.select(:title, :id) }
+  #     column :author, ->(scope) { scope.select(:author_id).includes(:author) }
+  #     column :published, ->(scope) { scope.select(:published_at) }
+  #     column :actions, database: false
+  #
+  #     filter :title,
+  #       ->(scope, value) { scope.where("title ILIKE ?", "%#{value}%") }
+  #     filter :published,
+  #       ->(scope, value) { scope.where(published: value) }
+  #
+  #     default_scope { Post.all }
+  #   end
+  #
+  # == Running a Query
+  #
+  # This query would start from +Post.all+, then "apply" all columns, by
+  # modifying the query to add each clause declared in the columns, and finally
+  # look at the input params given when running to decide which filters should
+  # be applied.
+  #
+  # For example, in the below example query, the params include the `title`
+  # filter, but not the `published` filter:
+  #
+  #   Blog::PostsQuery.run(filters: {title: "test"}) #=> #<ActiveRecord::Relation ...>
+  #
+  #   # Given those input parameters, that code is equivalent to this:
+  #   Post.all
+  #     .select(:title, :id)
+  #     .select(:author_id).includes(:author)
+  #     .select(:published_at)
+  #     .where("title ILIKE ?", "%test%")
+  #
+  # == Scoping queries to only return authorized data
+  #
+  # Usually, your queries will be scoped to data visible by a user or account in
+  # your system. If you're using +ActiveSupport::CurrentAttributes+, you could
+  # set your initial scope with this:
+  #
+  #   default_scope { Current.user.posts }
+  #
+  # But if you're not, you will need to have access to the +current_user+ or
+  # whatever you call it. For this, the recommended approach is to implement
+  # a base query object that provides access to this:
+  #
+  #   class ApplicationQuery < DTB::Query
+  #     attr_reader :current_user
+  #
+  #     def initialize(current_user, *args)
+  #       super(*args)
+  #       @current_user = current_user
+  #     end
+  #   end
+  #
+  #   class Blog::PostsQuery < ApplicationQuery
+  #     default_scope { current_user.posts }
+  #   end
+  #
+  # All the Procs (the +default_scope+ and the procs attached to columns and
+  # filters) are evaluated in the context of the Query class itself, so you have
+  # access to its instance methods and variables.
+  #
+  # == Rendering the Query as a Data Table
+  #
+  # DTB can easily turn the Query results into a {DataTable} object, which
+  # provides some basic structure so templates can render this into a table with
+  # all the data, next to a filters panel.
+  #
+  # You can easily turn a Query into a DataTable:
+  #
+  #   DataTable.build(Blog::PostsQuery, {filters: {title: "test"}})
+  #
+  # Check out the {DataTable} documentation for more on how to build and
+  # customize data tables.
+  #
+  # @see HasColumns
+  # @see HasFilters
+  class Query
+    extend ActiveModel::Translation
+    include HasDefaultImplementation
+    include HasOptions
+    include BuildsDataTable
+    include HasColumns
+    include HasFilters
+    include HasUrl
+    include HasEmptyState
+    include Renderable
+
+    # Provide a base scope of +queries+ for translations. Unless overridde,
+    # translations within query objects will be found under
+    # +queries.{namespace}.{query_class}+.
+    #
+    # @see https://api.rubyonrails.org/classes/ActiveModel/Translation.html
+    def self.i18n_scope
+      :queries
+    end
+
+    # Run the query, returning the results.
+    #
+    # @param ... [Array<Object>] Any arguments given will be forwarded to
+    #   #initialize
+    # @return (see #run)
+    def self.run(...)
+      new(...).run
+    end
+
+    # @!method initialize(params = {}, options = {})
+    #   @param params [Hash] Any user-supplied params (such as filters to apply)
+    #   @param options [Hash] Any options to customize this query.
+    #   @raise (see HasOptions#initialize)
+
+    # @!method run
+    #   Runs the query, starting from its default scope, if defined, and
+    #   applying all columns and filters.
+    #
+    #   @return the result of running the query.
+    #   @raise {NotImplementedError} if no default scope is defined.
+
+    # @!method to_data_table
+    #   @return [Hash<Symbol, Object>] a Hash of arguments suitable to pass to
+    #     {DataTable#initialize}
+
+    # (see Renderable#rendering_options)
+    def rendering_options
+      # NOTE: Normally this is exposed through a DataTable, and we don't want to
+      # expose query internals when rendering. You can always override this if
+      # you do want the Query instance available to the Renderer, though.
+      {}
+    end
+  end
+end

data/lib/dtb/query_builder.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative "has_i18n"
+require_relative "has_options"
+
+module DTB
+  # Query builders are the "atoms" of a Query. They specify a specific behavior
+  # scoped to a single part of the query. For example, a column or a filter.
+  # This class is not meant to be used directly, but instead extended with
+  # concrete behavior.
+  #
+  # The central part of a query builder is a Proc that will receive an object
+  # (e.g. an ActiveRecord::Relation) and is expected to return that object,
+  # modified in whatever way the builder is meant to work.
+  #
+  # Query builders have an optional "execution context" (usually an instance of
+  # the {Query} class) which is used to evaluate their Proc, giving it access to
+  # any state / methods in that object.
+  #
+  # The central interface to query builders is the {#call} method, which given a
+  # "scope", will decide if the query builder's Proc should be called, and
+  # either return the result of the Proc, or if it doesn't need to evaluate
+  # itself, will return the input "scope" as is.
+  #
+  # In order to decide whether it should be evaluated, query builders rely on
+  # the {#evaluate?} method and/or the {#render?} method. {#render?} decides if
+  # the atom being defined by this builder is something that should be displayed
+  # back to the user, and {#evaluate?} checks if the Proc should be evaluated or
+  # skipped.
+  #
+  # Normally, something that should not be rendered should not be evaluated, so
+  # the default behavior is that {#evaluate?} depends on {#render?}. However,
+  # you may change this in sub-classes. For a concrete example, if you are not
+  # going to display a column in the table to users, it makes no sense to add
+  # extra data to users.
+  #
+  # @abstract
+  # @see Column
+  # @see Filter
+  class QueryBuilder
+    include HasOptions
+    include HasI18n
+
+    # @!group Options
+
+    # @!attribute [rw] context
+    #   @return [Object, nil] The Object in which the {QueryBuilder}'s proc is
+    #     evaluated.
+    option :context, default: nil
+
+    # @!attribute [rw] if
+    #   @return [Proc] A Proc that returns a Boolean. If it returns +false+ then
+    #     {#call} will skip evaluating the {QueryBuilder}'s proc.
+    option :if, default: -> { true }
+
+    # @!attribute [rw] unless
+    #   @return [Proc] A Proc that returns a Boolean. If it returns +true+ then
+    #     {#call} will skip evaluating the {QueryBuilder}'s proc.
+    option :unless, default: -> { false }
+
+    # @!endgroup
+
+    IDENT = ->(value) { value }
+    private_constant :IDENT
+
+    # @return [Symbol] The name of this QueryBuilder.
+    attr_reader :name
+
+    # @param name [Symbol] The QueryBuilder's name.
+    # @param opts [Hash] Any options that need to be set. See also {HasOptions}.
+    # @yield [scope, ...] The given block will be used by {#call} to modify
+    #   the given input scope
+    # @raise (see HasOptions#initialize)
+    def initialize(name, opts = {}, &query)
+      super(opts)
+      @name = name
+      @query = query
+      @applied = false
+    end
+
+    # Evaluates this QueryBuilder's Proc if necessary, returning either the
+    # input +scope+ or the output of the Proc.
+    #
+    # @param scope [Object] the "query" being built.
+    # @param ... [Array<Object>] Splat of any other params that are accepted by
+    #   this QueryBuilder's Proc.
+    # @return [Object] the modified "query" or the input +scope+.
+    #
+    # @see #evaluate?
+    def call(scope, ...)
+      if evaluate?
+        @applied = true
+        evaluate(scope, ...)
+      else
+        scope
+      end
+    end
+
+    # Evaluates a Proc in the context of this QueryBuilder's +context+, as given
+    # in the options.
+    #
+    # @param args [Array<Object>] Any arguments will be forwarded to the Proc.
+    # @param with [Proc] A Proc. Defaults to this QueryBuilder's main Proc.
+    # @api private
+    def evaluate(*args, with: @query, **opts)
+      options[:context].instance_exec(*args, **opts, &with)
+    end
+
+    # @return [Boolean] Whether this QueryBuilder's Proc has been used or not.
+    def applied?
+      @applied
+    end
+
+    # Whether the Proc should be evaluated or skipped. By default, this depends
+    # on whether the QueryBuilder is meant to be rendered ot not, and on the
+    # +if+ and +unless+ options.
+    #
+    # Subclasses should override this method to provide specific reasons why the
+    # QueryBuilder should be skipped or not.
+    #
+    # @return [Boolean]
+    # @see #render?
+    def evaluate?
+      render?
+    end
+
+    # Whether this QueryBuilder should be displayed in views or not. By default
+    # this depends on the +if+ and +unless+ options.
+    #
+    # Subclasses should override this method to provide specific reasons why the
+    # QueryBuilder should be rendered or not.
+    #
+    # @return [Boolean]
+    # @see #evaluate?
+    def render?
+      evaluate(with: options[:if]) && !evaluate(with: options[:unless])
+    end
+
+    # Finds values in your I18n configuration based on this QueryBuilder's
+    # {name} and {context}.
+    #
+    # @example Looking up strings in the i18n sources
+    #   class SomeQuery
+    #     extend ActiveModel::Translation
+    #
+    #     def self.i18n_scope
+    #       :queries
+    #     end
+    #   end
+    #
+    #   builder = QueryBuilder.new(:builder_name, context: SomeQuery.new)
+    #
+    #   # Assuming the current locale is `en`, this will search for:
+    #   #
+    #   #   en:                                # Current Locale
+    #   #     queries:                         # Context's i18n_scope
+    #   #       labels:                        # Namespace given to this method
+    #   #         some_query:                  # Context's model_name
+    #   #           builder_name: <value>      # This builder's name.
+    #   #
+    #   builder.i18n_lookup(:labels)
+    #
+    # @example i18n_lookup follows the context's inheritance chain
+    #   class BaseQuery
+    #     extend ActiveModel::Translation
+    #
+    #     def self.i18n_scope
+    #       :queries
+    #     end
+    #   end
+    #
+    #   class ConcreteQuery < BaseQuery
+    #   end
+    #
+    #   builder = QueryBuilder.new(:builder_name, context: SomeQuery.new)
+    #
+    #   # Assuming the current locale is `en`, this will first attempt to search
+    #   # for:
+    #   #
+    #   #   en.queries.labels.concrete_query.builder_name
+    #   #
+    #   # And if no translation is declared, will then look up:
+    #   #
+    #   #   en.queries.labels.base_query.builder_name
+    #   #
+    #   builder.i18n_lookup(:labels)
+    #
+    # @param namespace [Symbol] A scope to find I18n values in.
+    # @param default [String, nil] A default value to render if no value is
+    #   found in the i18n sources.
+    #
+    # @see HasI18n#i18n_lookup
+    def i18n_lookup(namespace, default: nil)
+      super(name, namespace, default: default, context: options[:context])
+    end
+  end
+end

data/lib/dtb/query_builder_set.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+require_relative "has_options"
+
+module DTB
+  # These models a set of {QueryBuilder} objects where you can quickly select
+  # sub-sets of query builders or extract individual builders.
+  #
+  # A set can also be evaluated using the method {#call}, which will evaluate
+  # each query builder in the set in turn, using each builder's output as the
+  # next's buidler's input. This allows, for example, applying every filter or
+  # column defined in a query in a single method call.
+  class QueryBuilderSet
+    include HasOptions
+
+    # @!method each(&block)
+    #   Iterate through the builders in the set.
+    #   @yieldparam builder [QueryBuilder] A QueryBuilder
+    #   @return [void]
+
+    # @!method to_a
+    #   @return [Array<QueryBuilder>] an Array with the contents of the set.
+
+    # @!method any?
+    #   @return [Boolean] if the set has at least one {QueryBuilder}.
+
+    # @!method empty?
+    #   @return [Boolean] if the set is empty.
+
+    delegate :each, :to_a, :any?, :empty?, to: :@builders
+
+    # @param builders [Array<QueryBuilder>]
+    # @param opts [Hash] any defined options.
+    # @raise (see HasOptions#initialize)
+    def initialize(builders = [], opts = {})
+      super(opts)
+      @builders = builders
+    end
+
+    # Evaluates every {QueryBuilder} in the set if necessary, passing the return
+    # value of each as input to the next builder's {QueryBuilder#call} method.
+    #
+    # @example Applying multiple builders at once.
+    #
+    #   builder_1 = QueryBuilder.new(...)
+    #   builder_2 = QueryBuilder.new(...)
+    #   builder_3 = QueryBuilder.new(...)
+    #
+    #   builders = QueryBuilderSet.new([builder_1, builder_2, builder_3])
+    #
+    #   # This will evaluate all three builders
+    #   result = builders.call(a_scope)
+    #
+    #   # ...and is equivalent to doing this:
+    #   a_scope = builder_1.call(a_scope)
+    #   a_scope = builder_2.call(a_scope)
+    #   result = builder_3.call(a_scope)
+    #
+    # @param scope (see QueryBuilder#call)
+    # @return (see QueryBuilder#call)
+    #
+    # @see QueryBuilder#call
+    def call(scope)
+      @builders.reduce(scope) { |current, builder| builder.call(current) }
+    end
+
+    # Filters the set to only those {QueryBuilder}s that should be rendered.
+    #
+    # @return [QueryBuilderset] a new set.
+    def renderable
+      self.class.new(@builders.select { |builder| builder.render? }, options)
+    end
+
+    # Filters the set to only those {QueryBuilder}s that have been applied.
+    #
+    # @return [QueryBuilderset] a new set.
+    def applied
+      self.class.new(@builders.select { |builder| builder.applied? }, options)
+    end
+
+    # @param name [Symbol]
+    # @return [QueryBuilder, nil] a single QueryBuilder, by name, if it's
+    #   currently in the set, or +nil+ if it's not.
+    def [](name)
+      @builders.find { |builder| builder.name.to_s == name.to_s }
+    end
+
+    # @param names [Array<Symbol>] Splat of names to filter.
+    # @return [QueryBuilderSet] a subset containing only the builders with the
+    #   names in the input list.
+    def slice(*names)
+      builders = @builders.select do |builder|
+        names.any? { |name| name.to_s == builder.name.to_s }
+      end
+
+      self.class.new(builders, options)
+    end
+
+    # @param names [Array<Symbol>] Splat of names to filter out.
+    # @return [QueryBuilderSet] a subset containing only the builders in this
+    #   set whose name is not in the input list.
+    def except(*names)
+      builders = @builders.reject do |builder|
+        names.any? { |name| name.to_s == builder.name.to_s }
+      end
+      self.class.new(builders, options)
+    end
+  end
+end

data/lib/dtb/renderable.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_model/naming"
+require_relative "has_options"
+
+module DTB
+  # Provides a simple abstraction for rendering components by setting an option
+  # with the object to use for rendering.
+  #
+  # This povides a {#renderer} method that you can pass to ActionView's
+  # +render+, like so:
+  #
+  #   <%= render @object.renderer %>
+  #
+  # == Rendering partials
+  #
+  # In the most basic case, you can pass a string to the +:render_with+ option
+  # to render the component via a partial. When doing so, the return value of
+  # the {#rendering_options} method will be passed as locals.
+  #
+  # @example Rendering via a partial
+  #   class SelectFilter < DTB::Filter
+  #     option :render_with, default: "filters/select_filter"
+  #   end
+  #
+  # In that example, +renderer+ will return a Hash that looks like this:
+  #
+  #   {partial: "filters/select_filter", locals: {filter: <the filter object>}}
+  #
+  # == Rendering components
+  #
+  # If you're using a component library such as ViewComponent or Phlex, you can
+  # pass a component directly to the +:render_with+ option. The component will
+  # be instantiated with the object.
+  #
+  # @example Rendering a ViewComponent
+  #   class SelectFilter < DTB::Filter
+  #     option :render_with, default: SelectFilterComponent
+  #   end
+  #
+  # In that example, calling +renderer+ will be equivalent to insantiating the
+  # component like so:
+  #
+  #   SelectFilterComponent.new(filter: <the filter object>)
+  #
+  # == Dynamic renderer resolution
+  #
+  # If you pass a callable to +:render_with+, it will be called with the object
+  # as a keyword argument. The callable is expected to return a valid argument
+  # for ActionView's +render+ method.
+  #
+  # @example Dynamic partial selection
+  #   class SelectFilter < DTB::Filter
+  #     option :render_with, default: ->(filter:, **opts) {
+  #       if filter.autocomplete?
+  #         {partial: "filters/autocomplete_filter", locals: {filter: filter, **opts}}
+  #       else
+  #         {partial: "filters/select_filter", locals: {filter: filter, **opts}}
+  #       end
+  #     }
+  #   end
+  #
+  # == Passing extra options to the renderer
+  #
+  # Whatever options you pass to the {#renderer} method, they will be
+  # forwarded to the configured renderer via {#render_with}.
+  #
+  # If rendering with a partial, these will be passed as extra locals. If using
+  # a component-based renderer, these will be passed as extra keyword arguments
+  # to the initializer.
+  #
+  # @example Passing extra locals to a partial
+  #   <%= render filter.renderer(css_class: "custom-class") %>
+  module Renderable
+    extend ActiveSupport::Concern
+    include HasOptions
+
+    included do
+      # @!group Options
+
+      # @!attribute [rw] render_with
+      #   @return [#call, Class<#render_in>, Hash] an object that can be used to
+      #     render the Renderable, that will be passed to ActionView's #render.
+      #   @see #renderer
+      #   @see #rendering_options
+      option :render_with
+
+      # @!endgroup
+    end
+
+    # Returns an object capable of being rendered by ActionView's +render+,
+    # based on what the +:render_with+ option is set to.
+    #
+    # * If +:render_with+ is a string, it will return a Hash with the +:partial+
+    #   key set to the string, and the +:locals+ key set to the return value of
+    #   the {#rendering_options} method, plus any extra options passed to this
+    #   method.
+    #
+    # * If +:render_with+ is a class, it will return an instance of that class
+    #   with the return value of the {#rendering_options} method and any extra
+    #   options passed to this method as keyword arguments.
+    #
+    # * If +:render_with+ is a callable, it will call it with the return value
+    #   of the {#rendering_options} method and any extra options passed to this
+    #   method as keyword arguments.
+    #
+    # @param opts [Hash] extra options to pass to the renderer.
+    # @return [Hash, #render_in] an object that can be used as an argument to
+    #   ActionView's +render+ method.
+    #
+    # @see #rendering_options
+    def renderer(**opts)
+      render_with = options[:render_with]
+      opts = opts.update(rendering_options)
+
+      if render_with.respond_to?(:call)
+        render_with.call(**opts)
+      elsif render_with.is_a?(Class)
+        render_with.new(**opts)
+      elsif render_with.respond_to?(:to_str)
+        {partial: render_with, locals: opts}
+      else
+        render_with
+      end
+    end
+
+    # Returns a Hash of options to pass to the renderer. By default, this will
+    # include a reference to the Renderable itself, under a key that is derived
+    # from its class name, underscored, after removing any class namespace.
+    #
+    # @example Default rendering options
+    #   class MyFilter
+    #     include DTB::Renderable
+    #   end
+    #
+    #   filter = MyFilter.new
+    #   filter.rendering_options # => {my_filter: filter}
+    #
+    # @example Default rendering options in a namespaced object
+    #   class Admin::Widget
+    #     include DTB::Renderable
+    #   end
+    #
+    #   widget = Admin::Widget.new
+    #   widget.rendering_options # => {widget: widget}
+    #
+    # @example Overridden rendering options
+    #   class MyFilter
+    #     include DTB::Renderable
+    #
+    #     def rendering_options
+    #       {filter: self, custom: "option"}
+    #     end
+    #   end
+    #
+    #   filter = MyFilter.new
+    #   filter.rendering_options # => {filter: filter, custom: "option"}
+    #
+    # @return [Hash<Symbol, Object>]
+    def rendering_options
+      name = ActiveModel::Name.new(self.class).element.underscore.to_sym
+      {name => self}
+    end
+
+    # (see BuildsDataTable#to_data_table)
+    def to_data_table(*)
+      super.merge(renderable: self)
+    end
+  end
+end

data/lib/dtb/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module DTB
+  # @return [String] the current gem version.
+  VERSION = "1.0.0.rc1"
+end

data/lib/dtb.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "dtb/data_table"
+require_relative "dtb/query"
+require_relative "dtb/version"
+
+module DTB # :nodoc:
+end