uchi 0.1.3 → 0.1.5

data/lib/uchi/repository/translate.rb

@@ -0,0 +1,368 @@
+# frozen_string_literal: true
+
+module Uchi
+  class Repository
+    class Translate
+      attr_reader :repository
+
+      # Returns the breadcrumb label for the given page.
+      #
+      # Example translation key:
+      #   uchi.repository.author.breadcrumb.edit.label
+      def breadcrumb_label(page, record: nil)
+        return breadcrumb_label_for_index if page.to_sym == :index
+
+        default = {
+          show: title_for_record(record)
+        }[page.to_sym].presence
+        default ||= translate("common.#{page}", default: page.to_s.capitalize)
+
+        translate(
+          "label",
+          default: default,
+          model: singular_name,
+          record: title_for_record(record),
+          scope: i18n_scope("breadcrumb.#{page}")
+        )
+      end
+
+      # Returns the breadcrumb label for the index page.
+      #
+      # Returns the first of the following that is present:
+      # 1. Translation from "uchi.repository.author.breadcrumb.index.label"
+      # 2. Translation from "uchi.repository.author.index.title"
+      # 3. plural name of the model
+      # 4. Translation from "common.index"
+      # 5. Capitalized page name ("Index")
+      def breadcrumb_label_for_index
+        first_present_value(
+          translate(i18n_scope("breadcrumb.index.label"), default: nil),
+          translate(i18n_scope("index.title"), default: nil),
+          plural_name,
+          translate("common.index", default: nil),
+          "Index"
+        )
+      end
+
+      # Returns the label for the root breadcrumb item. Defaults to the
+      # application name.
+      #
+      # To customize this provide a translation for the key:
+      # `uchi.breadcrumb.root.label`
+      def breadcrumb_label_for_root
+        first_present_value(
+          translate("breadcrumb.root.label", default: nil),
+          Rails.application.name.titlecase
+        )
+      end
+
+      # Returns a description for the given page, or nil if none is found.
+      # This description is intended to provide additional context for the page
+      # being shown.
+      def description(page, record: nil)
+        translate(
+          "description",
+          default: nil,
+          model: singular_name,
+          record: record,
+          scope: i18n_scope(page)
+        )
+      end
+
+      # Returns a title for a dialog with the given name, e.g. :destroy.
+      # The title may include interpolation keys such as %{record}.
+      #
+      # Example translation key:
+      #   uchi.repository.author.dialog.destroy.title
+      #
+      # Example default value:
+      #   Are you sure you want to delete %{record}?
+      #
+      # Note that the default value itself is also looked up in the "common"
+      # scope, so that it can be shared across repositories.
+      #
+      # Example fallback translation key:
+      #   common.dialog.destroy.title
+      #
+      # Example fallback default value:
+      #   Are you sure you want to delete this record?
+      def destroy_dialog_title(record = nil)
+        translate(
+          "dialog.destroy.title",
+          default: translate(
+            "common.dialog.destroy.title",
+            default: "Are you sure?",
+            record: repository.title(record)
+          ),
+          record: repository.title(record),
+          scope: "uchi.repository.#{i18n_key}"
+        )
+      end
+
+      def failed_destroy
+        translate(
+          "destroy.failure",
+          default: translate(
+            "destroy.failure",
+            default: "The record could not be deleted",
+            scope: "common"
+          ),
+          scope: "uchi.repository.#{i18n_key}"
+        )
+      end
+
+      def initialize(repository:)
+        @repository = repository
+      end
+
+      # Returns the label for the given field.
+      def field_label(field)
+        translate(
+          "label",
+          default: model.human_attribute_name(field.name),
+          scope: i18n_scope("field.#{field.name}")
+        )
+      end
+
+      # Returns the hint for the given field, or nil if none is found.
+      def field_hint(field)
+        translate(
+          "hint",
+          default: nil,
+          scope: i18n_scope("field.#{field.name}")
+        )
+      end
+
+      def link_to_cancel
+        translate("common.cancel", default: "Cancel")
+      end
+
+      def link_to_destroy(record)
+        first_present_value(
+          translate(
+            "link_to_destroy",
+            default: nil,
+            model: singular_name,
+            record: repository.title(record),
+            scope: i18n_scope("button")
+          ),
+          translate(
+            "common.destroy",
+            default: nil,
+            model: singular_name,
+            record: repository.title(record)
+          ),
+          "Delete"
+        )
+      end
+
+      def link_to_edit(record)
+        first_present_value(
+          translate(
+            "link_to_edit",
+            default: nil,
+            model: singular_name,
+            record: repository.title(record),
+            scope: i18n_scope("button")
+          ),
+          translate(
+            "common.edit",
+            default: nil,
+            model: singular_name,
+            record: repository.title(record)
+          ),
+          "Edit"
+        )
+      end
+
+      # Returns the text for the "new" action link.
+      #
+      # Returns the first of the following translations that is present:
+      # 1. Translation from "uchi.repository.[name].button.link_to_new"
+      # 2. Translation from "uchi.common.new" with interpolation key %{model}
+      # 3. Default string "New %{model}"
+      def link_to_new
+        translate(
+          "link_to_new",
+          default: translate("common.new", default: "New %{model}"),
+          model: singular_name,
+          scope: i18n_scope("button")
+        )
+      end
+
+      def loading_message
+        translate("loading", default: "Loading...", scope: "uchi.repository.common")
+      end
+
+      # Returns the label for the navigation link to this repository's index
+      # page.
+      #
+      # Returns the first of the following that is present:
+      # 1. Translation from "uchi.repository.[name].navigation.label"
+      # 2. Translation from "uchi.repository.[name].index.title"
+      # 3. plural name of the model
+      def navigation_label
+        first_present_value(
+          translate(i18n_scope("navigation.label"), default: nil),
+          translate(i18n_scope("index.title"), default: nil),
+          plural_name
+        )
+      end
+
+      # Returns the localized, human-readable plural name of the model this
+      # repository manages.
+      def plural_name
+        ::I18n.translate(
+          "uchi.repository.#{i18n_key}.model",
+          count: 2,
+          default: model.model_name.plural.humanize
+        )
+      end
+
+      def no_records_found
+        translate("no_records_found", default: "No records found", scope: "uchi.common")
+      end
+
+      def search_label
+        translate("common.search", default: "Search")
+      end
+
+      def search_button
+        translate("common.search", default: "Search")
+      end
+
+      # Returns the label for a generic submit button
+      def submit_button
+        translate("common.save", default: "Save")
+      end
+
+      def successful_create
+        translate(
+          "create.success",
+          default: translate(
+            "create.success",
+            default: "Your changes have been saved",
+            scope: "common"
+          ),
+          scope: "uchi.repository.#{i18n_key}"
+        )
+      end
+
+      def successful_destroy
+        translate(
+          "destroy.success",
+          default: translate(
+            "destroy.success",
+            default: "The record has been deleted",
+            scope: "common"
+          ),
+          scope: "uchi.repository.#{i18n_key}"
+        )
+      end
+
+      def successful_update
+        translate(
+          "update.success",
+          default: translate(
+            "update.success",
+            default: "Your changes have been saved",
+            scope: "common"
+          ),
+          scope: "uchi.repository.#{i18n_key}"
+        )
+      end
+
+      def title_for_edit(record)
+        first_present_value(
+          translate(
+            "title",
+            default: nil,
+            model: singular_name,
+            record: repository.title(record),
+            scope: i18n_scope(:edit)
+          ),
+          link_to_edit(record)
+        )
+      end
+
+      def title_for_index
+        translate(
+          "title",
+          default: plural_name,
+          model: singular_name,
+          scope: i18n_scope(:index)
+        )
+      end
+
+      def title_for_show(record)
+        return repository.title(record) if record
+
+        translate(
+          "title",
+          default: plural_name,
+          model: singular_name,
+          scope: i18n_scope(:show)
+        )
+      end
+
+      # Returns the title for the "new" page.
+      #
+      # Returns the first of the following translations that is present:
+      # 1. Translation from "uchi.repository.[name].new.title"
+      # 2. Translation from "uchi.repository.[name].button.link_to_new"
+      # 3. Translation from "uchi.common.new" with interpolation key %{model}
+      # 4. Default string "New %{model}"
+      def title_for_new
+        first_present_value(
+          translate(i18n_scope("new.title"), default: nil),
+          link_to_new
+        )
+      end
+
+      private
+
+      # Returns the first translation that yields a present value by looking
+      # through each key in keys in order.
+      def first_present_value(*values)
+        values.find(&:presence)
+      end
+
+      # Returns the segment of the i18n key specific to this repository.
+      def i18n_key
+        @repository.model.model_name.i18n_key
+      end
+
+      def i18n_scope(section = nil)
+        [
+          "uchi.repository",
+          i18n_key,
+          section
+        ].compact.join(".")
+      end
+
+      def model
+        @model ||= repository.model
+      end
+
+      # Returns the localized, human-readable singular name of the model this
+      # repository manages.
+      def singular_name
+        ::I18n.translate(
+          "uchi.repository.#{i18n_key}.model",
+          count: 1,
+          default: model.model_name.human(count: 1)
+        )
+      end
+
+      def title_for_record(record)
+        return nil unless record
+
+        repository.title(record)
+      end
+
+      def translate(key, **options)
+        Uchi::I18n.translate(key, **options)
+      end
+    end
+  end
+end

