@spree/docs 0.1.0

package/dist/developer/admin/custom-css.md

@@ -0,0 +1,243 @@
+---
+title: Admin Dashboard Custom CSS
+sidebarTitle: Custom CSS
+---
+
+Spree Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. The stylesheet system is designed to be easily customizable while maintaining consistency with the Spree design system.
+
+## How It Works
+
+When you install Spree Admin, the installer creates a file at `app/assets/tailwind/spree_admin.css` in your application. This file:
+
+1. Imports the base Spree Admin styles from the gem
+2. Scans your custom admin views, helpers, and JavaScript for Tailwind classes
+3. Allows you to add custom styles and override theme variables
+
+## Using Tailwind Utility Classes
+
+You can use any Tailwind CSS utility class in your custom admin views, helpers, or JavaScript files. The build process automatically scans these locations:
+
+- `app/views/spree/admin/**/*.erb`
+- `app/helpers/spree/admin/**/*.rb`
+- `app/javascript/spree/admin/**/*.js`
+
+Example usage in a view:
+
+```erb
+<div class="bg-zinc-100 p-4 rounded-lg shadow-sm">
+  <h2 class="text-lg font-bold text-zinc-900">Custom Section</h2>
+  <p class="text-sm text-zinc-600 mt-2">Your content here</p>
+</div>
+```
+
+## Customizing the Theme
+
+### Overriding Theme Colors
+
+To override Tailwind theme values, add a `@theme` block in your `app/assets/tailwind/spree_admin.css` file after the import:
+
+```css app/assets/tailwind/spree_admin.css
+/* Import Spree Admin base styles from the gem */
+@import "$SPREE_ADMIN_PATH/app/assets/tailwind/spree/admin/index.css";
+
+/* Override theme colors */
+@theme {
+  --color-primary: #4F46E5;      /* Change primary color to indigo */
+  --color-success: #059669;      /* Custom success color */
+  --color-danger: #DC2626;       /* Custom danger color */
+}
+```
+
+### Available Theme Variables
+
+The Spree Admin theme defines these customizable variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--color-primary` | `var(--color-zinc-950)` | Primary brand color |
+| `--color-success` | `var(--color-green-900)` | Success state color |
+| `--color-danger` | `var(--color-red-600)` | Error/danger state color |
+| `--color-warning` | `var(--color-yellow-900)` | Warning state color |
+| `--color-info` | `var(--color-blue-900)` | Info state color |
+
+### Overriding Layout Variables
+
+You can also customize layout-related CSS variables:
+
+```css app/assets/tailwind/spree_admin.css
+:root {
+  --spacing-sidebar-width: 280px;      /* Default: 220px */
+  --spacing-sidebar-collapsed: 70px;   /* Default: 59px */
+  --spacing-header-height: 64px;       /* Default: 58px */
+}
+```
+
+## Adding Custom Components
+
+Use Tailwind's `@layer` directive to add custom component styles that work seamlessly with the existing design:
+
+```css app/assets/tailwind/spree_admin.css
+@layer components {
+  /* Custom card style */
+  .my-custom-card {
+    @apply bg-white rounded-lg shadow-sm border border-zinc-200 p-4;
+  }
+
+  /* Custom button variant */
+  .btn-custom {
+    @apply inline-flex items-center px-4 py-2 rounded-md;
+    @apply bg-indigo-600 text-white font-medium;
+    @apply hover:bg-indigo-700 transition-colors;
+  }
+
+  /* Custom status badge */
+  .status-badge {
+    @apply inline-flex items-center px-2 py-1 rounded-full text-xs font-medium;
+  }
+
+  .status-badge-active {
+    @apply status-badge bg-green-100 text-green-800;
+  }
+
+  .status-badge-inactive {
+    @apply status-badge bg-zinc-100 text-zinc-600;
+  }
+}
+```
+
+## Adding Custom Utilities
+
+For reusable utility classes, use the utilities layer:
+
+```css app/assets/tailwind/spree_admin.css
+@layer utilities {
+  .text-gradient {
+    @apply bg-clip-text text-transparent bg-gradient-to-r from-indigo-500 to-purple-500;
+  }
+
+  .scrollbar-hidden {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+
+  .scrollbar-hidden::-webkit-scrollbar {
+    display: none;
+  }
+}
+```
+
+## Scanning Additional Paths
+
+If you have admin-related code in non-standard locations, add additional `@source` directives:
+
+```css app/assets/tailwind/spree_admin.css
+/* Scan host app's custom admin code for Tailwind classes */
+@source "../../views/spree/admin/**/*.erb";
+@source "../../helpers/spree/admin/**/*.rb";
+@source "../../javascript/spree/admin/**/*.js";
+
+/* Add your custom paths */
+@source "../../components/admin/**/*.erb";
+@source "../../views/admin/**/*.erb";
+```
+
+## Development Workflow
+
+### Starting the CSS Watcher
+
+During development, run the Tailwind CSS watcher to automatically rebuild styles when you make changes:
+
+```bash
+bin/rails spree:admin:tailwindcss:watch
+```
+
+Or if you're using `Procfile.dev` with foreman:
+
+```bash
+bin/dev
+```
+
+The watcher monitors:
+- Your host app's CSS files in `app/assets/tailwind/`
+- The Spree Admin engine's CSS files
+- All files matching your `@source` patterns
+
+### Building for Production
+
+CSS is automatically compiled during asset precompilation:
+
+```bash
+bin/rails assets:precompile
+```
+
+## Common Customization Examples
+
+### Custom Primary Color Scheme
+
+```css app/assets/tailwind/spree_admin.css
+@theme {
+  /* Use blue as the primary color */
+  --color-primary: #2563EB;
+}
+
+@layer components {
+  /* Ensure buttons use the new primary color */
+  .btn-primary {
+    @apply bg-blue-600 hover:bg-blue-700;
+  }
+}
+```
+
+### Dark Mode Adjustments
+
+```css app/assets/tailwind/spree_admin.css
+@layer base {
+  /* Custom dark mode overrides */
+  .dark {
+    --color-primary: #60A5FA;
+  }
+}
+```
+
+### Custom Form Styling
+
+```css app/assets/tailwind/spree_admin.css
+@layer components {
+  /* Custom input style */
+  .input-custom {
+    @apply block w-full rounded-md border-zinc-300 shadow-sm;
+    @apply focus:border-indigo-500 focus:ring-indigo-500;
+  }
+
+  /* Custom select style */
+  .select-custom {
+    @apply block w-full rounded-md border-zinc-300 py-2 pl-3 pr-10;
+    @apply focus:border-indigo-500 focus:outline-none focus:ring-indigo-500;
+  }
+}
+```
+
+## Troubleshooting
+
+### Changes Not Appearing
+
+1. Ensure the watcher is running: `bin/rails spree:admin:tailwindcss:watch`
+2. Check that your files are in paths covered by `@source` directives
+3. Hard refresh the browser (Cmd+Shift+R or Ctrl+Shift+R)
+
+### Missing Utility Classes
+
+If a Tailwind class isn't working, ensure:
+1. The class is used in a file that's scanned by `@source`
+2. The class name is complete (not dynamically constructed)
+3. Run a fresh build: `bin/rails spree:admin:tailwindcss:build`
+
+### Listen Gem Required
+
+The watch task requires the `listen` gem. Add it to your Gemfile:
+
+```ruby Gemfile
+group :development do
+  gem 'listen', '>= 3.0'
+end
+```

package/dist/developer/admin/custom-javascript.md

@@ -0,0 +1,116 @@
+---
+title: Custom JavaScript for Admin Dashboard
+sidebarTitle: Custom JavaScript
+description: Learn how to add custom JavaScript to your Spree Admin Dashboard
+---
+
+## Extending Admin Dashboard with JavaScript
+
+Spree Admin Dashboard can be easily extended with custom JavaScript. Most of the JavaScript in the Admin Dashboard is powered by a framework called [Stimulus.js](https://stimulus.hotwired.dev/) which is the Ruby on Rails default. It's a very simple and minimalistic framework only enhancing our server-side rendered HTML with a bit of interactivity.
+
+### 3rd party JavaScript libraries
+
+Spree Admin Dashboard comes with a few 3rd party JavaScript libraries already included.
+
+Main libraries we're using:
+
+* [Stimulus.js](https://stimulus.hotwired.dev/)
+* [Turbo](https://turbo.hotwired.dev/)
+* [EasyPick](https://easepick.com/) (date picker)
+* [TomSelect](https://tom-select.js.org/) (autocomplete/dropdowns)
+* [Sortable.js](https://github.com/SortableJS/Sortable) - sortable drag and drop lists
+* [Uppy](https://uppy.io/) - file uploader
+
+You can find them in the [app/assets/javascripts/vendor](https://github.com/spree/spree/blob/main/admin/vendor/javascript) directory.
+
+### Managing JavaScript dependencies
+
+You're probably wondering why these libraries are in the `vendor` directory, and not in `node_modules`.
+
+That's because we're not using Node.js at all. So no Yarn or npm. We're using a different approach to manage dependencies.
+
+We're using a tool called [Importmaps](https://github.com/rails/importmap-rails) to manage dependencies which is the Ruby on Rails default.
+
+> **INFO:** If you want to use a different JavaScript package manager you can do so by using [jsbundling-rails](https://github.com/rails/jsbundling-rails) gem.
+
+#### Install dependencies
+
+To install dependencies you need to run the following command:
+
+```bash
+bin/importmap pin react
+```
+
+This will install the dependencies, download the files to your `vendor/javascript` directory and add them to your `config/importmap.rb` file, eg.
+
+```ruby
+pin "react" # @19.1.0
+```
+
+Now you can just import the library in your application entry point, eg. `application.js`:
+
+```js
+import "react";
+```
+
+### Application entry point
+
+Mentioned above, the application entry point is the `application.js` file. It's located in the `app/javascript` directory.
+
+If you want to add custom JavaScript to your Spree Admin Dashboard, you can do so by adding a new file to the `app/javascript` directory.
+
+### Stimulus Controllers
+
+Stimulus controllers are a way to add interactivity to your Spree Admin Dashboard. Admin Dashboard controllers can be found in the Spree repository in the [Admin Dashboard/app/javascript/spree/admin/controllers](https://github.com/spree/spree/tree/main/admin/app/javascript/spree/admin/controllers) directory.
+
+You can find more information about Stimulus controllers in the [Stimulus.js documentation](https://stimulus.hotwired.dev/handbook/controllers).
+
+To add a new controller you need to create a new file in the `app/javascript/controllers` directory. It will be automatically picked up by the application.
+
+```js
+// app/javascript/controllers/hello_controller.js
+import { Controller } from '@hotwired/stimulus'
+
+export default class extends Controller {
+  connect() {
+    console.log("Hello Spree Commerce Stimulus!", this.element);
+  }
+}
+```
+
+To use the controller in your HTML you need to add the `data-controller` attribute to your element, eg.
+
+```html
+<div data-controller="hello">
+  Hello Spree Commerce Stimulus!
+</div>
+```
+
+## JavaScript snippets
+
+If you need to add a small piece of JavaScript code (eg. tracking, marketing, analytics, customer service etc.) you can do this by:
+
+1. Declaring a new head partial in the `config/initializers/spree.rb` file, eg.
+
+    **Spree 5.2+:**
+
+```ruby config/initializers/spree.rb
+        Rails.application.config.after_initialize do
+          Spree.admin.partials.head << 'spree/admin/shared/my_tracking_code'
+        end
+        ```
+
+      **Spree 5.1 and below:**
+
+```ruby config/initializers/spree.rb
+        Rails.application.config.spree_admin.head_partials << 'spree/admin/shared/my_tracking_code'
+        ```
+
+
+2. Creating a new file in the `app/views/spree/admin/shared/my_tracking_code.html.erb`, where you can add your tracking code, eg.
+
+    ```erb
+    <script>
+      console.log("I'm a spy!");
+    </script>
+    ```