solidus_admin 0.2.0 → 0.3.0

data/docs/stimulusjs.md

@@ -0,0 +1,85 @@
+# StimulusJS
+
+This project uses [StimulusJS](https://stimulusjs.org) to add interactivity to the admin interface.
+
+## Using ther `stimulus_id` helper
+
+All JavaScript files are imported using `import-maps`, eliminating the need for compilation.
+
+Any `component.js` file is automatically loaded as a StimulusJS controller. The component path is used as the identifier, which is achieved by using `parameterize` and replacing `/` with `--`.
+For example, `app/components/solidus_admin/foo/component.js` is loaded as `solidus-admin--foo`..
+
+To simplify the use of StimulusJS controllers in components, a `stimulus_id` helper is provided.
+This helper ensures that the controller identifier is correctly used every time.
+
+```erb
+<div
+  data-controller="<%= stimulus_id %>"
+  data-action="click-><%= stimulus_id %>#doSomething"
+  data-<%= stimulus_id %>-foo-value="123"
+>
+  ...
+</div>
+```
+
+## Coding Style
+
+Besides the standard StimulusJS conventions, we have a few additional tricks to make the code more readable and maintainable.
+
+### Separating the state from the DOM
+
+Whenever the controller gets beyond trivial we try to separate the state from DOM updates using a `render()` method.
+
+```js
+import { Controller } from "stimulus"
+
+export default class extends Controller {
+  static targets = [ "details" ]
+
+  connect() {
+    this.render()
+  }
+
+  show() {
+    this.open = true
+  }
+
+  render() {
+    this.detailsTarget.hidden = !this.open
+  }
+}
+```
+
+### Using values to communicate with the external world
+
+Values are an excellent tool for communicating with the external environment and representing state.
+Any change to them will be reflected in the DOM and the change callbacks provided by StimulusJS are a great way to react to state changes.
+
+```js
+import { Controller } from "stimulus"
+
+export default class extends Controller {
+  static values = { open: Boolean }
+
+  connect() {
+    this.render()
+  }
+
+  show() {
+    this.openValue = true
+  }
+
+  openValueChanged() {
+    this.render()
+  }
+
+  render() {
+    this.detailsTarget.hidden = !this.openValue
+  }
+}
+```
+
+## Leveraging stimulus-use
+
+Solidus Admin leverages [stimulus-use](https://github.com/stimulus-use/stimulus-use/), an external library that offers a collection of composable behaviors for Stimulus Controllers. These mixins greatly simplify the work of developers and can be used when adding new components.
+For more information, please refer to the project doc. You can also find examples of usage in the Admin codebase (for instance, `useClickOutside` and `useDebounce` mixins are used in admin components).

data/docs/{customizing_tailwindcss.md → tailwindcss.md}

@@ -1,4 +1,4 @@
-# Customizing TailwindCSS
+# Tailwind CSS for the Admin UI
 
 Solidus Admin uses [Tailwind CSS](https://tailwindcss.com/) for styling. The
 benefit of using Tailwind is that it allows you to customize the look and feel
@@ -12,11 +12,28 @@ In case you need to customize the admin's look and feel, or create custom
 components, you can do so by running Tailwind's build process in your host
 application.
 
-This process presumes that you have a working knowledge of Tailwind CSS. If you
-are not familiar with Tailwind, please refer to the [Tailwind
-documentation](https://tailwindcss.com/docs) for more information.
+This process presumes that you have a working knowledge of Tailwind CSS.
+If you are not familiar with Tailwind, please refer to the [Tailwind documentation](https://tailwindcss.com/docs) for more information.
 
-## Setting up a local TailwindCSS build for Solidus Admin
+## Coding Style
+
+The provided Tailwind CSS configuration is as vanilla as possible, with little to no customizations.
+We aim to stay within the boundaries of the default Tailwind CSS classes and avoid custom classes.
+Occasionally, we need to add custom styles and in such cases we try to use dynamic square brackets classes.
+
+CSS classes are all kept in the HTML templates of the components in order to simplify the configuration.
+
+The few customizations we have added, are through plugins as they support not only classes but also variants.
+
+## Releasing with a precompiled Tailwind CSS
+
+Solidus Admin Tailwind CSS stylesheets are precompiled and included in Solidus gems released to Rubygems.
+
+This means that there's no need to compile the admin Tailwind CSS file in the host application.
+
+The compiled file is not included in the git repository, but it is generated and incorporated in the gem as part of the `rake release` task (see releasing instructions). This approach completely removes the potential noise created by committing that file to the repository, and the need to keep it updated in pull requests that should affect it.
+
+## Customizing TailwindCSS
 
 In order to customize the admin's look and feel, you'll need to set up a local
 Tailwind build. This is a two-step process:
@@ -48,10 +65,12 @@ Or, to watch for changes and automatically rebuild the CSS file, run:
 bin/rails solidus_admin:tailwindcss:watch
 ```
 
-## Caveats
-
-### Conflict with sassc-rails
+## Caveat: Conflict with sassc-rails
 
 Tailwind uses modern CSS features that are not recognized by the sassc-rails extension that was included by default in the Gemfile for Rails 6. In order to avoid any errors like SassC::SyntaxError, you must remove that gem from your Gemfile.
 
 *See https://github.com/rails/tailwindcss-rails#conflict-with-sassc-rails.*
+
+## Development
+
+The main solidus `bin/dev` command will automatically compile the Tailwind CSS stylesheets and watch for changes.

data/lib/solidus_admin/component_registry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  class ComponentRegistry
+    ComponentNotFoundError = Class.new(NameError)
+
+    def initialize
+      @names = {}
+    end
+
+    def []=(key, value)
+      @names[key] = value
+    end
+
+    def [](key)
+      if @names[key]
+        @names[key].constantize
+      else
+        infer_constant_from(key)
+      end
+    end
+
+    private
+
+    def infer_constant_from(key)
+      "solidus_admin/#{key}/component".classify.constantize
+    rescue NameError
+      prefix = "#{SolidusAdmin::Configuration::ENGINE_ROOT}/app/components/solidus_admin/"
+      suffix = "/component.rb"
+      dictionary = Dir["#{prefix}**#{suffix}"].map { _1.delete_prefix(prefix).delete_suffix(suffix) }
+      corrections = DidYouMean::SpellChecker.new(dictionary: dictionary).correct(key.to_s)
+
+      raise ComponentNotFoundError.new(
+        "Unknown component #{key}#{DidYouMean.formatter.message_for(corrections)}",
+        key.classify,
+        receiver: ::SolidusAdmin
+      )
+    end
+  end
+end

data/lib/solidus_admin/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spree/preferences/configuration'
+require 'solidus_admin/component_registry'
 
 module SolidusAdmin
   # Configuration for the admin interface.
@@ -8,7 +9,6 @@ module SolidusAdmin
   # Ensure requiring this file after the Rails application has been created,
   # as some defaults depend on the application context.
   class Configuration < Spree::Preferences::Configuration
-    ComponentNotFoundError = Class.new(NameError)
     ENGINE_ROOT = File.expand_path("#{__dir__}/../..")
 
     # Path to the logo used in the admin interface.
@@ -111,13 +111,6 @@ module SolidusAdmin
           ]
         },
 
-        {
-          key: "promotions",
-          route: -> { spree.admin_promotions_path },
-          icon: "megaphone-line",
-          position: 30,
-        },
-
         {
           key: "stock",
           route: -> { spree.admin_stock_items_path },
@@ -187,24 +180,7 @@ module SolidusAdmin
     end
 
     def components
-      @components ||= Hash.new do |_h, k|
-        const_name = "solidus_admin/#{k}/component".classify
-
-        unless Object.const_defined?(const_name)
-          prefix = "#{ENGINE_ROOT}/app/components/solidus_admin/"
-          suffix = "/component.rb"
-          dictionary = Dir["#{prefix}**#{suffix}"].map { _1.delete_prefix(prefix).delete_suffix(suffix) }
-          corrections = DidYouMean::SpellChecker.new(dictionary: dictionary).correct(k.to_s)
-
-          raise ComponentNotFoundError.new(
-            "Unknown component #{k}#{DidYouMean.formatter.message_for(corrections)}",
-            k.classify,
-            receiver: ::SolidusAdmin
-          )
-        end
-
-        const_name.constantize
-      end
+      @components ||= ComponentRegistry.new
     end
 
     # The method used to authenticate the user in the admin interface, it's expected to redirect the user to the login method

data/lib/solidus_admin/install_tailwindcss.rb

@@ -73,7 +73,9 @@ create_file "lib/tasks/solidus_admin/tailwind.rake", <<~RUBY
   end
 RUBY
 
-append_file ".gitignore", "app/assets/builds/solidus_admin/"
+if Rails.root.join(".gitignore").exist?
+  append_file ".gitignore", "app/assets/builds/solidus_admin/"
+end
 
 unless Rails.root.join("Procfile.dev").exist?
   create_file "Procfile.dev", <<~YAML

data/lib/solidus_admin/testing_support/admin_assets.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  config.when_first_matching_example_defined(solidus_admin: true) do
+    config.before(:suite) do
+      system('bin/rails solidus_admin:tailwindcss:build') or abort 'Failed to build Tailwind CSS'
+      Rails.application.precompiled_assets
+    end
+  end
+end

data/lib/solidus_admin/testing_support/component_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  module TestingSupport
+    module ComponentHelpers
+      # Mocks a component class with the given definition.
+      #
+      # @param definition [Proc] the component definition
+      # @example
+      #  mock_component do
+      #    def call
+      #      "Rendered"
+      #    end
+      #  end
+      def mock_component(&definition)
+        location = caller(1, 1).first
+        component_class = Class.new(SolidusAdmin::BaseComponent)
+        # ViewComponent will complain if we don't fake a class name:
+        # @see https://github.com/ViewComponent/view_component/blob/5decd07842c48cbad82527daefa3fe9c65a4226a/lib/view_component/base.rb#L371
+        component_class.define_singleton_method(:name) { "Foo" }
+        component_class.define_singleton_method(:to_s) { "#{name} (#{location})" }
+        component_class.class_eval(&definition) if definition
+        component_class
+      end
+    end
+  end
+end

data/lib/solidus_admin/testing_support/dummy_app/rake_tasks.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+namespace :solidus_admin do
+  namespace :tailwindcss do
+    desc "Build Tailwind CSS"
+    task build: :dummy_environment do
+      require "solidus_admin"
+      require "tailwindcss/commands"
+
+      config_file = <<~JS
+        const adminRoot = "#{SolidusAdmin::Engine.root}"
+        const solidusAdmin = require(`${adminRoot}/config/tailwind.config.js`)
+
+        module.exports = {
+          // Read how to use TailwindCSS presets: https://tailwindcss.com/docs/presets.
+          presets: [solidusAdmin],
+
+          content: [
+            // Include paths coming from SolidusAdmin.
+            ...solidusAdmin.content,
+
+            // Include paths to your own components.
+            `${__dirname}/../../../../app/components/admin/**/*`,
+            `${__dirname}/../../../../lib/components/admin/**/*`,
+          ],
+        }
+      JS
+      FileUtils.mkdir_p(DummyApp::Application.root.join("config"))
+      File.write(DummyApp::Application.root.join("config/tailwind.config.js"), config_file)
+      FileUtils.mkdir_p(DummyApp::Application.root.join("app/assets/stylesheets/solidus_admin"))
+      FileUtils.cp(
+        SolidusAdmin::Engine.root.join("app/assets/stylesheets/solidus_admin/application.tailwind.css"),
+        DummyApp::Application.root.join("app/assets/stylesheets/solidus_admin/application.tailwind.css")
+      )
+
+      tailwindcss = Tailwindcss::Commands.executable
+
+      tailwindcss_command = [
+        tailwindcss,
+        "--config", DummyApp::Application.root.join("config/tailwind.config.js"),
+        "--input", DummyApp::Application.root.join("app/assets/stylesheets/solidus_admin/application.tailwind.css"),
+        "--output", DummyApp::Application.root.join("assets/builds/solidus_admin/tailwind.css")
+      ]
+
+      sh tailwindcss_command.shelljoin
+    end
+  end
+end
+
+# Attach Tailwind CSS build to other tasks.
+%w[
+  assets:precompile
+  test:prepare
+  spec:prepare
+  db:test:prepare
+].each do |task_name|
+  next unless Rake::Task.task_defined?(task_name)
+
+  Rake::Task[task_name].enhance(["solidus_admin:tailwindcss:build"])
+end

data/lib/solidus_admin/testing_support/feature_helpers.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  module TestingSupport
+    module FeatureHelpers
+      def sign_in(user)
+        allow_any_instance_of(SolidusAdmin::BaseController).to receive(:spree_current_user).and_return(user)
+      end
+
+      def stub_authorization!(user)
+        ability = Spree::Ability.new(user)
+        if block_given?
+          yield ability
+        else
+          ability.can :manage, :all
+        end
+        allow_any_instance_of(SolidusAdmin::BaseController).to receive(:current_ability).and_return(ability)
+        allow_any_instance_of(Spree::Admin::BaseController).to receive(:current_ability).and_return(ability)
+      end
+
+      def find_row(text)
+        find('table tbody tr', text: text)
+      end
+
+      def find_row_checkbox(text)
+        find_row(text).find('td:first-child input[type="checkbox"]')
+      end
+
+      def select_row(text)
+        find_row_checkbox(text).check
+      end
+    end
+  end
+end

data/lib/solidus_admin/version.rb

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

data/solidus_admin.gemspec

@@ -12,11 +12,15 @@ Gem::Specification.new do |s|
 
   s.author      = 'Solidus Team'
   s.email       = 'contact@solidus.io'
-  s.homepage    = 'http://solidus.io'
+  s.homepage    = 'https://github.com/solidusio/solidus/blob/main/admin/README.md'
   s.license     = 'BSD-3-Clause'
 
   s.metadata['rubygems_mfa_required'] = 'true'
 
+  s.metadata["homepage_uri"] = s.homepage
+  s.metadata["source_code_uri"] = "https://github.com/solidusio/solidus/tree/main/api"
+  s.metadata["changelog_uri"] = "https://github.com/solidusio/solidus/releases?q=%22solidus_admin%2Fv0%22&expanded=true"
+
   s.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(spec|script)/})
   end + ["app/assets/builds/solidus_admin/tailwind.css"]
@@ -29,6 +33,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'solidus_backend'
   s.add_dependency 'solidus_core', '> 4.2'
   s.add_dependency 'stimulus-rails', '~> 1.2'
-  s.add_dependency 'turbo-rails', '~> 1.4'
-  s.add_dependency 'view_component', '~> 3.3'
+  s.add_dependency 'turbo-rails', '~> 2.0'
+  s.add_dependency 'view_component', '~> 3.9'
 end