data/lib/uchi/repository.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "repository/routes"
+
+module Uchi
+  class Repository
+    class << self
+      # Returns all defined Uchi::Repository classes
+      def all
+        Uchi::Repositories.constants.map { |const_name|
+          Uchi::Repositories.const_get(const_name)
+        }
+      end
+
+      # Returns the repository for the given model, or nil if none is found.
+      def for_model(model)
+        all.find { |repository| repository.model.to_s == model.to_s }
+      end
+
+      # Returns the model class this repository manages.
+      def model
+        @model ||= name.demodulize.constantize
+      end
+    end
+
+    # Returns a new, unsaved instance of the model this repository manages.
+    def build(attributes = {})
+      model.new(attributes)
+    end
+
+    # Returns the "name" of the controller that handles requests for this
+    # repository. Note that this is different from the controllers class name
+    # and is intended for generating URLs.
+    def controller_name
+      model_param_key.pluralize
+    end
+
+    def default_sort_order
+      SortOrder.new(:id, :asc)
+    end
+
+    # Returns an array of fields to show on the edit page.
+    def fields_for_edit
+      fields.select { |field| field.on.include?(:edit) }.each { |field| field.repository = self }
+    end
+
+    # Returns an array of fields to show on the index page.
+    def fields_for_index
+      fields.select { |field| field.on.include?(:index) }.each { |field| field.repository = self }
+    end
+
+    # Returns an array of fields to show on the show page.
+    def fields_for_show
+      fields.select { |field| field.on.include?(:show) }.each { |field| field.repository = self }
+    end
+
+    def find_all(search: nil, scope: model.all, sort_order: default_sort_order)
+      scope ||= model.all
+      query = scope.includes(includes)
+      query = apply_search(query, search)
+      apply_sort_order(query, sort_order)
+    end
+
+    def find(id)
+      model.find(id)
+    end
+
+    # Returns the list of associations to include when querying for records.
+    #
+    # See
+    # https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-includes
+    # for further details.
+    def includes
+      []
+    end
+
+    def model
+      self.class.model
+    end
+
+    def model_param_key
+      model.model_name.param_key
+    end
+
+    # Returns an instance of Uchi::Repository::Routes for this repository,
+    # which can be used to generate paths and URLs.
+    #
+    # @return [Uchi::Repository::Routes]
+    def routes
+      @routes ||= Routes.new(self)
+    end
+
+    # Returns true if this repository has at least one searchable field.
+    #
+    # @return [Boolean]
+    def searchable?
+      searchable_fields.any?
+    end
+
+    # Returns the title to show for a given record. By default, this method
+    # returns the value of the first of the following methods that exist:
+    #
+    # 1. `name`
+    # 2. `title`
+    # 3. `to_s`
+    #
+    # You can override this method in your repository subclass to provide
+    # custom logic.
+    def title(record)
+      return nil unless record
+
+      [:name, :title, :to_s].each do |method|
+        if record.respond_to?(method)
+          return record.public_send(method)
+        end
+      end
+    end
+
+    # Provides access to translation helpers specific to this repository.
+    def translate
+      @translate ||= Translate.new(repository: self)
+    end
+
+    private
+
+    def apply_search(query, search)
+      return query unless search.present?
+      return query if searchable_fields.empty?
+
+      search = search.strip
+      conditions = searchable_fields.map { |field|
+        arel_field = model.arel_table[field.name]
+        Arel::Nodes::NamedFunction.new(
+          "CAST",
+          [arel_field.as(Arel::Nodes::SqlLiteral.new("VARCHAR"))]
+        ).matches("%#{search}%")
+      }
+      query.where(conditions.inject(:or))
+    end
+
+    def apply_sort_order(query, sort_order)
+      field_to_sort_by = fields.find { |field| field.name == sort_order.name }
+      return query unless field_to_sort_by
+
+      if field_to_sort_by.sortable.respond_to?(:call)
+        field_to_sort_by.sortable.call(query, sort_order.direction)
+      else
+        sort_order.apply(query)
+      end
+    end
+
+    def searchable_fields
+      @searchable_fields ||= fields.select { |field| field.searchable? }
+    end
+  end
+end

