binxtils 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1595e2d8526fd86fa68cd648e318960c951a046c7a5401bb3819a01f91f9d915
-  data.tar.gz: a57ad2f943c81ccbc8245302639805b8ffa36529b8737871a5afdd143c162462
+  metadata.gz: e7eb389fe8adfebf07d5c4b775a457a89ffe7cedee03b4c635865ee844b5c237
+  data.tar.gz: b05037ae696c23642e45e2d04003e2ba4b76eb3b974ad6157388355aab41bf7c
 SHA512:
-  metadata.gz: a7e95c3ad3df8c0a64ea582344c40033407e49e4844284b964bc21159b1933bfe121f1848b9c8f53913c496140c4a174af847d113527a63f8c1302b9f5040788
-  data.tar.gz: 2cdd46b2ea2b0f9c45aa7d2432f7296210d481405d0154edea6ad1d9f3d18604059f27751225b11d73988dc9a0bc57c68a2db48f6e57e9a8a5b962faf5678868
+  metadata.gz: 1b3874b3af0782086081d84a32ec0c303abbab56775621ceb70f5366ffdfd5436cccfacd559e8bfc5f96894f2ed84a3e381c7f81a9f7991cea7914388039e995
+  data.tar.gz: fd12bc0f7d66071963d0bd52a763e27a6cccbddfab58174254031c588e60a8e2003907c2ee343a182a3e91d28acf91590c4dda05bbad55ea4bec8770bdf9f419

data/README.md

@@ -12,12 +12,65 @@ gem "binxtils"
 - **Binxtils::TimeParser** - Parse fuzzy time/date strings into `Time` objects
 - **Binxtils::TimeZoneParser** - Parse and resolve time zone strings
 
-## Usage
+### Functionable modules
 
