uchi 0.1.2 → 0.1.4

data/lib/generators/uchi/repository/repository_generator.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Uchi
+  class RepositoryGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path("templates", __dir__)
+
+    def create_repository_file
+      destination = File.join("app/uchi/repositories")
+      template "repository.rb", File.join(destination, "#{file_name}.rb")
+    end
+
+    def generate_controller
+      generate("uchi:controller", name)
+    end
+  end
+end

data/lib/generators/uchi/repository/templates/repository.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Uchi
+  module Repositories
+    class <%= class_name %> < Repository
+      def fields
+        []
+      end
+    end
+  end
+end

data/lib/tasks/uchi_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :uchi do
+#   # Task goes here
+# end

data/lib/uchi/application_record.rb

@@ -0,0 +1,5 @@
+module Uchi
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/uchi/engine.rb

@@ -0,0 +1,24 @@
+module Uchi
+  class Engine < ::Rails::Engine
+    isolate_namespace Uchi
+
+    initializer "uchi.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/assets/javascripts")
+        app.config.assets.precompile += %w[uchi_manifest]
+      end
+    end
+
+    initializer "uchi.autoload" do |app|
+      # Preserve Uchi as a namespace for autoloading from app/uchi
+      # See https://github.com/fxn/zeitwerk/issues/250 for details
+      ActiveSupport::Dependencies.autoload_paths.delete("#{Rails.root}/app/uchi")
+
+      uchi_directory = Rails.root.join("app/uchi")
+      if uchi_directory.exist?
+        Rails.autoloaders.main.push_dir(uchi_directory, namespace: Uchi)
+      end
+    end
+  end
+end

data/lib/uchi/field/configuration.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Field
+    module Configuration
+      class Unset; end
+
+      DEFAULT_READER = ->(record, field_name) { record.public_send(field_name) }
+
+      def initialize(*args)
+        super
+        @on = default_on
+        @reader = DEFAULT_READER
+        @searchable = default_searchable?
+        @sortable = default_sortable?
+      end
+
+      # Sets or gets which actions this field should appear on.
+      #
+      # When called with arguments, sets the actions and returns self for chaining.
+      # When called without arguments, returns the current actions.
+      #
+      # @param actions [Array<Symbol>] The actions where this field should appear
+      #   (e.g., :index, :show, :new, :edit)
+      # @return [self, Array<Symbol>] Returns self for method chaining when setting,
+      #   or the actions array when getting
+      #
+      # @example Setting
+      #   Field::Number.new(:id).on(:index, :show)
+      #
+      # @example Getting
+      #   field.on # => [:index, :show]
+      def on(*actions)
+        return @on if actions.empty?
+
+        @on = actions.flatten
+        self
+      end
+
+      # Sets or gets a custom reader for this field.
+      #
+      # When called with an argument, sets the reader and returns self for chaining.
+      # When called without arguments, returns the current reader.
+      #
+      # @param reader_proc [Proc, nil] A callable that reads the value from a record.
+      #   The proc receives the model and field name, and should return the value.
+      # @return [self, Proc] Returns self for method chaining when setting,
+      #   or the reader proc when getting
+      #
+      # @example Setting
+      #   Field::String.new(:full_name).reader(->(record, field_name) {
+      #     "#{record.first_name} #{record.last_name}"
+      #   })
+      #
+      # @example Getting
+      #   field.reader # => #<Proc...>
+      def reader(reader_proc = nil)
+        return @reader if reader_proc.nil? && !block_given?
+
+        @reader = reader_proc || Proc.new
+        self
+      end
+
+      # Sets or gets whether this field is searchable.
+      #
+      # When called with an argument, sets searchable and returns self for chaining.
+      # When called without arguments, returns whether the field is searchable.
+      #
+      # @param value [Boolean, nil] Whether the field is searchable in index views.
+      #   Defaults to false for most fields, except text-based fields.
+      # @return [self, Boolean] Returns self for method chaining when setting,
+      #   or boolean when getting
+      #
+      # @example Setting
+      #   Field::String.new(:password).searchable(false)
+      #   Field::Number.new(:id).searchable(true)
+      def searchable(value = Configuration::Unset)
+        return @searchable if value == Configuration::Unset
+
+        @searchable = value
+        self
+      end
+
+      # Returns true if the field is searchable and should be included in the
+      # query when a search term has been entered.
+      def searchable?
+        return default_searchable? if @searchable.nil?
+
+        !!@searchable
+      end
+
+      # Sets or gets whether and how this field is sortable.
+      #
+      # When called with an argument, sets sortable and returns self for chaining.
+      # When called without arguments, returns the sortable value.
+      #
+      # @param value [Boolean, Proc, Symbol] Whether the field is sortable. Pass true/false
+      #   for simple sorting, or a lambda that receives the query and direction
+      #   and returns an ActiveRecord::Relation for custom sorting.
+      # @return [self, Boolean, Proc] Returns self for method chaining when setting,
+      #   or the sortable value when getting
+      #
+      # @example Setting with boolean
+      #   Field::Number.new(:calculated_sum).sortable(false)
+      #
+      # @example Setting with lambda
+      #   Field::Number.new(:users_count).sortable(lambda { |query, direction|
+      #     query.joins(:users).group(:id).order("COUNT(users.id) #{direction}")
+      #   })
+      #
+      # @example Getting
+      #   field.sortable # => true
+      def sortable(value = Configuration::Unset)
+        return @sortable if value == Configuration::Unset
+
+        @sortable = value
+        self
+      end
+
+      # Returns true if the field is sortable
+      def sortable?
+        return default_sortable? if @sortable.nil?
+
+        !!@sortable
+      end
+
+      protected
+
+      def default_on
+        [:edit, :index, :show]
+      end
+
+      def default_searchable?
+        false
+      end
+
+      def default_sortable?
+        true
+      end
+    end
+  end
+end

