dtb 1.0.0.rc1

data/lib/dtb/data_table.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+require_relative "filter_set"
+require_relative "query_builder_set"
+require_relative "empty_state"
+
+module DTB
+  # Data Tables act as presenter objects for the data returned from a {Query}.
+  # Queries pass data to this object, which is then passed to the view layer,
+  # providing methods to access the different components that should be rendered
+  # on the page.
+  #
+  # DataTables provide also a method (.build) to run the Query and turn it into
+  # a DataTable in one pass, since most likely that's what you will need on most
+  # endpoints that use these objects.
+  #
+  # @example build a data table in the controller
+  #   def index
+  #     @data_table = DTB::DataTable.build SomeQuery, params
+  #   end
+  #
+  # @example render a data table on the view
+  #   <%= render partial: @data_table.filters, as: :filters %>
+  #
+  #   <% if @data_table.any? %>
+  #     <table>
+  #       <thead>
+  #         <%= @data_table.columns.renderable.each do |column| %>
+  #           <th><%= column.header %>
+  #         <% end %>
+  #       </thead>
+  #       <tbody>
+  #         <%= render partial: @data_table.rows %>
+  #       </tbody>
+  #     </table>
+  #   <% else %>
+  #     <%= render partial: @data_table.empty_state,
+  #                as: :empty_state,
+  #                locals: { data_table: @data_table } %>
+  #   <% end %>
+  class DataTable
+    # @overload build(query_class, params = {}, options = {})
+    #   @param query_class [Class<Query>] a Query class to run and turn into a
+    #     data table.
+    #   @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)
+    #   @return [Datatable] the data table with the results of running the query.
+    #
+    # @overload build(query)
+    #   @param query [Query] an instance of a Query which may or may not have
+    #     been run yet.
+    #   @return [Datatable] the data table with the results of running the query.
+    #
+    # @overload build(object, ...)
+    #   @param object [#to_data_table] an object that implements +#to_data_table+.
+    #   @param ... [Array<Object>] any parameters that should be forwarded to
+    #     the +object+'s +#to_data_table+ method.
+    #   @return [Datatable] the data table with the results of running the query.
+    #   @see BuildsDataTable
+    def self.build(query, ...)
+      new(**query.to_data_table(...))
+    end
+
+    # @!method any?
+    #   @return [Boolean] whether there are any rows to render.
+    # @!method empty?
+    #   @return [Boolean] whether there are no rows to render.
+    # @!method each
+    #   @yield each row of the query results
+    delegate :any?, :empty?, :each, to: :rows
+
+    # @return [Enumerable] the list of objects to render as rows of the table.
+    attr_reader :rows
+
+    # @return [QueryBuilderSet] the list of columns used for this query.
+    attr_reader :columns
+
+    # @return [FilterSet] the list of filters used for this query.
+    attr_reader :filters
+
+    # @return [Hash] the options used to configure the query.
+    attr_reader :options
+
+    # @return [EmptyState] the {EmptyState} object to use if there are no rows
+    #   to render.
+    attr_reader :empty_state
+
+    # @param rows [Enumerable] a list of objects to generate the rows of the table.
+    # @param columns [QueryBuilderSet] the list of columns used for this query.
+    #   Defaults to an empty set.
+    # @param filters [FilterSet] the list of filters used for this query.
+    #   Defaults to an empty set.
+    # @param empty_state [EmptyState] the object to get information from if
+    #   there are no rows. Defaults to an unconfigured {EmptyState}.
+    # @param options [Hash] the options used to configure the query.
+    # @param renderable [Renderable, nil] the source of rendering options for this
+    #   data table. Normally, a Query object, or the same object that was used
+    #   to generate the {#rows}. If +nil+, calling {#renderer} will return +nil+.
+    def initialize(
+      rows:,
+      columns: NO_COLUMNS,
+      filters: NO_FILTERS,
+      empty_state: DEFAULT_EMPTY_STATE,
+      options: {},
+      renderable: nil
+    )
+      @rows = rows
+      @columns = columns
+      @filters = filters
+      @empty_state = empty_state
+      @options = options
+      @renderable = renderable
+    end
+
+    # @return [Boolean] whether any of the filters was applied to get the
+    #   current results.
+    def filtered?
+      @filtered ||= filters.applied.any?
+    end
+
+    # (see Renderable#renderer)
+    def renderer(**opts)
+      opts = opts.merge(rendering_options)
+      @renderable&.renderer(**opts)
+    end
+
+    # (see Renderable#rendering_options)
+    def rendering_options
+      {data_table: self}
+    end
+
+    NO_COLUMNS = QueryBuilderSet.new
+    private_constant :NO_COLUMNS
+
+    NO_FILTERS = FilterSet.new
+    private_constant :NO_FILTERS
+
+    DEFAULT_EMPTY_STATE = EmptyState.new
+    private_constant :DEFAULT_EMPTY_STATE
+  end
+end

