Merge pull request #5554 from solidusio/elia/admin/tailwind

[admin] Provide a pre-built CSS file and a script to customize TW for local modifications
solidusio · Dec 19, 2023 · b3878ef · b3878ef
2 parents 7afb2cd + 7dc3b14
commit b3878ef
Show file tree

Hide file tree

Showing 27 changed files with 243 additions and 285 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -1,10 +1,12 @@
 {
   "extends": "eslint:recommended",
   "ignorePatterns": [
+    "*tailwind.config.js",
     "**/spec",
     "**/vendor",
     "**/node_modules",
     "sandbox",
+    "coverage",
     "core/doc",
     "tmp"
   ],

diff --git a/.gitignore b/.gitignore
@@ -31,3 +31,4 @@ node_modules
 yarn.lock
 package-lock.json
 .env
+/admin/app/assets/builds
diff --git a/.rubocop.yml b/.rubocop.yml
@@ -345,3 +345,8 @@ Lint/MissingSuper:
 Rails/FindEach:
   Exclude:
     - 'db/migrate/**/*'
+
+# Since we're writing library code we can't assume that
+# tasks should load the rails environment loaded.
+Rails/RakeEnvironment:
+  Enabled: false
diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml
@@ -459,16 +459,6 @@ Rails/Present:
     - "core/lib/spree/core/search/base.rb"
     - "core/spec/models/spree/stock/availability_validator_spec.rb"
 
-# Offense count: 8
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: Include.
-# Include: **/Rakefile, **/*.rake
-Rails/RakeEnvironment:
-  Exclude:
-    - "Rakefile"
-    - "backend/Rakefile"
-    - "core/Rakefile"
-
 # Offense count: 8
 # This cop supports safe autocorrection (--autocorrect).
 Rails/RedundantForeignKey:

diff --git a/Gemfile b/Gemfile
@@ -54,6 +54,7 @@ end
 
 group :admin do
   gem 'solidus_admin', path: 'admin', require: false
+  gem 'tailwindcss-rails', '~> 2.0', require: false
   gem 'axe-core-rspec', '~> 4.7', require: false
   gem 'axe-core-capybara', '~> 4.7', require: false
 end

diff --git a/Procfile.dev b/Procfile.dev
@@ -1,2 +1,2 @@
 web: env RUBY_DEBUG_OPEN=true bin/rails server
-admin_tailwind: bin/rails solidus_admin:tailwindcss:watch
+admin_tailwind: bundle exec rake -C admin tailwindcss:watch
diff --git a/admin/Rakefile b/admin/Rakefile
@@ -7,6 +7,32 @@ require 'rspec/core/rake_task'
 require 'spree/testing_support/dummy_app/rake_tasks'
 require 'bundler/gem_tasks'
 
+namespace :tailwindcss do
+  tailwindcss_command = [
+    "tailwindcss",
+    "--content",
+    "#{__dir__}/{app/helpers,app/views,app/components,app/assets/javascripts,spec/components/previews}/**/*",
+    "--config",
+    "#{__dir__}/config/tailwind.config.js",
+    "--input",
+    "#{__dir__}/app/assets/stylesheets/solidus_admin/application.tailwind.css",
+    "--output",
+    "#{__dir__}/app/assets/builds/solidus_admin/tailwind.css",
+  ]
+
+  desc 'Build Tailwind CSS'
+  task :build do
+    sh tailwindcss_command.shelljoin
+  end
+
+  desc 'Watch Tailwind CSS'
+  task :watch do
+    sh (tailwindcss_command + ['--watch']).shelljoin
+  end
+end
+
+task build: 'tailwindcss:build'
+
 RSpec::Core::RakeTask.new
 task default: :spec
 

diff --git a/admin/app/assets/builds/.keep b/admin/app/assets/builds/.keep
diff --git a/admin/app/assets/config/solidus_admin_manifest.js b/admin/app/assets/config/solidus_admin_manifest.js
@@ -1,4 +1,5 @@
 //= link_tree ../images
+//= link_tree ../builds
 //= link_tree ../stylesheets .css
 //= link_tree ../../javascript .js
 //= link_tree ../../components .js
diff --git a/admin/app/assets/stylesheets/solidus_admin/application.tailwind.css b/admin/app/assets/stylesheets/solidus_admin/application.tailwind.css
@@ -0,0 +1,4 @@
+@import url("https://rsms.me/inter/inter.css");
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
diff --git a/admin/app/assets/stylesheets/solidus_admin/application.tailwind.css.erb b/admin/app/assets/stylesheets/solidus_admin/application.tailwind.css.erb
diff --git a/admin/app/views/layouts/solidus_admin/application.html.erb b/admin/app/views/layouts/solidus_admin/application.html.erb
@@ -8,7 +8,6 @@
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
 
-    <%= stylesheet_link_tag "inter-font", "data-turbo-track": "reload" %>
     <%= stylesheet_link_tag SolidusAdmin::Config.theme_path(session[:admin_light_theme]), media: '(prefers-color-scheme: light)', "data-turbo-track": "reload" %>
     <%= stylesheet_link_tag SolidusAdmin::Config.theme_path(session[:admin_dark_theme]), media: '(prefers-color-scheme: dark)', "data-turbo-track": "reload" %>
     <%= javascript_importmap_tags "solidus_admin/application", shim: false, importmap: SolidusAdmin.importmap %>

diff --git a/admin/app/views/layouts/solidus_admin/preview.html.erb b/admin/app/views/layouts/solidus_admin/preview.html.erb
@@ -1,7 +1,6 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <%= stylesheet_link_tag "solidus_admin/application.css", "inter-font", "data-turbo-track": "reload" %>
     <%= javascript_importmap_tags "solidus_admin/application", shim: false, importmap: SolidusAdmin.importmap %>
   </head>
   <body class="p-3">

diff --git a/...nfig/solidus_admin/tailwind.config.js.erb → admin/config/tailwind.config.js b/...nfig/solidus_admin/tailwind.config.js.erb → admin/config/tailwind.config.js
@@ -1,27 +1,28 @@
 const defaultTheme = require('tailwindcss/defaultTheme')
 const plugin = require('tailwindcss/plugin')
+const adminRoot = __dirname.replace(/\/config$/, '')
 
 module.exports = {
   content: [
-    <%= SolidusAdmin::Config.tailwind_content.map { "'#{_1}'" }.join(",\n    ") %>
+    `${adminRoot}/{app/helpers,app/views,app/components,app/assets/javascripts,spec/components/previews}/**/*`,
   ],
   theme: {
     extend: {
       aria: {
-        'current': 'current="true"',
+        current: 'current="true"',
       },
       fontFamily: {
-        sans: ['Inter var', ...defaultTheme.fontFamily.sans],
+        sans: ["Inter var", ...defaultTheme.fontFamily.sans],
       },
       colors: {
         transparent: "transparent",
         current: "currentColor",
 
         // Primary palette
-        'solidus-red': "#ef3023",
+        "solidus-red": "#ef3023",
         black: "#222222",
         graphite: "#c7ccc7",
-        'graphite-light': "#d8dad8",
+        "graphite-light": "#d8dad8",
         sand: "#f5f3f0",
         white: "#ffffff",
 
@@ -37,10 +38,10 @@ module.exports = {
         sky: "#cbdff1",
         seafoam: "#c1e0de",
         dune: "#e6bf9b",
-        'full-black': "#000000",
+        "full-black": "#000000",
 
         // Extra colors (not part of the original palette)
-        'papaya-whip': "#f9e3d9",
+        "papaya-whip": "#f9e3d9",
 
         // UI Red
         red: {
@@ -71,45 +72,45 @@ module.exports = {
         },
       },
       borderRadius: {
-        sm: '4px',
+        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')",
+        "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)'
+        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'),
+    require("@tailwindcss/forms")({ strategy: "class" }),
+    require("@tailwindcss/aspect-ratio"),
+    require("@tailwindcss/typography"),
+    require("@tailwindcss/container-queries"),
     plugin(({ addVariant, addBase, addComponents, theme }) => {
       // Support the "hidden" attribute
-      addVariant('hidden', '&([hidden])')
-      addVariant('visible', '&:not([hidden])')
+      addVariant("hidden", "&([hidden])")
+      addVariant("visible", "&:not([hidden])")
 
       // Support the "search-cancel" pseudo-element
-      addVariant('search-cancel', '&::-webkit-search-cancel-button')
+      addVariant("search-cancel", "&::-webkit-search-cancel-button")
 
       // Reset the <summary> marker
       addBase({
-        'summary::-webkit-details-marker': { display: 'none' },
-        'summary::marker': { display: 'none' },
-        'summary': { listStyle: 'none' },
+        "summary::-webkit-details-marker": { display: "none" },
+        "summary::marker": { display: "none" },
+        summary: { listStyle: "none" },
       })
 
       // Add a text style for links
       addComponents({
-        '.body-link': {
-          color: theme('colors.blue'),
-          '&:hover': {
-            textDecoration: 'underline',
+        ".body-link": {
+          color: theme("colors.blue"),
+          "&:hover": {
+            textDecoration: "underline",
           },
         },
       })

diff --git a/admin/docs/customizing_tailwind.md b/admin/docs/customizing_tailwind.md
diff --git a/admin/docs/customizing_tailwindcss.md b/admin/docs/customizing_tailwindcss.md
@@ -0,0 +1,57 @@
+# Customizing TailwindCSS
+
+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 provides a precompiled CSS file that includes all the necessary
+Tailwind classes for the admin to work out of the box.
+
+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.
+
+## Setting up a local TailwindCSS build for Solidus Admin
+
+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:
+
+Add Tailwind configuration files to your application:
+
+```shell
+bin/rails solidus_admin:tailwindcss:install
+```
+
+This will create all the necessary files for you to customize TailwindCSS,
+including:
+- A `config/solidus_admin/tailwind.config.js` configuration file
+  that will automatically import the Solidus Admin's default configuration.
+- An `app/assets/stylesheets/solidus_admin/application.tailwind.css` file
+  in which you can add your own customizations.
+- Tasks to build the CSS file once or watch for changes and automatically
+  rebuild the target `app/assets/builds/solidus_admin/application.css` file.
+
+In order to manually build the CSS file, run:
+
+```shell
+bin/rails solidus_admin:tailwindcss:build
+```
+
+Or, to watch for changes and automatically rebuild the CSS file, run:
+
+```shell
+bin/rails solidus_admin:tailwindcss:watch
+```
+
+## Caveats
+
+### 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.*
diff --git a/admin/lib/generators/solidus_admin/install/install_generator.rb b/admin/lib/generators/solidus_admin/install/install_generator.rb
@@ -4,6 +4,7 @@ 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'
+      class_option :tailwind, type: :boolean, default: false, desc: 'Install TailwindCSS for custom components'
 
       source_root "#{__dir__}/templates"
 
@@ -25,7 +26,7 @@ def ignore_tailwind_build_files
       end
 
       def build_tailwind
-        rake "solidus_admin:tailwindcss:build"
+        rake "solidus_admin:tailwindcss:install" if options[:tailwind]
       end
 
       def install_lookbook