@spree/docs 0.1.0

package/dist/developer/admin/admin.md

@@ -0,0 +1,205 @@
+---
+title: Admin Dashboard
+sidebarTitle: Overview
+description: Learn how to customize and extend the Spree Admin Dashboard
+---
+
+The Spree Admin Dashboard is a full-featured administration interface for managing your e-commerce store. It's built with Ruby on Rails and ships as the `spree_admin` gem.
+
+<img src="/images/spree_admin_dashboard.png" alt="Spree Admin Dashboard" />
+
+## What You Can Do
+
+The Admin Dashboard allows store administrators to manage:
+
+- **Products** - Create and manage products, variants, images, and inventory
+- **Orders** - Process orders, refunds, and shipments
+- **Customers** - View customer accounts and order history
+- **Promotions** - Create discounts, coupon codes, and special offers
+- **Content** - Manage pages, menus, and blog posts
+- **Settings** - Configure store settings, shipping, taxes, and payments
+
+## Customization Options
+
+As a developer, you can fully customize the Admin Dashboard:
+
+
+  - [Add New Sections](/developer/tutorial/admin) — Create entirely new admin pages for custom features like Brands, Vendors, or any custom model
+  - [Extend Existing UI](/developer/admin/extending-ui) — Inject custom fields, buttons, and sections into existing admin pages
+  - [Custom Navigation](/developer/admin/navigation) — Add menu items to the sidebar or create custom navigation structures
+  - [Custom Styling](/developer/admin/custom-css) — Add your own CSS to match your brand or modify the look and feel
+
+
+## Architecture Overview
+
+Spree Admin follows standard Rails conventions with some Spree-specific patterns:
+
+```
+app/
+├── controllers/
+│   └── spree/
+│       └── admin/
+│           └── products_controller.rb    # Your custom controllers
+├── views/
+│   └── spree/
+│       └── admin/
+│           └── products/
+│               ├── index.html.erb        # List view
+│               ├── _form.html.erb        # Shared form partial
+│               └── _table_row.html.erb   # Table row partial
+├── helpers/
+│   └── spree/
+│       └── admin/
+│           └── products_helper.rb        # View helpers
+└── assets/
+    └── tailwind/
+        └── spree_admin.css               # Custom Tailwind styles
+```
+
+## Key Concepts
+
+### Controllers
+
+Admin controllers inherit from `Spree::Admin::ResourceController` which provides:
+
+- Full CRUD operations (index, new, create, edit, update, destroy)
+- Automatic authorization checks
+- Flash messages and redirects
+- Search and filtering with Ransack
+
+```ruby
+# app/controllers/spree/admin/brands_controller.rb
+module Spree
+  module Admin
+    class BrandsController < ResourceController
+      # That's it! CRUD is handled automatically.
+      # Override methods only when needed.
+    end
+  end
+end
+```
+
+> **INFO:** Learn more about creating admin sections in the [Admin Dashboard Tutorial](/developer/tutorial/admin).
+
+### Views & Templates
+
+Views use standard Rails ERB templates with Spree's [Form Builder](/developer/admin/form-builder) and [Components](/developer/admin/components):
+
+```erb
+<%# app/views/spree/admin/brands/_form.html.erb %>
+<div class="card mb-6">
+  <div class="card-header">
+    <h5 class="card-title"><%= Spree.t(:general_settings) %></h5>
+  </div>
+  <div class="card-body">
+    <%= f.spree_text_field :name, required: true %>
+    <%= f.spree_text_area :description %>
+    <%= f.spree_file_field :logo, width: 300, height: 300 %>
+    <%= f.spree_check_box :active %>
+  </div>
+</div>
+```
+
+### JavaScript & Interactivity
+
+Spree Admin uses [Hotwire](https://hotwire.dev/) (Turbo + Stimulus) for interactivity:
+
+- **Turbo Drive** - Fast page navigation without full reloads
+- **Turbo Frames** - Update parts of the page independently
+- **Turbo Streams** - Real-time updates over WebSocket
+- **Stimulus** - Lightweight JavaScript controllers
+
+```erb
+<%# Using Stimulus controllers %>
+<div data-controller="dropdown">
+  <button data-action="dropdown#toggle">Menu</button>
+  <div data-dropdown-target="menu">...</div>
+</div>
+```
+
+> **INFO:** Add custom JavaScript using [Stimulus controllers](/developer/admin/custom-javascript).
+
+### Styling
+
+The Admin Dashboard uses [Tailwind CSS v4](https://tailwindcss.com/) for styling. You can:
+
+- Use Tailwind utility classes directly in your views
+- Override theme variables (colors, spacing, typography)
+- Add custom components using `@layer components`
+
+```erb
+<%# Using Tailwind utility classes in views %>
+<div class="bg-white rounded-lg shadow-sm border border-zinc-200 p-4">
+  <h3 class="text-lg font-bold text-zinc-900">My Custom Card</h3>
+  <p class="text-sm text-zinc-600 mt-2">Card content here</p>
+</div>
+```
+
+> **INFO:** Learn how to customize styles in [Custom CSS](/developer/admin/custom-css).
+
+## Quick Reference
+
+### Available Tools
+
+| Tool | Purpose | Documentation |
+|------|---------|---------------|
+| Form Builder | Create consistent forms with validation | [Form Builder](/developer/admin/form-builder) |
+| Components | Dropdowns, dialogs, icons, badges, etc. | [Components](/developer/admin/components) |
+| Helper Methods | Navigation, links, utilities | [Helper Methods](/developer/admin/helper-methods) |
+| UI Extensions | Inject content into existing pages | [Extending UI](/developer/admin/extending-ui) |
+
+### Common Tasks
+
+| Task | How To |
+|------|--------|
+| Add a new admin page | Use the scaffold generator: `bin/rails g spree:admin:scaffold Spree::Brand` |
+| Add sidebar navigation | Use `Spree.admin.navigation.sidebar.add` in an initializer |
+| Add form fields | Use `f.spree_text_field`, `f.spree_select`, etc. |
+| Show flash messages | They're automatic with `ResourceController` |
+| Check permissions | Use `can?(:update, @product)` in views |
+
+### Generator Commands
+
+```bash
+# Generate a complete admin section (controller, views, routes)
+bin/rails g spree:admin:scaffold Spree::Brand
+
+# Generate just a controller
+bin/rails g controller Spree::Admin::Brands --skip-routes
+```
+
+## Authentication & Authorization
+
+### Authentication
+
+Admin users must be authenticated to access the dashboard. Spree supports:
+
+- Built-in Devise authentication
+- Custom authentication adapters
+- SSO integration
+
+> **INFO:** See [Authentication](/developer/admin/authentication) for setup details.
+
+### Authorization
+
+Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization:
+
+```ruby
+# Check permissions in controllers
+authorize! :update, @product
+
+# Check permissions in views
+<% if can?(:destroy, @product) %>
+  <%= link_to_delete(@product) %>
+<% end %>
+```
+
+> **INFO:** See [Permissions](/developer/customization/permissions) for defining custom abilities.
+
+## Next Steps
+
+
+  - [Tutorial: Build Admin UI](/developer/tutorial/admin) — Step-by-step guide to creating a complete admin section
+  - [Form Builder](/developer/admin/form-builder) — Learn all available form field helpers
+  - [Components](/developer/admin/components) — Explore UI components like dropdowns, dialogs, and icons
+  - [Extending UI](/developer/admin/extending-ui) — Add custom content to existing admin pages

package/dist/developer/admin/authentication.md

@@ -0,0 +1,59 @@
+---
+title: Admin Panel Authentication
+sidebarTitle: Authentication
+description: How to customize the Spree admin panel authentication
+---
+
+Spree allows you to use a different model for the admin panel than the storefront (that's the default since Spree 5.2).
+Here you can find how to customize the admin panel authentication to use a different model.
+
+Let's assume you have an existing `AdminUser` model in your application and you're using Devise for authentication.
+
+In `config/initializers/spree.rb` file, add the following line:
+
+```ruby
+Spree.admin_user_class = 'AdminUser'
+```
+
+This will tell Spree to use your `AdminUser` model for the admin panel. You will also need to add the following line in that model file:
+
+```ruby
+include Spree::UserMethods
+```
+
+In your `config/initializers/routes.rb` file, you will need define devise routes for the 2nd model:
+
+```ruby
+Spree::Core::Engine.routes.prepend_routes do
+  # Admin authentication
+  devise_for(
+    Spree.admin_user_class.model_name.singular_route_key,
+    class_name: Spree.admin_user_class.to_s,
+    controllers: {
+      sessions: 'spree/admin/user_sessions',
+      passwords: 'spree/admin/user_passwords'
+    },
+    skip: :registrations,
+    path: :admin_user,
+    router_name: :spree
+  )
+end
+```
+
+And now in your `lib/spree/authentication_helpers.rb` file, please replace the following lines: 
+
+```diff
+     def spree_admin_login_path(opts = {})
+-      spree_login_path(opts)
++      new_admin_user_session_path(opts)
+     end
+
+     def spree_admin_logout_path(opts = {})
+-      spree_logout_path(opts)
++      destroy_admin_user_session_path(opts)
+     end
+```
+
+Now when attempting to access the admin panel, you will be redirected to the dedicated admin panel login page.
+
+![Admin panel login page](/images/developer/admin/admin_panel_login.png)