data/lib/dtb/empty_state.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "has_options"
+require_relative "has_i18n"
+require_relative "renderable"
+
+module DTB
+  # The Empty State encapsulates the data you might want to render when a query
+  # returns no results. For each query, this will derive from your i18n sources
+  # three things:
+  #
+  # * a {title} to show in the page (for example "No results!")
+  # * an {explanation} to indicate why the query returned no results (this is
+  #   useful to present on a "blank slate" scenario, when the underlying
+  #   storage doesn't have data yet.)
+  # * a call to action to {update_filters} in the case the user has applied
+  #   filters and that resulted in the results being empty.
+  #
+  # The names of those methods is purely informational and doesn't carry any
+  # behavior with it. You are welcome to use these strings in any way you want,
+  # or not at all.
+  #
+  # == Rendering the Empty State
+  #
+  # Each empty state is a {Renderable} object, and as such, you can define how
+  # to render it via the {#render_with} option, and by then calling the
+  # {#renderer} method.
+  #
+  # @see HasEmptyState
+  class EmptyState
+    include HasOptions
+    include HasI18n
+    include Renderable
+
+    # @!group Options
+
+    # @!attribute [rw] context
+    #   @return [Object, nil] the Object to use as context to evaluate the i18n
+    #     sources.
+    # ` @see HasI18n#i18n_lookup
+    option :context
+
+    # @!endgroup
+
+    # Determine the "title" of the default empty state container that is
+    # rendered. This looks up a translation under the +empty_states+ namespace,
+    # optionally using this empty state's #context.
+    #
+    # @return [String]
+    # @see #i18n_lookup
+    def title
+      i18n_lookup(:title, :empty_states, context: options[:context])
+    end
+
+    # Determine the "explanation" to render when a query has no results to show.
+    # This looks up a translation under the +empty_states+ namespace, optionally
+    # using this empty state's #context.
+    #
+    # @return [String]
+    # @see #i18n_lookup
+    def explanation
+      i18n_lookup(:explanation, :empty_states, context: options[:context], default: "")
+    end
+
+    # Determine the explanation to render when a query has no results to show
+    # and filters are applied. This should be a call to action to let users know
+    # they should relax the filters. This looks up a translation under the
+    # +empty_states+ namespace, optionally using this empty state's #context.
+    #
+    # @return [String]
+    # @see #i18n_lookup
+    def update_filters
+      i18n_lookup(:update_filters, :empty_states, context: options[:context], default: "")
+    end
+  end
+end

data/lib/dtb/errors.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module DTB
+  # Mixin for other errors raised from this library, so that you can always
+  # rescue +DTB::Error+.
+  module Error; end
+
+  # Raised when initializing an object that supports options with an option that
+  # hasn't been defined.
+  #
+  # @see HasOptions
+  # @see OptionsMap
+  class UnknownOptionsError < ArgumentError
+    include DTB::Error
+
+    # @return [OptionsMap] The invalid options hash.
+    attr_reader :options
+
+    # @return [Set] The options that are defined for this hash.
+    attr_reader :valid_options
+
+    # @return [Set] The options that are present in the Hash that aren't defined.
+    attr_reader :unknown_options
+
+    # @api private
+    def initialize(options)
+      unknown = options.keys.to_set - options.valid_keys
+      super(format(MESSAGE, unknown.to_a, options.valid_keys.to_a))
+      @options = options
+      @valid_options = options.valid_keys
+      @unknown_options = unknown
+    end
+
+    MESSAGE = "Unknown options: %p. Valid options are: %p"
+    private_constant :MESSAGE
+  end
+
+  # Raised when initializing an object that supports options without passing all
+  # the required options.
+  #
+  # @see HasOptions
+  # @see OptionsMap
+  class MissingOptionsError < ArgumentError
+    include DTB::Error
+
+    # @return [OptionsMap] The invalid options hash.
+    attr_reader :options
+
+    # @return [Set] The options that are required for this Hash.
+    attr_reader :required_options
+
+    # @return [Set] The required options that are missing from this Hash.
+    attr_reader :missing_options
+
+    # @api private
+    def initialize(options)
+      missing = options.required_keys - options.keys
+      super(format(MESSAGE, missing.to_a, options))
+      @options = options
+      @required_options = options.required_keys
+      @missing_options = missing
+    end
+
+    MESSAGE = "Missing required options: %p. Options given were: %p"
+    private_constant :MESSAGE
+  end
+
+  # rubocop:disable Lint/InheritException
+
+  # Extends +NotImplementedError+ to be catchable as a library error via
+  # +rescue DTB::Error+. Normally you wouldn't rescue this in code, though,
+  # but rather use it to get failing tests / exceptions while developing.
+  class NotImplementedError < ::NotImplementedError
+    include DTB::Error
+  end
+  # rubocop:enable Lint/InheritException
+end