data/lib/uchi/field.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "field/configuration"
+
+module Uchi
+  class Field
+    include Configuration
+
+    attr_reader :name
+
+    # The repository this field is associated with.
+    attr_accessor :repository
+
+    def column_name
+      name.to_s.humanize
+    end
+
+    def group_as(_action)
+      :attributes
+    end
+
+    def edit_component(form:, repository:, label: nil, hint: nil)
+      edit_component_class.new(
+        field: self,
+        form: form,
+        repository: repository,
+        label: label,
+        hint: hint
+      )
+    end
+
+    def edit_component_class
+      self.class.const_get(:Edit)
+    end
+
+    def index_component(record:, repository:)
+      index_component_class.new(
+        field: self,
+        record: record,
+        repository: repository
+      )
+    end
+
+    def index_component_class
+      self.class.const_get(:Index)
+    end
+
+    # @param name [String, Symbol] The name of the field.
+    def initialize(name)
+      super()
+      @name = name.to_sym
+    end
+
+    # Returns the key that this field is expected to use in params
+    def param_key
+      name.to_sym
+    end
+
+    # Returns the values to use for permitting this field in strong parameters
+    def permitted_param
+      param_key
+    end
+
+    def show_component(record:, repository:)
+      show_component_class.new(
+        field: self,
+        record: record,
+        repository: repository
+      )
+    end
+
+    def show_component_class
+      self.class.const_get(:Show)
+    end
+
+    def value(record)
+      reader.call(record, name)
+    end
+  end
+end

data/lib/uchi/i18n.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Uchi
+  module I18n
+    module_function
+
+    def translate(key, **options)
+      scope = options.delete(:scope)
+      scope ||= "uchi" unless key.to_s.start_with?("uchi.")
+      ::I18n.translate(key, **options, scope: scope)
+    end
+  end
+end

data/lib/uchi/pagination/controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "uchi/pagy"
+
+require "uchi/pagination/page"
+
+module Uchi
+  module Pagination
+    module Controller
+      include Pagy::Method
+
+      # Set up pagination for the given records. Returns a Page object and the
+      # paginated records for that page.
+      #
+      # @param records [ActiveRecord::Relation] The records to paginate
+      #
+      # @param records_per_page [Integer] The number of records per page
+      #
+      # @return [Array<(Uchi::Pagination::Page, ActiveRecord::Relation)>]
+      def paginate(records, records_per_page:)
+        page, records = pagy(:offset, records, limit: records_per_page)
+        [Uchi::Pagination::Page.new(page), records]
+      end
+    end
+  end
+end

data/lib/uchi/pagination/page.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Uchi
+  module Pagination
+    class Page
+      delegate \
+        :last,
+        :next,
+        :page,
+        :page_url,
+        to: :pagy
+
+      private attr_reader :pagy
+
+      def initialize(pagy)
+        @pagy = pagy
+      end
+    end
+  end
+end

data/lib/uchi/pagy/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017-2025 Domizio Demichelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/uchi/pagy/classes/exceptions.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Pagy
+    # Generic option error
+    class OptionError < ArgumentError
+      attr_reader :pagy, :option, :value
+
+      # Set the options and prepare the message
+      def initialize(pagy, option, description, value)
+        @pagy   = pagy
+        @option = option
+        @value  = value
+        super("expected :#{@option} #{description}; got #{@value.inspect}")
+      end
+    end
+
+    # Specific range error
+    class RangeError < OptionError; end
+
+    # I18n localization error
+    class RailsI18nLoadError < LoadError; end
+
+    # Generic internal error
+    class InternalError < StandardError; end
+
+    # JsonApi :page param error
+    class JsonapiReservedParamError < StandardError
+      # Inform about the actual value
+      def initialize(value)
+        super("expected reserved :page param to be nil or Hash-like; got #{value.inspect}")
+      end
+    end
+  end
+end