data/lib/uchi/sort_order.rb

@@ -0,0 +1,35 @@
+module Uchi
+  class SortOrder
+    attr_reader :name, :direction
+
+    class << self
+      def from_params(params)
+        sort_params = params[:sort] || {}
+        return nil if sort_params.empty?
+
+        by = sort_params[:by]
+        return by unless by
+
+        direction = sort_params[:direction] || :asc
+        new(by, direction)
+      end
+    end
+
+    def ascending?
+      direction == :asc
+    end
+
+    def apply(query)
+      query.order(name => direction)
+    end
+
+    def descending?
+      direction == :desc
+    end
+
+    def initialize(name, direction)
+      @name = name.to_sym
+      @direction = direction.to_sym
+    end
+  end
+end

data/lib/uchi/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Uchi
+  VERSION = "0.1.5"
+end

data/lib/uchi.rb

@@ -0,0 +1,18 @@
+gem "turbo-rails"
+require "turbo-rails"
+
+gem "view_component"
+require "view_component"
+
+require "uchi/version"
+require "uchi/engine"
+
+require "uchi/field"
+require "uchi/i18n"
+require "uchi/repository"
+require "uchi/sort_order"
+require "uchi/repository/translate"
+
+module Uchi
+  # Your code goes here...
+end

data/uchi.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/uchi/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "uchi"
+  spec.version = Uchi::VERSION
+  spec.authors = ["Jakob Skjerning"]
+  spec.email = ["jakob@substancelab.com"]
+
+  spec.summary = "Build usable and extensible admin panels for your Ruby on Rails application in minutes."
+  spec.description = "Level up your scaffolds with a modern admin backend framework, designed for Rails developers who demand both beauty, functionality, and extensibility. Uchi provides a set of components and conventions for creating user interfaces that are both powerful and easy to use."
+  spec.homepage = "https://www.uchiadmin.com/"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["changelog_uri"] = "https://github.com/substancelab/uchi/blob/main/CHANGELOG.md"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/substancelab/uchi"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = \
+    Dir["app/**/*"] +
+    Dir["lib/**/*"] +
+    [
+      "README.md",
+      "uchi.gemspec"
+    ]
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 7.2"
+  spec.add_dependency "turbo-rails"
+  spec.add_dependency "view_component", ">= 4.0"
+end