@spree/docs 0.1.177 → 0.1.178

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

@@ -1,256 +0,0 @@
----
-title: Admin Dashboard Custom CSS
-sidebarTitle: Custom CSS
-description: Customize the Spree Admin Dashboard with your own CSS by overriding Tailwind variables, adding custom styles, and extending admin views and helpers.
----
-
-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 Spree CLI (Docker)
-spree rake spree:admin:tailwindcss:watch
-```
-
-```bash Without Spree CLI
-bundle exec rake spree:admin:tailwindcss:watch
-```
-
-
-Or run the full development process, which includes the watcher when it's defined in `Procfile.dev`:
-
-
-```bash Spree CLI (Docker)
-spree dev
-```
-
-```bash Without Spree CLI
-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

@@ -1,116 +0,0 @@
----
-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/). 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.
-
-> **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 partial file `app/views/spree/admin/shared/_my_tracking_code.html.erb` (note the leading underscore — it's rendered as a partial), where you can add your tracking code, eg.
-
-    ```erb app/views/spree/admin/shared/_my_tracking_code.html.erb
-    <script>
-      console.log("I'm a spy!");
-    </script>
-    ```