data/lib/uchi/pagy/classes/offset/offset.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/abilities/shiftable'
+require_relative '../../modules/abilities/rangeable'
+
+module Uchi
+  class Pagy
+    # Implements Offset Pagination
+    class Offset < Pagy
+      DEFAULT = { page: 1 }.freeze
+
+      autoload :Countless, Pathname.new(__dir__).join('countless')
+
+      include Rangeable
+      include Shiftable
+
+      def initialize(**) # rubocop:disable Lint/MissingSuper
+        assign_options(**)
+        assign_and_check(limit: 1, count: 0, page: 1)
+        assign_last
+        assign_offset
+        return unless in_range? { @page <= @last }
+
+        @from = [@offset + 1, @count].min
+        @to   = [@offset + @limit, @count].min
+        @in   = [@to - @from + 1, @count].min
+        assign_previous_and_next
+      end
+
+      attr_reader :offset, :count, :from, :to, :in, :previous, :last
+
+      def records(collection)
+        collection.offset(@offset).limit(@limit)
+      end
+
+      protected
+
+      def offset? = true
+
+      def assign_last
+        @last = [(@count.to_f / @limit).ceil, 1].max
+        @last = @options[:max_pages] if @options[:max_pages] && @last > @options[:max_pages]
+      end
+
+      def assign_offset
+        @offset = (@limit * (@page - 1))
+      end
+
+      # Called by false in_range?
+      def assign_empty_page_variables
+        @in = @from = @to = 0     # options relative to the actual page
+        @previous = @last         # @previous relative to the actual page
+      end
+    end
+  end
+end

data/lib/uchi/pagy/classes/request.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Pagy
+    # Decouple the reuest from the env, allowing non-rack apps to use pagy by passing a hash.
+    # Resolve :page and :limit, supporting the :jsonapi option. Support for URL composition.
+    class Request
+      def initialize(request, options = {})
+        @base_url, @path, @query, @cookie =
+          if request.is_a?(Hash)
+            request.values_at(:base_url, :path, :query, :cookie)
+          else
+            [request.base_url, request.path, request.GET, request.cookies['pagy']]
+          end
+        @jsonapi = @query['page'] && options[:jsonapi]
+        raise JsonapiReservedParamError, @query['page'] if @jsonapi && !@query['page'].respond_to?(:fetch)
+      end
+
+      attr_reader :base_url, :path, :query, :cookie
+
+      def resolve_page(options, force_integer: true)
+        page_key = options[:page_key] || DEFAULT[:page_key]
+        page     = @jsonapi ? @query['page'][page_key] : @query[page_key]
+        page     = nil if page == ''   # fix for app-generated queries like ?page=
+        force_integer ? (page || 1).to_i : page
+      end
+
+      def resolve_limit(options)
+        limit_key = options[:limit_key] || DEFAULT[:limit_key]
+        return options[:limit] || DEFAULT[:limit] \
+              unless options[:client_max_limit] &&
+                      (requested_limit = @jsonapi ? @query['page'][limit_key] : @query[limit_key])
+
+        [requested_limit.to_i, options[:client_max_limit]].min
+      end
+    end
+  end
+end