data/lib/dtb/filter.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+require_relative "query_builder"
+require_relative "has_options"
+require_relative "renderable"
+
+module DTB
+  # Filters allow setting conditions on a query, which are optionally applied
+  # depending on user input. You are meant to subclass this and define your own
+  # specialized filters based on your application's needs.
+  #
+  # == Query Builders
+  #
+  # The filter, as other query builders, depends on a Proc that accepts both a
+  # +scope+ and the user provided +value+ for this filter. As other
+  # {QueryBuilder Query Builders}, filters respond to {#call}, which evaluates
+  # the proc only if the value is present.
+  #
+  #   with_value = Filter.new(:name, value: "Jane Doe") do |scope, value|
+  #     scope.where(name: value)
+  #   end
+  #   without_value = Filter.new(:name, value: nil) do |scope, value|
+  #     scope.where(name: value)
+  #   end
+  #
+  #   scope = User.all
+  #   without_value.call(scope) #=> User.all
+  #   with_value.call(scope) #=> User.all.where(name: "Jane Doe")
+  #
+  # == Value Sanitization
+  #
+  # By default, the value is passed as-is to the Proc. You might want to format
+  # it or sanitize it in any other way:
+  #
+  #   filter = Filter.new(
+  #     :name,
+  #     value: "  string ",
+  #     sanitize: ->(value) { value&.strip&.upcase }
+  #   ) { |scope, value| scope.where(name => value) }
+  #
+  #   filter.call(User.all) #=> User.all.where(name: "STRING")
+  #
+  # *NOTE*: Keep in mind that the value received by +sanitize+ might be +nil+.
+  #
+  # == Default Values
+  #
+  # Usually you want filters to run only when the user supplies a value, but
+  # sometimes you want the query to always be filtered in some way, with the
+  # user having control on the specific value of the filter.
+  #
+  # For example, a query might always return a window of time, but the user
+  # could choose whether that's "last week", "last month", or "last year", and
+  # by default you want this to be "last week".
+  #
+  #   # if the user sends 30 (i.e. last 30 days), we will use that value.
+  #   filter = Filter.new(:name, value: 30, default: 7) do |scope, value|
+  #     scope.where("created_at > ?", value.days.ago)
+  #   end
+  #
+  #   # if the user doesn't set this filter, we will use 7 as the default value.
+  #   filter = Filter.new(:name, value: nil, default: 7) do |scope, value|
+  #     scope.where("created_at > ?", value.days.ago)
+  #   end
+  #
+  # If the given default is a Proc/lambda, it will be evaluated, and the return
+  # value of the Proc will be used as the default:
+  #
+  #   # the default value will be the current user's currency
+  #   filter = Filter.new(:currency, default: -> { Current.user.currency })
+  #
+  # == Rendering filters
+  #
+  # To render a filter in the view, you can call its {#renderer} method, and
+  # pass the output to the +render+ helper:
+  #
+  #   <%= render filter.renderer %>
+  #
+  # To configure how that renderer behaves, Filters accept a +rendes_with+
+  # option that defines how they can be rendered. This lets you render different
+  # widgets for each filter, where you can customize the form control used (i.e.
+  # a text field vs a number field vs a select box).
+  #
+  # By default, filters are rendered using a partial template named after the
+  # filter's class. For example, a +SelectFilter+ would be rendered in the
+  # +"filters/select_filter"+ partial. The partial receives a local named
+  # +filter+ with the filter object.
+  #
+  # Alternatively, you can pass a callable to +render_with+ that returns valid
+  # attributes for ActionView's +render+ method. This could be a Hash (i.e. to
+  # +render+ a custom partial with extra options) or it could be an object that
+  # responds to +render_in+.
+  #
+  # Finally, you can just pass a Class. If you do, DTB will insantiate it with a
+  # +filter+ keyword, and return the instance. This is useful when using
+  # component libraries such as ViewComponent or Phlex.
+  #
+  #   class SelectFilter < DTB::Filter
+  #     option :render_with, default: SelectFilterComponent
+  #   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}. For example,
+  # given:
+  #
+  #   class SelectFilter < DTB::Filter
+  #     option :render_with, default: SelectFilterComponent
+  #   end
+  #
+  # The following two statements are equivalent
+  #
+  #   <%= render filter.renderer(class: "custom-class") %>
+  #   <%= render SelectFilterComponent.new(filter: filter, class: "custom-class") %>
+  #
+  # == Overriding the options passed to the renderer
+  #
+  # The default options passed to the rendered are the return value of the
+  # {#rendering_options} method. You can always override it to customize how the
+  # object is passed to the renderer, or to pass other options that you always
+  # need to include (rather than passing them on every {#renderer}) invocation.
+  #
+  # @example Overriding the rendering options
+  #   class AutocompleteFilter < DTB::Filter
+  #     option :render_with, default: AutocompleteFilterComponent
+  #
+  #     def rendering_options
+  #       # super here returns `{filter: self}`
+  #       {url: autocomplete_url}.update(super)
+  #     end
+  #   end
+  #
+  # @see HasFilters
+  class Filter < QueryBuilder
+    include HasOptions
+    include Renderable
+
+    # @!group Options
+
+    # @!attribute [rw] value
+    #   @return [Object, nil] the user-supplied value for this filter.
+    option :value, required: true
+
+    # @!attribute [rw] sanitize
+    #   @return [Proc] a Proc to sanitize the user input. Defaults to a Proc
+    #     that returns the input value.
+    option :sanitize, default: IDENT, required: true
+
+    # @!attribute [rw] default
+    #   @return [Object, Proc nil] a default value to use if the user supplies a
+    #     blank value. If given a Proc, it will be evaluated and its return
+    #     value used as the default.
+    option :default
+
+    # @!attribute [rw] render_with
+    #   @see Renderable#render_with
+    option :render_with,
+      default: ->(filter:, **opts) {
+        {partial: "filters/#{filter.class.name.underscore}", locals: {filter: filter, **opts}}
+      },
+      required: true
+
+    # @!endgroup
+
+    # Applies the Proc if the value given by the user is present, and the filter
+    # isn't turned off in another way (e.g. via +if+/+unless+) settings.
+    #
+    # @param scope (see QueryBuilder#call)
+    # @return (see QueryBuilder#call)
+    # @raise (see QueryBuilder#call)
+    def call(scope)
+      super(scope, value).tap do
+        # We only want to consider this filter applied if it has a _custom_
+        # value set, not if it's just using the default value.
+        @applied = false if @applied && sanitized_value.blank?
+      end
+    end
+
+    # @return [Object, nil] the value used to decide if the filter should be
+    # applied. This can be a user supplied value (after sanitizing), or the
+    # default value, if set.
+    def value
+      sanitized_value.presence || default_value
+    end
+
+    # Determine the content of the +<label>+ tag that should be shown when
+    # rendering this filter. This will look up the translation under the
+    # +filters+ namespace.
+    #
+    # @return [String]
+    # @see QueryBuilder#i18n_lookup
+    def label
+      i18n_lookup(:filters)
+    end
+
+    # Determine the content of the +placeholder+ attribute that should be used
+    # when rendering this filter. This will look up the translation under the
+    # +placeholders+ namespace.
+    #
+    # @return [String]
+    # @see QueryBuilder#i18n_lookup
+    def placeholder
+      i18n_lookup(:placeholders, default: "")
+    end
+
+    # @api private
+    def evaluate?
+      value.present? && super
+    end
+
+    private def rendering_options
+      {filter: self}
+    end
+
+    private def default_value
+      if options[:default].respond_to?(:call)
+        evaluate(with: options[:default])
+      else
+        options[:default]
+      end
+    end
+
+    private def sanitized_value
+      options[:sanitize].call(options[:value])
+    end
+  end
+end

