solidus_admin 0.0.0 → 0.0.2

data/config/locales/products.en.yml

@@ -0,0 +1,10 @@
+en:
+  solidus_admin:
+    products:
+      title: "Products"
+      destroy:
+        success: "Products were successfully removed."
+      discontinue:
+        success: "Products were successfully discontinued."
+      activate:
+        success: "Products were successfully activated."

data/config/routes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+SolidusAdmin::Engine.routes.draw do
+  resource :account, only: :show
+  resources :products, only: [:index, :show, :edit, :update] do
+    collection do
+      delete :destroy
+      put :discontinue
+      put :activate
+    end
+  end
+  resources :orders, only: :index
+end

data/config/solidus_admin/tailwind.config.js.erb

@@ -0,0 +1,95 @@
+const defaultTheme = require('tailwindcss/defaultTheme')
+const plugin = require('tailwindcss/plugin')
+
+module.exports = {
+  content: [
+    <%= SolidusAdmin::Config.tailwind_content.map { "'#{_1}'" }.join(",\n    ") %>
+  ],
+  theme: {
+    extend: {
+      aria: {
+        'current': 'current="true"',
+      },
+      fontFamily: {
+        sans: ['Inter var', ...defaultTheme.fontFamily.sans],
+      },
+      colors: {
+        transparent: "transparent",
+        current: "currentColor",
+
+        // Primary palette
+        solidusRed: "#ef3023",
+        black: "#222222",
+        graphite: "#c7ccc7",
+        graphiteLight: "#d8dad8",
+        sand: "#f5f3f0",
+        white: "#ffffff",
+
+        // Secondary palette
+        yellow: "#fdc071",
+        orange: "#f68050",
+        blue: "#2554b1",
+        moss: "#2d3925",
+        forest: "#096756",
+        midnight: "#163449",
+        pink: "#f6d7e2",
+        plum: "#3a0e31",
+        sky: "#cbdff1",
+        seafoam: "#c1e0de",
+        dune: "#e6bf9b",
+
+        // Extra colors (not part of the original palette)
+        papayaWhip: "#f9e3d9",
+
+        // UI Red
+        red: {
+          100: "#f8d6d3",
+          200: "#f1ada7",
+          300: "#ea8980",
+          400: "#e36054",
+          500: "#dc3728",
+          600: "#b12c20",
+          700: "#862219",
+          800: "#561610",
+          900: "#2b0b08",
+        },
+
+        // Grayscale
+        gray: {
+          15: "#fafafa",
+          25: "#f5f5f5",
+          50: "#f0f0f0",
+          100: "#dedede",
+          200: "#cfcfcf",
+          300: "#bababa",
+          400: "#a3a3a3",
+          500: "#737373",
+          600: "#616161",
+          700: "#4a4a4a",
+          800: "#333333",
+        },
+      },
+      borderRadius: {
+        sm: '4px',
+      },
+      backgroundImage: {
+        'arrow-right-up-line': "url('solidus_admin/arrow_right_up_line.svg')",
+        'arrow-down-s-fill-gray-700': "url('solidus_admin/arrow_down_s_fill_gray_700.svg')",
+        'arrow-down-s-fill-red-400': "url('solidus_admin/arrow_down_s_fill_red_400.svg')",
+      },
+      boxShadow: {
+        sm: '0px 1px 2px 0px rgba(0, 0, 0, 0.04)',
+        base: '0px 4px 8px 0px rgba(0, 0, 0, 0.08), 0px 2px 4px -1px rgba(0, 0, 0, 0.04)'
+      },
+    },
+  },
+  plugins: [
+    require('@tailwindcss/forms')({ strategy: 'class' }),
+    require('@tailwindcss/aspect-ratio'),
+    require('@tailwindcss/typography'),
+    require('@tailwindcss/container-queries'),
+    plugin(({ addVariant }) => addVariant('hidden', '&([hidden])')),
+    plugin(({ addVariant }) => addVariant('visible', '&:not([hidden])')),
+    plugin(({ addVariant }) => addVariant('search-cancel', '&::-webkit-search-cancel-button')),
+  ]
+}