-All modules use [Functionable](https://github.com/sethherr/functionable) and are called as class methods:
+These modules use [Functionable](https://github.com/sethherr/functionable) and are called as class methods:
 
 ```ruby
 Binxtils::TimeParser.parse("next thursday")
 Binxtils::InputNormalizer.string("  Some Input  ")
 Binxtils::TimeZoneParser.parse("Eastern Time")
 ```
+
+### Rails concerns
+
+- **Binxtils::SetPeriod** - Controller concern for time period filtering (hour, day, week, month, year, all, custom). Parses period params, manages timezones, and sets `@time_range`.
+- **Binxtils::SortableTable** - Controller concern providing `sort_column` and `sort_direction` helpers with configurable defaults.
+- **Binxtils::SortableHelper** - View helper for rendering sortable column header links with active-state indicators.
+
+Include them in your controllers and helpers:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Binxtils::SetPeriod
+  include Binxtils::SortableTable
+
+  # Optionally configure the earliest date for the "all" period
+  self.default_earliest_time = Time.at(1714460400).freeze
+end
+
+module ApplicationHelper
+  include Binxtils::SortableHelper
+
+  # Optionally extend the permitted search params
+  def default_search_keys
+    super + [:organization_id, query_items: []]
+  end
+end
+```
+
+`SortableTable` requires a `sortable_columns` method in your controller:
+
+```ruby
+class BikesController < ApplicationController
+  def sortable_columns
+    %w[created_at updated_at manufacturer_id]
+  end
+end
+```
+
+## npm package
+
+This repo also publishes `@bikeindex/time-localizer`, an npm package for localizing time elements in the browser. Luxon is bundled into the published package, so consumers don't need to install it separately.
+
+To publish a new version: update the version in `package.json`, then run `npm publish` from the repo root (requires npm login with access to the `@bikeindex` scope). The `prepublishOnly` script automatically builds `dist/index.js` before publishing.
+
+## Releasing
+
+From the `main` branch, run `bin/release` with a version number:
+
+```
+bin/release 0.3.0
+```
+
+This bumps the version, commits, tags, pushes, builds and publishes the gem to RubyGems, and creates a GitHub release.

data/lib/binxtils/set_period.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Binxtils
+  module SetPeriod
+    extend ActiveSupport::Concern
+
+    PERIOD_TYPES = %w[hour day month year week all next_week next_month].freeze
+
+    included do
+      class_attribute :default_earliest_time, default: Time.at(0).freeze
+    end
+
+    # For setting periods, particularly for graphing
+    def set_period
+      set_timezone
+      # Set time period
+      @period ||= params[:period]
+      if @period == "custom"
+        if params[:start_time].present?
+          @start_time = Binxtils::TimeParser.parse(params[:start_time], @timezone)
+          @end_time = Binxtils::TimeParser.parse(params[:end_time], @timezone) || latest_period_date
+          @start_time, @end_time = @end_time, @start_time if @start_time > @end_time
+        else
+          set_time_range_from_period
+        end
+      elsif params[:search_at].present?
+        @period = "custom"
+        @search_at = Binxtils::TimeParser.parse(params[:search_at], @timezone)
+        offset = params[:period].present? ? params[:period].to_i : 10.minutes.to_i
+        @start_time = @search_at - offset
+        @end_time = @search_at + offset
+      else
+        set_time_range_from_period
+      end
+      # Add this render_chart in here so we don't have to define it in all the controllers
+      @render_chart = Binxtils::InputNormalizer.boolean(params[:render_chart])
+      @time_range = @start_time..@end_time
+    end
+
+    private
+
+    def set_time_range_from_period
+      @period = default_period unless PERIOD_TYPES.include?(@period)
+
+      case @period
+      when "hour"
+        @start_time = Time.current - 1.hour
+      when "day"
+        @start_time = Time.current.beginning_of_day - 1.day
+      when "month"
+        @start_time = Time.current.beginning_of_day - 30.days
+      when "year"
+        @start_time = Time.current.beginning_of_day - 1.year
+      when "week"
+        @start_time = Time.current.beginning_of_day - 1.week
+      when "next_month"
+        @start_time ||= Time.current
+        @end_time = Time.current.beginning_of_day + 30.days
+      when "next_week"
+        @start_time = Time.current
+        @end_time = Time.current.beginning_of_day + 1.week
+      when "all"
+        @start_time = earliest_period_date
+      end
+      @end_time ||= latest_period_date
+    end
+
+    # Separate method so it can be overridden on per controller basis
+    def default_period
+      "all"
+    end
+
+    # Separate method so it can be overridden, specifically in invoices
+    def latest_period_date
+      Time.current
+    end
+
+    # Separate method so it can be overridden on per controller basis
+    def earliest_period_date
+      default_earliest_time
+    end
+
+    def set_timezone
+      return true if @timezone.present?
+
+      if params[:timezone].present?
+        @timezone = Binxtils::TimeZoneParser.parse(params[:timezone])
+        session[:timezone] = @timezone&.name
+      end
+
+      if session[:timezone].present?
+        @timezone ||= Binxtils::TimeZoneParser.parse(session[:timezone])
+        Time.zone = @timezone
+      end
+
+      @timezone ||= Binxtils::TimeParser.default_time_zone
+    end
+  end
+end

data/lib/binxtils/sortable_helper.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Binxtils
+  module SortableHelper
+    BASE_SEARCH_KEYS = [
+      :direction, :sort, # sorting params
+      :period, :start_time, :end_time, :render_chart, # Time period params
+      :user_id, :query, :per_page # General search params
+    ].freeze
+
+    # Set defaults, required for testing
+    def sort_column = "id"
+    def sort_direction = "desc"
+
+    def default_search_keys
+      BASE_SEARCH_KEYS
+    end
+
+    def sortable(column, title = nil, html_options = {}, &block)
+      if title.is_a?(Hash) # If title is a hash, it wasn't passed
+        html_options = title
+        title = nil
+      end
+      title ||= column.gsub(/_(id|at)\z/, "").titleize
+
+      # Check for render_sortable - otherwise default to rendering
+      render_sortable = html_options.key?(:render_sortable) ? html_options[:render_sortable] : !html_options[:skip_sortable]
+      return title unless render_sortable
+
+      html_options[:class] = "#{html_options[:class]} sortable-link"
+      direction = (column == sort_column && sort_direction == "desc") ? "asc" : "desc"
+
+      if column == sort_column
+        html_options[:class] += " active"
+        span_content = (direction == "asc") ? "\u2193" : "\u2191"
+      end
+
+      link_to(sortable_url(column, direction), html_options) do
+        concat(block_given? ? capture(&block) : title.html_safe)
+        concat(content_tag(:span, span_content, class: "sortable-direction"))
+      end
+    end
+
+    def sortable_search_params?(except: [])
+      except_keys = %i[direction sort period per_page] + except
+      s_params = sortable_search_params.except(*except_keys).values.reject(&:blank?).any?
+
+      return true if s_params
+      return false if except.map(&:to_s).include?("period")
+
+      params[:period].present? && params[:period] != "all"
+    end
+
+    def sortable_params
+      @sortable_params ||= sortable_search_params.as_json.filter_map do |k, v|
+        next if v.blank? || k == "sort" && v == default_column ||
+          k == "direction" && v == default_direction
+        [k, v]
+      end.to_h.with_indifferent_access
+    end
+
+    def sortable_search_params
+      return @sortable_search_params if defined?(@sortable_search_params)
+
+      search_param_keys = params.keys.select { |k| k.to_s.start_with?("search_") } # match params starting with search_
+      @sortable_search_params = params.permit(*(default_search_keys | search_param_keys))
+    end
+
+    private
+
+    # This is a separate method purely for testing purposes, so it can be stubbed
+    def sortable_url(sort, direction)
+      url_for(sortable_search_params.merge(sort:, direction:))
+    end
+  end
+end

data/lib/binxtils/sortable_table.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Binxtils
+  module SortableTable
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :set_period, only: %i[index]
+
+      helper_method :sort_column, :sort_direction, :default_column, :default_direction
+    end
+
+    def sort_column
+      @sort_column ||= sortable_columns.include?(params[:sort]) ? params[:sort] : default_column
+    end
+
+    def sort_direction
+      %w[asc desc].include?(params[:direction]) ? params[:direction] : default_direction
+    end
+
+    def permitted_time_range_columns
+      %w[created_at updated_at].freeze
+    end
+
+    def current_time_range_column
+      permitted_time_range_columns.include?(sort_column) ? sort_column : permitted_time_range_columns.first
+    end
+
+    # So they can be overridden
+    def default_direction = "desc"
+
+    def default_column = sortable_columns.first
+  end
+end

data/lib/binxtils/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Binxtils
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/binxtils.rb

@@ -10,4 +10,7 @@ require "rails-html-sanitizer"
 require_relative "binxtils/input_normalizer"
 require_relative "binxtils/time_zone_parser"
 require_relative "binxtils/time_parser"
+require_relative "binxtils/set_period"
+require_relative "binxtils/sortable_table"
+require_relative "binxtils/sortable_helper"
 require_relative "binxtils/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: binxtils
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Bike Index
@@ -90,6 +90,9 @@ files:
 - lib/binxtils.rb
 - lib/binxtils/input_normalizer.rb
 - lib/binxtils/railtie.rb
+- lib/binxtils/set_period.rb
+- lib/binxtils/sortable_helper.rb
+- lib/binxtils/sortable_table.rb
 - lib/binxtils/time_parser.rb
 - lib/binxtils/time_zone_parser.rb
 - lib/binxtils/version.rb