data/lib/dtb/filter_set.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "query_builder_set"
+require_relative "renderable"
+
+module DTB
+  # Filter sets extend {QueryBuilderSet QueryBuilder sets} by adding a few
+  # options to help render the filters form.
+  #
+  # == Rendering the filters form
+  #
+  # Start by defining a partial for your form. Default location is
+  # +filters/filters+, so +app/views/filters/_filters.html.erb+ is a good place
+  # to start, with at least these components:
+  #
+  #   <%= form_with method: :get, scope: filters.namespace, url: filters.submit_url do |form| %>
+  #     <% filters.each do |filter| %>
+  #       <%= render partial: filter, locals: { form: form } %>
+  #     <% end %>
+  #
+  #     <%= form.submit %>
+  #
+  #     <% if filters.reset_url.present? %>
+  #       <%= form.link_to t(".reset"), filters.reset_url, class: "btn" %>
+  #     <% end %>
+  #   <% end %>
+  #
+  class FilterSet < QueryBuilderSet
+    include Renderable
+
+    # @!group Options
+
+    # @!attribute [rw] param
+    #   This is the name of the query string parameter used to group filters in
+    #   the form. {HasFilters} uses this to determine which sub-Hash of the
+    #   parameters object to use as the values for filters.
+    #   @return [Symbol] the name of the top-level param name. Defaults to
+    #     +:filters+.
+    #   @see #namespace
+    option :param, default: :filters, required: true
+
+    # @!attribute [rw] renders_with (see Renderable#renders_with)
+    option :render_with, default: "filters/filters", required: true
+
+    # @!attribute [rw] submit_url
+    #   @return [String] the URL to submit the filters form to.
+    option :submit_url
+
+    # @!attribute [rw] reset_url
+    #   @return [String, nil] the URL to reset the filters form to.
+    option :reset_url
+
+    # @!endgroup
+
+    # The keyword to use as the namespace for all form fields when rendering the
+    # filters form.
+    #
+    # @example Rendering the filters form with +form_with+
+    #   <%= form_with scope: filters.namespace, url: filters.submit_url do |form| %>
+    #     ...
+    #   <% end %>
+    #
+    # @example Rendering the filters form with +form_for+
+    #   <%= form_for filters.namespace, url: filters.submit_url do |form| %>
+    #     ...
+    #   <% end %>
+    #
+    # @return [Symbol]
+    # @see #param
+    def namespace
+      options[:param]
+    end
+
+    def submit_url
+      options[:submit_url]
+    end
+
+    def reset_url
+      options[:reset_url]
+    end
+
+    private def rendering_options
+      {filters: self}
+    end
+  end
+end