data/lib/uchi/pagy/modules/abilities/configurable.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Pagy
+    # Add configurstion methods
+    module Configurable
+      # Sync the pagy javascript targets
+      def sync_javascript(destination, *targets)
+        names   = %w[pagy.mjs pagy.js pagy.js.map pagy.min.js]
+        targets = names if targets.empty?
+        targets.each { |filename| FileUtils.cp(ROOT.join('javascripts', filename), destination) }
+        (names - targets).each { |filename| FileUtils.rm_f(File.join(destination, filename)) }
+      end
+
+      # Generate the script and style tags to help development
+      def dev_tools(wand_scale: 1)
+        <<~HTML
+          <script id="pagy-ai-widget">
+            document.addEventListener('wand-positioned', #{ROOT.join('javascripts/ai_widget.js').read});
+          </script>
+          <script id="pagy-wand" data-scale="#{wand_scale}">
+            #{ROOT.join('javascripts/wand.js').read}
+          </script>
+          <style id="pagy-wand-default">
+            #{ROOT.join('stylesheets/pagy.css').read}
+          </style>
+        HTML
+      end
+
+      # Setup pagy for using the i18n gem
+      def translate_with_the_slower_i18n_gem!
+        send(:remove_const, :I18n)
+        send(:const_set, :I18n, ::I18n)
+        ::I18n.load_path += Dir[ROOT.join('locales/*.yml')]
+      end
+    end
+  end
+end

data/lib/uchi/pagy/modules/abilities/linkable.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Uchi
+  class Pagy
+    # Provide the helpers to handle the url and anchor
+    module Linkable
+      module QueryUtils
+        module_function
+
+        # Extracted from Rack::Utils and reformatted for rubocop
+        # Add the 'unescaped' param, and use it for simple and safe url-templating.
+        # All string keyed hashes
+        def build_nested_query(value, prefix = nil, unescaped = [])
+          case value
+          when Array
+            value.map { |v| build_nested_query(v, "#{prefix}[]", unescaped) }.join('&')
+          when Hash
+            value.map do |k, v|
+              new_k = prefix ? "#{prefix}[#{escape(k)}]" : escape(k)
+              unescaped[unescaped.find_index(k)] = new_k if unescaped.size.positive? && new_k != k && unescaped.include?(k)
+              build_nested_query(v, new_k, unescaped)
+            end.delete_if(&:empty?).join('&')
+          when nil
+            escape(prefix)
+          else
+            raise ArgumentError, 'value must be a Hash' if prefix.nil?
+            return "#{escape(prefix)}=#{value}" if unescaped.include?(prefix)
+
+            "#{escape(prefix)}=#{escape(value)}"
+          end
+        end
+
+        def escape(str)
+          URI.encode_www_form_component(str)
+        end
+      end
+
+      protected
+
+      # Return the URL for the page, relying on the Pagy::Request
+      def compose_page_url(page, limit_token: nil, **options)
+        jsonapi, page_key, limit_key, limit, client_max_limit, querify, absolute, path, fragment =
+          @options.merge(options)
+                  .values_at(:jsonapi, :page_key, :limit_key, :limit, :client_max_limit, :querify, :absolute, :path, :fragment)
+        query = @request.query.clone(freeze: false)
+        query.delete(jsonapi ? 'page' : page_key)
+        factors = {}.tap do |h|
+                    h[page_key]  = countless? ? "#{page || 1}+#{@last}" : page
+                    h[limit_key] = limit_token || limit if client_max_limit
+                  end.compact # No empty params
+        query.merge!(jsonapi ? { 'page' => factors } : factors) if factors.size.positive?
+        querify&.(query) # Must modify the query: the returned value is ignored
+        query_string = QueryUtils.build_nested_query(query, nil, [page_key, limit_key])
+        query_string = "?#{query_string}" unless query_string.empty?
+        fragment   &&= %(##{fragment}) unless fragment&.start_with?('#')
+        "#{@request.base_url if absolute}#{path || @request.path}#{query_string}#{fragment}"
+      end
+    end
+  end
+end

data/lib/uchi/pagy/modules/abilities/rangeable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Pagy
+    # Add method supporting range checking, range error and rescue
+    module Rangeable
+      # Check if in range
+      def in_range?
+        return @in_range if defined?(@in_range) || (@in_range = yield)
+        raise RangeError.new(self, :page, "in 1..#{@last}", @page) if @options[:raise_range_error]
+
+        assign_empty_page_variables
+        false
+      end
+    end
+  end
+end

data/lib/uchi/pagy/modules/abilities/shiftable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Pagy
+    module Shiftable
+      protected
+
+      def assign_previous_and_next
+        @previous = @page - 1 unless @page == 1
+        @next     = @page + 1 unless @page == @last
+      end
+    end
+  end
+end

data/lib/uchi/pagy/modules/console.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Pagy
+    # Provide a ready to use pagy environment when included in irb/rails console
+    module Console
+      class Request
+        attr_accessor :base_url, :path, :params
+
+        def initialize
+          @base_url = 'http://www.example.com'
+          @path     = '/path'
+          @params   = { example: '123' }
+        end
+
+        def GET = @params  # rubocop:disable Naming/MethodName
+
+        def cookies = {}
+      end
+
+      class Collection < Array
+        def initialize(arr = Array(1..1000))
+          super
+          @collection = clone
+        end
+
+        def offset(value) = tap { @collection = self[value..] }
+        def limit(value)  = @collection[0, value]
+        def count(*)      = size
+      end
+
+      include Method
+
+      # Direct reference to request.params via a method
+      def params     = request.params
+      def request    = @request ||= Request.new
+      def collection = Collection
+    end
+  end
+end