data/docs/customizing_main_navigation.md

@@ -0,0 +1,42 @@
+# Customizing the main navigation
+
+You are allowed to add your custom links to the main navigation. To do so, you can access `SolidusAdmin::Config.main_nav` in an initializer:
+
+```ruby
+# config/initializers/solidus_admin.rb
+SolidusAdmin::Config.menu_items << {
+  key: :my_custom_link,
+  route: :my_custom_link_path,
+  icon: "24-hours-fill",
+  position: 80
+}
+```
+
+- The key you provide will be used to translate the link's label under the
+`solidus_admin.main_nav.#{key}` key.
+- Icon needs to be an icon name from [Remixicon](https://remixicon.com/).
+- Position tells Solidus where to place the link in the main navigation. The
+ default items are placed with 10 points of difference between them.
+
+For nested links, you can provide a `children:` option with an array of hashes:
+
+```ruby
+# config/initializers/solidus_admin.rb
+SolidusAdmin::Config.configure do |config|
+  config.menu_items << {
+    key: :my_custom_link,
+    route: :my_custom_link_path,
+    icon: "24-hours-fill",
+    position: 80,
+    children: [
+      {
+        key: :my_custom_nested_link,
+        route: :my_custom_nested_link_path,
+        position: 80
+      }
+    ]
+  }
+end
+```
+
+Your custom link will be rendered in the active state when its base path (i.e, the path without the query string) matches the one for the current url.

data/docs/customizing_tailwind.md

@@ -0,0 +1,78 @@
+# Customizing tailwind
+
+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
+of the admin without having to write any CSS. By leveraging utility classes,
+you can easily change the colors, fonts, and spacing in use.
+
+Solidus Admin sets up Tailwind in a way that allows customization. When you
+install `solidus_admin`, its compiled CSS file is generated at
+`app/assets/builds/solidus_admin/tailwind.css`. As we'll see below, there are
+different ways in which you can add your styles to it. There are a couple of
+tasks you can run to recompile the CSS file:
+
+- `bin/rails solidus_admin:tailwindcss:build` - compiles the CSS file once.
+- `bin/rails solidus_admin:tailwindcss:watch` - compiles the CSS file and
+  watches for changes.
+
+When deploying to production, the build task is automatically added as part of
+the assets precompilation process.
+
+### Adding new paths to Tailwind
+
+Tailwind generates its CSS by scanning a configured set of paths for CSS
+classes. By default, Solidus Admin will add to this list the following globs
+from your host application:
+
+- `app/components/solidus_admin/**/*.rb`
+- `app/views/solidus_admin/**/*.{erb,haml,html,slim}`
+- `app/helpers/solidus_admin/**/*.rb`
+- `app/assets/javascripts/solidus_admin/**/*.js`
+- `public/solidus_admin/*.html`
+
+If that flexibility is not enough, you can add your own paths by appending the
+`SolidusAdmin::Config.tailwind_content` setting:
+
+```ruby
+# config/initializers/solidus_admin.rb
+SolidusAdmin::Config.tailwind_content << Rails.root.join("app/my/custom/path/**/*.rb")
+```
+
+> ⚠ Remember to re-run the `build` or `watch` tasks after changing this setting.
+
+### Adding custom CSS
+
+If you need advanced Tailwind customization, you can also create your own CSS
+file and append it to the Solidus Admin's default one. Be aware that's
+[considered a last-resort option](https://tailwindcss.com/docs/reusing-styles)
+according to Tailwind's philosophy, and most of the time you should be ok by
+making use of the available Tailwind classes.
+
+In case you need to do it, you can append your CSS file by pushing it to the
+`SolidusAdmin.tailwind_stylesheets` array:
+
+```ruby
+# config/initializers/solidus_admin.rb
+SolidusAdmin.tailwind_stylesheets << Rails.root.join("app/my/custom/path/my_styles.css")
+```
+
+> ⚠ Remember to re-run the `build` or `watch` tasks after changing this setting.
+
+## Acquiring full control over Tailwind configuration
+
+For very advanced use cases, it's possible to bail out of the Solidus Admin's
+managed Tailwind configuration and get a grip on it yourself. This is not
+recommended, as it will make your app more brittle to future changes in Solidus
+Admin, so do it at your own risk!
+
+There are a couple of tasks you can run for that:
+
+- `bin/rails solidus_admin:tailwindcss:override_config` - copies the default
+  Tailwind configuration file to `config/solidus_admin/tailwind.config.js.erb`.
+- `bin/rails solidus_admin:tailwindcss:override_stylesheet` - copies the
+  default Tailwind stylesheet file to
+  `app/assets/stylesheets/solidus_admin/application.tailwind.css.erb`.
+
+Notice that, unlike in a regular Tailwind setup, the config and stylesheet
+files are ERB templates. This is because they need to be able to access the
+Solidus Admin and application paths.

data/docs/customizing_view_components.md

@@ -0,0 +1,153 @@
+# Customizing view components
+
+Solidus Admin uses [view components](https://viewcomponent.org/) to render the views. Components are
+a pattern for breaking up the view layer into small, reusable pieces, easy to
+reason about and test.
+
+All the components Solidus Admin uses are located in the [`app/components`](../app/components) folder of the
+`solidus_admin` gem. As you can see, they are organized in a particular folder structure:
+
+- All of them are under the `SolidusAdmin` namespace.
+- They are grouped in sidecar directories, where the main component file and
+  all its related files (assets, i18n files, etc.) live together.
+
+For instance, the component for the main navigation is located in
+[`app/components/solidus_admin/main_nav/component.rb`](../app/components/solidus_admin/main_nav/component.rb).
+
+Solidus Admin components are designed to be easily customizable by the host
+application. Because of that, if you look at how they are designed, you'll find
+a series of patterns are followed consistently:
+
+- Components are always resolved from a global registry in
+  `SolidusAdmin::Config.components` instead of being referenced by their constant. For
+  example, we call `component('main_nav')` instead of referencing
+  `SolidusAdmin::MainNav::Component` directly. As you'll see later, this makes
+  it easy to replace or tweak a component.
+- It's possible to override the registry locally inside a component by redefining
+  the `#component` method. This is useful when you need to use a component that
+  is not registered in the global registry or need to address some edge case.
+- In any case, Solidus Admin components initializers only take keyword
+  arguments.
+
+A picture is worth a thousand words, so let's depict how this works with an
+example:
+
+```ruby
+# app/components/solidus_admin/foo/component.rb
+class SolidusAdmin::Foo::Component < SolidusAdmin::BaseComponent
+  def component(key)
+    return MyApplication::Bar::Component if key == 'bar'
+
+    super
+  end
+
+  erb_template <<~ERB
+    <div>
+      <%= render component('bar').new %>
+    </div>
+  ERB
+end
+# render component('foo').new
+```
+
+## Customizing components
+
+Some of the customizations detailed below require you to match Solidus Admin's
+component paths in your application. For instance, if we talk about the
+component in `solidus_admin` gem's
+`app/components/solidus_admin/main_nav/component.rb`, the matching path in your
+application would be
+`app/components/my_application/solidus_admin/main_nav/component.rb`, where
+`my_application` is the underscored name of your application (you can get it by
+running `Rails.application.class.module_parent_name`).
+
+### Replacing a component's template
+
+In the most typical case, you'll only need to replace the template used by a
+component. You can do that by creating a new component with a maching path in
+your application, inheriting from the default one. Then, you can create a new
+template for it. For example, to replace the main nav template:
+
+```erb
+# app/components/my_application/solidus_admin/main_nav/component.rb %>
+class MyApplication::SolidusAdmin::MainNav::Component < ::SolidusAdmin::MainNav::Component
+end
+
+<%# app/components/my_application/solidus_admin/main_nav/component.html.erb %>
+<nav class="my_own_classes">
+  <%=
+    render main_nav_item_component.with_collection(
+      sorted_items
+    )
+  %>
+</nav>
+```
+
+### Prepending or appending to a component's template
+
+In some situations, you might only need to add some markup before or after a
+component. You can easily do that by rendering the Solidus Admin component and
+adding your markup before or after it.
+
+```erb
+<%# app/components/my_application/solidus_admin/main_nav/component.html.erb %>
+<h1>MY STORE ADMINISTRATION</h1>
+<%= render SolidusAdmin::MainNav::Component.new %>
+```
+
+### Replacing a component
+
+You can replace a component by creating a new one with a matching path in your
+application.
+
+There are two considerations to keep in mind:
+
+- Be aware that other components might be using the component you're replacing.
+  They should only be using its `#initialize` method, so make sure to keep
+  compatibility with it when they're called.
+- Solidus Admin's components always inherit from
+  [SolidusAdmin::BaseComponent](../app/components/solidus_admin/base_component.rb).
+  You can consider doing the same if you need to use one of its helpers.
+
+For example, the following replaces the main nav component:
+
+```ruby
+# app/components/my_application/solidus_admin/main_nav/component.rb
+class MyApplication::SolidusAdmin::MainNav::Component < SolidusAdmin::BaseComponent
+  # do your thing
+end
+```
+
+If you need more control, you can explicitly register your component in the
+Solidus Admin container instead of using an implicit path:
+
+> ⓘ  Right now, that will raise an error when the application is reloaded. We
+> need to fix it.
+
+```ruby
+# config/initalizers/solidus_admin.rb
+Rails.application.config.to_prepare do
+  SolidusAdmin::Config.components['ui/button'] = MyApplication::Button::Component
+end
+```
+
+### Tweaking a component
+
+If you only need to tweak a component, you can always inherit from it in a
+matching path from within your application (or manually add it to the
+registry) and override the methods you need to change:
+
+```ruby
+# app/components/my_application/solidus_admin/main_nav/component.rb
+class MyApplication::SolidusAdmin::MainNav::Component < ::SolidusAdmin::MainNav::Component
+  def sorted_items
+    super.reverse
+  end
+end
+```
+
+Be aware that this approach comes with an important trade-off: You'll need to
+keep your component in sync with the original one as it changes on future updates.
+For instance, in the example above, the component is overriding a private
+method, so there's no guarantee that it will continue to exist in the future
+without being deprecated, as we only guarantee public API stability.

data/lib/generators/solidus_admin/component/USAGE

@@ -0,0 +1,13 @@
+Description:
+
+    Creates a SolidusAdmin component.
+
+Example:
+
+    $ bin/rails generate solidus_admin:component my_namespace/my_module_name my_attribute
+
+          create  app/components/my_namespace/my_module_name/component.rb
+          create  app/components/my_namespace/my_module_name/component.html.erb
+          create  app/components/my_namespace/my_module_name/component.yml
+          create  app/components/my_namespace/my_module_name/component.js
+          create  spec/components/my_namespace/my_module_name/component_spec.rb

data/lib/generators/solidus_admin/component/component_generator.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  class ComponentGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
+
+    argument :attributes, type: :array, default: [], banner: "attribute"
+
+    class_option :html, type: :boolean, default: true
+    class_option :i18n, type: :boolean, default: true
+    class_option :js, type: :boolean, default: true
+    class_option :spec, type: :boolean, default: true
+    class_option :preview, type: :boolean, default: true
+
+    def setup_inflections
+      # This is needed because the generator won't run the initialization process,
+      # in order to ensure that UI is not rendered as Ui we need to setup inflections
+      # manually.
+      SolidusAdmin::Engine.initializers.find { _1.name =~ /inflections/ }.run
+    end
+
+    def create_component_files
+      template "component.html.erb", destination(".html.erb")
+      unless options["html"]
+        say_status :inline, destination(".html.erb"), :blue
+        @inline_html = File.read(destination(".html.erb"))
+        shell.mute { remove_file(destination(".html.erb")) }
+      end
+      template "component.rb", destination(".rb")
+      template "component.yml", destination(".yml") if options["i18n"]
+      template "component.js", destination(".js") if options["js"]
+      template "component_spec.rb", destination("_spec.rb", root: "spec/components") if options["spec"]
+
+      if options["preview"]
+        preview_destination_path = destination("_preview.rb", root: "spec/components/previews")
+        template "component_preview.rb", preview_destination_path
+        template "component_preview_overview.html.erb", preview_destination_path.sub(/\.rb/, '/overview.html.erb')
+      end
+    end
+
+    private
+
+    def component_registry_id
+      [class_path.presence, file_name].compact.join("/")
+    end
+
+    def destination(suffix, root: "app/components")
+      File.join(root, class_path, file_name, "component#{suffix}")
+    end
+
+    def file_name
+      @_file_name ||= super.sub(/_component\z/i, "")
+    end
+
+    def dom_class
+      [class_path.presence, file_name].compact.join("/").tr("_", "-").gsub("/", "--")
+    end
+
+    def stimulus_controller_name
+      dom_class
+    end
+
+    def stimulus_attributes
+      ' data-controller="<%= stimulus_id %>"'
+    end
+
+    def initialize_signature
+      return if attributes.blank?
+
+      attributes.map { |attr| "#{attr.name}:" }.join(", ")
+    end
+
+    def initialize_body
+      attributes.map { |attr| "@#{attr.name} = #{attr.name}" }.join("\n    ")
+    end
+
+    def preview_signature
+      return if attributes.blank?
+
+      signature = attributes.map { |attr| "#{attr.name}: #{attr.name.to_s.inspect}" }.join(", ")
+      "(#{signature})"
+    end
+
+    def preview_playground_yard_tags
+      return if attributes.blank?
+
+      # See https://lookbook.build/guide/previews/params#input-types
+      attributes.map { |attr| "# @param #{attr.name} text" }.join("\n  ")
+    end
+
+    def preview_playground_body
+      render_signature = attributes.map { |attr| "#{attr.name}: #{attr.name}" }.join(", ")
+      render_signature = "(#{render_signature})" if render_signature.present?
+
+      "render component(#{component_registry_id.inspect}).new#{render_signature}"
+    end
+
+    def preview_overview_body
+      component_registry_id = [class_path.presence, file_name].compact.join("/")
+
+      "render component(#{component_registry_id.inspect}).new#{preview_signature}"
+    end
+
+    def attributes_html
+      attributes.map { |attr| "<p> <%= @#{attr.name} %> </p>" }.join("\n  ")
+    end
+
+    def stimulus_html
+      %{\n  <label>Your name: <input data-action="input->#{stimulus_controller_name}#typed"/></label>} +
+        %{\n  <p>Hello <span data-#{stimulus_controller_name}-target="output"></span></p>}
+    end
+
+    def i18n_html
+      "<%= t '.hello' %>"
+    end
+
+    def initialize_html
+      [
+        "<p>Add #{class_name} HTML here</p>",
+        (attributes_html if attributes.present?),
+        (stimulus_html if options["js"]),
+        (i18n_html if options["i18n"]),
+      ].compact.join("\n  ")
+    end
+
+    def inline_html(indent: '')
+      @inline_html.gsub!(/^/, indent).strip
+    end
+  end
+end

data/lib/generators/solidus_admin/component/templates/component.html.erb.tt

@@ -0,0 +1,3 @@
+<div class="<%%= stimulus_id %>"<%= stimulus_attributes if options[:js] %>>
+  <%= initialize_html %>
+</div>

data/lib/generators/solidus_admin/component/templates/component.js.tt

@@ -0,0 +1,14 @@
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  static targets = ['output']
+
+  typed(event) {
+    this.text = event.currentTarget.value
+    this.render()
+  }
+
+  render() {
+    this.outputTarget.innerText = this.text
+  }
+}

data/lib/generators/solidus_admin/component/templates/component.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class <%= File.join(*[namespaced_path, file_path].compact).classify %>::Component < SolidusAdmin::BaseComponent
+<%- if initialize_signature -%>
+  def initialize(<%= initialize_signature %>)
+    <%= initialize_body %>
+  end
+<%- end -%>
+<% unless options['html'] %>
+  erb_template <<~ERB
+    <%= inline_html indent: '    ' %>
+  ERB
+<%- end -%>
+end

data/lib/generators/solidus_admin/component/templates/component.yml.tt

@@ -0,0 +1,4 @@
+# Add your component translations here.
+# Use the translation in the example in your template with `t(".hello")`.
+en:
+  hello: "Hello world!"

data/lib/generators/solidus_admin/component/templates/component_preview.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# @component <%= component_registry_id.inspect %>
+class <%= File.join(*[namespaced_path, file_path].compact).classify %>::ComponentPreview < ViewComponent::Preview
+  include SolidusAdmin::Preview
+
+  def overview
+    render_with_template
+  end
+
+  <%= preview_playground_yard_tags %>
+  def playground<%= preview_signature %>
+    <%= preview_playground_body %>
+  end
+end

data/lib/generators/solidus_admin/component/templates/component_preview_overview.html.erb

@@ -0,0 +1,7 @@
+<div class="mb-8">
+  <h6 class="text-gray-500 mb-3 mt-0">
+    Scenario 1
+  </h6>
+
+  <%%= render current_component.new<%= preview_signature %> %>
+</div>

data/lib/generators/solidus_admin/component/templates/component_spec.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe <%= File.join(*[namespaced_path, file_path].compact).classify %>::Component, type: :component do
+  it "renders the overview preview" do
+    render_preview(:overview)
+  end
+
+  # it "renders something useful" do
+  #   render_inline(described_class.new(<%= attributes.map { |attr| "#{attr.name}: #{attr.name.to_s.inspect}" }.join(", ") %>))
+  #
+  #   expect(page).to have_text "Hello, components!"
+  #   expect(page).to have_css '.value'
+  # end
+end

data/lib/generators/solidus_admin/install/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      class_option :lookbook, type: :boolean, default: !!ENV['SOLIDUS_ADMIN_LOOKBOOK'], desc: 'Install Lookbook for component previews'
+
+      source_root "#{__dir__}/templates"
+
+      def install_solidus_core_support
+        route <<~RUBY
+          mount SolidusAdmin::Engine, at: '/admin', constraints: ->(req) {
+            req.cookies['solidus_admin'] != 'false' &&
+            req.params['solidus_admin'] != 'false'
+          }
+        RUBY
+      end
+
+      def copy_initializer
+        copy_file "config/initializers/solidus_admin.rb"
+      end
+
+      def ignore_tailwind_build_files
+        append_file(".gitignore", "app/assets/builds/solidus_admin/") if File.exist?(Rails.root.join(".gitignore"))
+      end
+
+      def build_tailwind
+        rake "solidus_admin:tailwindcss:build"
+      end
+
+      def install_lookbook
+        return unless options[:lookbook]
+
+        gem_group :development, :test do
+          gem "lookbook"
+          gem "listen"
+          gem "actioncable"
+        end
+
+        route "mount Lookbook::Engine, at: '/lookbook' if Rails.env.development?"
+      end
+    end
+  end
+end