data/lib/dtb/has_columns.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require_relative "column"
+require_relative "has_options"
+require_relative "query_builder_set"
+
+module DTB
+  # This mixin provides {Query Queries} with a set of column objects that can be
+  # used to modify the query and to render in the view. Including this module
+  # gives you access to the {.column} class method, which you can use to define
+  # columns in your query.
+  #
+  # @example (see .column)
+  module HasColumns
+    extend ActiveSupport::Concern
+    include HasDefaultImplementation
+    include BuildsDataTable
+    include HasOptions
+
+    included do
+      # @!group Options
+
+      # @!attribute [rw] default_column_type
+      #   The default class for columns added. Defaults to {Column}.
+      option :default_column_type, default: Column
+
+      # @!endgroup
+    end
+
+    class_methods do
+      # Defines a new Column that will be added to this Query.
+      #
+      # @example Adding a column that references an associated resource
+      #   column :author_id,
+      #     ->(scope) { scope.select(:author_id).includes(:author) }
+      #
+      # @example Adding a column that doesn't modify the database query but is rendered
+      #   column :actions, database: false
+      #
+      # @param name [Symbol]
+      # @param query [Proc] The {QueryBuilder} proc.
+      # @param type [Class<Column>] The type of column to use. Defaults to
+      #   whatever is set as the {default_column_type}.
+      # @param opts [Hash] Any other options required by the +type+.
+      # @return [void]
+      def column(name, query = ->(scope) { scope.select(name) }, type: options[:default_column_type], **opts)
+        column_definitions << {type: type, name: name, query: query, options: opts}
+      end
+
+      # @api private
+      # @return [Array<Hash>]
+      def column_definitions
+        @column_definitions ||= []
+      end
+    end
+
+    # @return [QueryBuilderSet] the set of columns defined on this object.
+    def columns
+      return @columns if defined?(@columns)
+
+      columns = self.class.column_definitions.map do |dfn|
+        dfn[:type].new(dfn[:name], context: self, **dfn[:options], &dfn[:query])
+      end
+
+      @columns = QueryBuilderSet.new(columns)
+    end
+
+    # Applies all defined columns to the query being built.
+    #
+    # @return (see HasDefaultImplementation#run)
+    def run
+      columns.call(super)
+    end
+
+    # (see BuildsDataTable#to_data_table)
+    def to_data_table
+      super.merge(columns: columns)
+    end
+  end
+end