@spree/docs 0.1.0

package/dist/developer/storefront/themes.md

@@ -0,0 +1,161 @@
+---
+title: "Storefront Themes"
+sidebarTitle: "Themes"
+description: "Learn how to develop themes for your Spree storefront"
+---
+
+Themes are the main building blocks of the storefront. They hold styles, settings, and templates for the storefront.
+
+## Default Theme
+
+Spree comes with a default theme called `default`. It is used as a base for all the themes and contains the core styles and scripts. This theme is included with the Spree Commerce core and is always available.
+
+## Creating a New Theme
+
+You can create your custom themes by following the steps below.
+
+```bash
+bin/rails g spree:storefront:theme MyTheme
+```
+
+This command will create a new theme called `my_theme` in the `app/views/themes` directory and copy the default theme files to the new theme.
+
+It will also add a line in your `config/initializers/spree.rb` file to load the new theme.
+
+```ruby config/initializers/spree.rb
+Spree.page_builder.themes << Spree::Themes::MyTheme
+```
+
+Now you can go to **Admin Dashboard -> Storefront -> Themes**, you should see a new section **Add new theme** with your theme name. Click **Add** button to activate the theme.
+
+### Theme Templates
+
+Theme has the following template structure:
+
+```
+├── account
+│   ├── store_credits
+│   ├── profile
+│   ├── orders
+│   ├── newsletter
+│   └── addresses
+├── checkout
+├── contacts
+├── orders
+├── page_sections
+├── policies
+├── posts
+├── products
+├── search
+├── settings
+├── shared
+└── wishlists
+```
+
+Each directory contains standard [Ruby on Rails ERB templates](https://guides.rubyonrails.org/action_view_overview.html) for the corresponding page.
+
+The `page_sections` directory contains sections that are used globally across the storefront.
+
+The `shared` directory contains shared components that are used across the storefront.
+
+### Theme Settings
+
+The theme settings are stored in the `app/models/spree/themes/my_theme.rb` file.
+
+```ruby
+module Spree
+  module Themes
+    class MyTheme < Spree::Theme
+      def self.metadata
+        {
+          authors: ['Spree Commerce'], # replace with your name
+          license: 'MIT' # replace with your license
+        }
+      end
+
+      # COLORS
+      # main colors
+      preference :primary_color, :string, default: '#000000'
+      preference :accent_color, :string, default: '#F0EFE9'
+      preference :danger_color, :string, default: '#C73528'
+      preference :neutral_color, :string, default: '#999999'
+      preference :background_color, :string, default: '#FFFFFF'
+      preference :text_color, :string, default: '#000000'
+      preference :success_color, :string, default: '#00C773'
+
+      # buttons
+      preference :button_background_color, :string
+      preference :button_text_color, :string, default: '#ffffff'
+      preference :button_hover_background_color, :string
+      preference :button_hover_text_color, :string
+      preference :button_border_color, :string
+
+      # borders
+      preference :border_color, :string, default: '#E9E7DC'
+      preference :sidebar_border_color, :string
+
+      preference :secondary_button_background_color, :string
+      preference :secondary_button_text_color, :string
+      preference :secondary_button_hover_background_color, :string
+      preference :secondary_button_hover_text_color, :string
+
+      # inputs
+      preference :input_text_color, :string, default: '#6b7280'
+      preference :input_background_color, :string, default: '#ffffff'
+      preference :input_border_color, :string
+      preference :input_focus_border_color, :string
+      preference :input_focus_background_color, :string
+      preference :input_focus_text_color, :string
+
+      # sidebar (checkout)
+      preference :checkout_sidebar_background_color, :string, default: '#f3f4f6'
+      preference :checkout_divider_background_color, :string
+      preference :checkout_sidebar_text_color, :string
+
+      # TYPOGRAPHY
+      preference :custom_font_code, :string, default: nil
+      # body
+      preference :font_family, :string, default: 'Inter'
+      preference :font_size_scale, :integer, default: 100
+      # headers
+      preference :header_font_family, :string, default: 'Inter'
+      preference :header_font_size_scale, :integer, default: 100
+      preference :headings_uppercase, :boolean, default: true
+
+      # BUTTONS
+      preference :button_border_thickness, :integer, default: 1
+      preference :button_border_opacity, :integer, default: 100
+      preference :button_border_radius, :integer, default: 100
+      preference :button_shadow_opacity, :integer, default: 0
+      preference :button_shadow_horizontal_offset, :integer, default: 0
+      preference :button_shadow_vertical_offset, :integer, default: 4
+      preference :button_shadow_blur, :integer, default: 5
+
+      # INPUTS
+      preference :input_border_thickness, :integer, default: 1
+      preference :input_border_opacity, :integer, default: 100
+      preference :input_border_radius, :integer, default: 8
+      preference :input_shadow_opacity, :integer, default: 0
+      preference :input_shadow_horizontal_offset, :integer, default: 0
+      preference :input_shadow_vertical_offset, :integer, default: 4
+      preference :input_shadow_blur, :integer, default: 5
+
+      # BORDERS
+      preference :border_width, :integer, default: 1
+      preference :border_radius, :integer, default: 6
+      preference :border_shadow_opacity, :integer, default: 0
+      preference :border_shadow_horizontal_offset, :integer, default: 0
+      preference :border_shadow_vertical_offset, :integer, default: 4
+      preference :border_shadow_blur, :integer, default: 5
+
+      # PRODUCT IMAGES
+      preference :product_listing_image_height, :integer, default: 300
+      preference :product_listing_image_width, :integer, default: 300
+      preference :product_listing_image_height_mobile, :integer, default: 190
+      preference :product_listing_image_width_mobile, :integer, default: 190
+    end
+  end
+end
+```
+
+These are standard [Spree preferences](/developer/customization/model-preferences) that are configurable via Page Builder.

package/dist/developer/tutorial/admin.md

@@ -0,0 +1,134 @@
+---
+title: Admin Dashboard
+description: Learn how to create Admin Dashboard UI to manage Brands
+---
+
+Now that we've created a complete "Brand" model, let's create an Admin Dashboard interface so our admins can manage the brands.
+
+## Step 1: Create the boilerplate Admin Dashboard UI
+
+Admin Scaffold generator is a tool that helps us create a complete Admin Dashboard UI for our new resource.
+
+Run the following command in our Spree application root directory:
+
+```bash
+bin/rails g spree:admin:scaffold Spree::Brand
+```
+
+This will create the following files:
+
+| File Type | Path | Description |
+|-----------|------|-------------|
+| Controller | `app/controllers/spree/admin/brands_controller.rb` | Handles the logic for the brands resource. |
+| View | `app/views/spree/admin/brands/index.html.erb` | Displays the list of brands using the new tables system. |
+| View | `app/views/spree/admin/brands/new.html.erb` | Displays the new brand form. |
+| View | `app/views/spree/admin/brands/edit.html.erb` | Displays the edit brand form. |
+| Partial | `app/views/spree/admin/brands/_form.html.erb` | The form partial used in new and edit views. |
+| Initializer | `config/initializers/spree_admin_brands_table.rb` | Registers the table with columns for the index view. |
+| Initializer | `config/initializers/spree_admin_brands_navigation.rb` | Adds navigation to the admin sidebar. |
+
+It will also automatically add the following routes to your `config/routes.rb` file:
+
+```ruby config/routes.rb
+namespace :admin do
+  resources :brands
+end
+```
+
+You will now be able to access the brands resource at `http://localhost:3000/admin/brands` in your browser. To reference this route in your code, you can use the `spree.admin_brands_path` helper.
+
+## Step 2: Customize the Table Columns
+
+The scaffold generator creates a table initializer at `config/initializers/spree_admin_brands_table.rb` with default columns:
+
+```ruby config/initializers/spree_admin_brands_table.rb
+Rails.application.config.after_initialize do
+  Spree.admin.tables.register(:brands, model_class: Spree::Brand, search_param: :name_cont)
+
+  Spree.admin.tables.brands.add :name,
+    label: :name,
+    type: :link,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 10
+
+  Spree.admin.tables.brands.add :created_at,
+    label: :created_at,
+    type: :datetime,
+    sortable: true,
+    filterable: true,
+    default: true,
+    position: 20
+
+  Spree.admin.tables.brands.add :updated_at,
+    label: :updated_at,
+    type: :datetime,
+    sortable: true,
+    filterable: true,
+    default: false,
+    position: 30
+end
+```
+
+You can customize this file to add more columns based on your model's attributes. For example, to add a description column:
+
+```ruby
+Spree.admin.tables.brands.add :description,
+  label: :description,
+  type: :string,
+  sortable: false,
+  filterable: true,
+  default: true,
+  position: 15
+```
+
+> **INFO:** For complete table customization options including column types, filtering, sorting, and bulk actions, see the [Admin Tables](/developer/admin/tables) guide.
+
+## Step 3: Customize Navigation
+
+The scaffold generator also creates a navigation initializer at `config/initializers/spree_admin_brands_navigation.rb`:
+
+```ruby config/initializers/spree_admin_brands_navigation.rb
+Rails.application.config.after_initialize do
+  Spree.admin.navigation.sidebar.add :brands,
+    label: :brands,
+    url: :admin_brands_path,
+    icon: 'list',
+    position: 55,
+    active: -> { controller_name == 'brands' },
+    if: -> { can?(:manage, Spree::Brand) }
+end
+```
+
+You can customize the icon and position to fit your needs. For example, to use the "award" icon and place it between Products (30) and Customers (40):
+
+```ruby
+Spree.admin.navigation.sidebar.add :brands,
+  label: :brands,
+  url: :admin_brands_path,
+  icon: 'award',
+  position: 35,
+  active: -> { controller_name == 'brands' },
+  if: -> { can?(:manage, Spree::Brand) }
+```
+
+### Adding to an Existing Submenu
+
+To add "Brands" to the Products submenu instead, use the `parent` option:
+
+```ruby config/initializers/spree_admin_brands_navigation.rb
+Rails.application.config.after_initialize do
+  Spree.admin.navigation.sidebar.add :brands,
+    label: :brands,
+    url: :admin_brands_path,
+    position: 50,
+    parent: :products,
+    active: -> { controller_name == 'brands' },
+    if: -> { can?(:manage, Spree::Brand) }
+end
+```
+
+After restarting your server, you'll see the new "Brands" navigation link in the admin sidebar!
+
+> **INFO:** For complete navigation API documentation including all available options, submenu creation, badges, and more, see the [Admin Navigation](/developer/admin/navigation) guide.

package/dist/developer/tutorial/extending-models.md

@@ -0,0 +1,380 @@
+---
+title: Extending Core Models
+description: Learn how to extend Spree's core models to connect Brands with Products
+---
+
+In this tutorial, we'll connect our custom Brand model with Spree's core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.
+
+> **INFO:** This guide assumes you've completed the [Model](/developer/tutorial/model), [Admin](/developer/tutorial/admin), and [File Uploads](/developer/tutorial/file-uploads) tutorials.
+
+## What We're Building
+
+By the end of this tutorial, you'll have:
+
+- Products associated with Brands
+- A brand selector in the Product admin form
+- Understanding of how to safely extend Spree core models
+
+## Choosing the Right Approach
+
+Before extending Spree models, consider which approach fits your needs best:
+
+| What you need | Recommended approach |
+|---------------|---------------------|
+| Add association (belongs_to, has_many) | **Decorator** (this tutorial) |
+| Add validation or scope | **Decorator** |
+| Add new instance/class method | **Decorator** |
+| React to model changes (after save, etc.) | [Events subscriber](/developer/core-concepts/events) |
+| Sync with external service on changes | [Events](/developer/core-concepts/events) or [Webhooks](/developer/core-concepts/webhooks) |
+| Add searchable/filterable field | [Ransack configuration](/developer/core-concepts/search-filtering#extending-ransackable-configuration) |
+| Add admin UI elements | [Admin Partials](/developer/admin/extending-ui) |
+
+> **INFO:** This tutorial uses **decorators** because we're adding a structural association between models. For behavioral changes like callbacks, prefer [Events](/developer/core-concepts/events) instead - they're easier to test and maintain.
+
+## Understanding Decorators
+
+When working with Spree, you'll often need to add functionality to existing models like `Spree::Product` or `Spree::Order`. However, you shouldn't modify these files directly because:
+
+1. **Upgrades** - Your changes would be lost when updating Spree
+2. **Maintainability** - It's hard to track what you've customized
+3. **Conflicts** - Direct modifications can conflict with Spree's code
+
+Instead, we use **decorators** - a Ruby pattern that lets you add or modify behavior of existing classes without changing their original source code.
+
+### How Decorators Work
+
+In Ruby, classes are "open" - you can add methods to them at any time. Decorators leverage this by:
+
+1. Creating a module with your new methods
+2. Using `Module#prepend` to inject your module into the class's inheritance chain
+3. Your methods run first, and can call `super` to invoke the original method
+
+```ruby
+# This is the basic pattern
+module Spree
+  module ProductDecorator
+    # Add a new method
+    def my_new_method
+      "Hello from decorator!"
+    end
+
+    # Override an existing method
+    def existing_method
+      # Do something before
+      result = super  # Call the original method
+      # Do something after
+      result
+    end
+  end
+
+  Product.prepend(ProductDecorator)
+end
+```
+
+The key line is `Product.prepend(ProductDecorator)` - this inserts your module at the beginning of the method lookup chain, so your methods are found first.
+
+## Step 1: Create the Migration
+
+First, add a `brand_id` column to the products table:
+
+```bash
+bin/rails g migration AddBrandIdToSpreeProducts brand_id:integer:index
+```
+
+Edit the migration to add an index (but no foreign key constraint, keeping it optional):
+
+```ruby db/migrate/XXXXXXXXXXXXXX_add_brand_id_to_spree_products.rb
+class AddBrandIdToSpreeProducts < ActiveRecord::Migration[8.0]
+  def change
+    add_column :spree_products, :brand_id, :integer
+    add_index :spree_products, :brand_id
+  end
+end
+```
+
+Run the migration:
+
+```bash
+bin/rails db:migrate
+```
+
+> **INFO:** We intentionally don't add a foreign key constraint. This keeps the association optional and avoids issues if brands are deleted. Spree follows this pattern for flexibility.
+
+## Step 2: Generate the Product Decorator
+
+Spree provides a generator to create decorator files with the correct structure:
+
+```bash
+bin/rails g spree:model_decorator Spree::Product
+```
+
+This creates `app/models/spree/product_decorator.rb`:
+
+```ruby app/models/spree/product_decorator.rb
+module Spree
+  module ProductDecorator
+    def self.prepended(base)
+      # Class-level configurations go here
+    end
+  end
+
+  Product.prepend(ProductDecorator)
+end
+```
+
+## Step 3: Add the Brand Association to Product
+
+Update the decorator to add the `belongs_to` association:
+
+```ruby app/models/spree/product_decorator.rb {4}
+module Spree
+  module ProductDecorator
+    def self.prepended(base)
+      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
+    end
+  end
+
+  Product.prepend(ProductDecorator)
+end
+```
+
+### Understanding the Code
+
+- `self.prepended(base)` - This callback runs when the module is prepended to a class. The `base` parameter is the class being decorated (`Spree::Product`)
+- `base.belongs_to` - We call class methods on `base` to add associations, validations, scopes, etc.
+- `optional: true` - Products don't require a brand (the `brand_id` can be `NULL`)
+
+## Step 4: Add Products Association to Brand
+
+Now update your Brand model to define the reverse association:
+
+```ruby app/models/spree/brand.rb {5}
+module Spree
+  class Brand < Spree::Base
+    # ... existing code ...
+
+    has_many :products, class_name: 'Spree::Product', dependent: :nullify
+
+    # ... rest of your model ...
+  end
+end
+```
+
+> **INFO:** We use `dependent: :nullify` instead of `dependent: :destroy`. When a brand is deleted, products will have their `brand_id` set to `NULL` rather than being deleted. This is safer for e-commerce data.
+
+## Step 5: Permit the Brand Parameter
+
+For the admin form to save the brand association, we need to permit the `brand_id` parameter.
+
+Add to your Spree initializer:
+
+```ruby config/initializers/spree.rb {3}
+# .. other code ..
+
+Spree::PermittedAttributes.product_attributes << :brand_id
+```
+
+## Step 6: Add Brand Selector to Product Admin Form
+
+Create a partial to inject the brand selector into the product form. Spree's admin product form has injection points for customization.
+
+Create the partial:
+
+```erb app/views/spree/admin/products/_brand_field.html.erb
+<div class="card mb-6">
+  <div class="card-header">
+    <h5 class="card-title"><%= Spree.t(:brand) %></h5>
+  </div>
+  <div class="card-body">
+  <%= f.spree_select :brand_id,
+      Spree::Brand.order(:name).pluck(:name, :id),
+      { include_blank: true, label: Spree.t(:brand) } %>
+</div>
+```
+
+Register this partial to appear in the product form. Add to your initializer:
+
+**Spree 5.2+:**
+
+```ruby config/initializers/spree.rb
+    Rails.application.config.after_initialize do
+      Spree.admin.partials.product_form_sidebar << 'spree/admin/products/brand_field'
+    end
+    ```
+
+  **Spree 5.1 and below:**
+
+```ruby config/initializers/spree.rb
+    Rails.application.config.spree_admin.product_form_sidebar_partials << 'spree/admin/products/brand_field'
+    ```
+
+
+## Step 7: Add Translation
+
+Add the translation for the brand label:
+
+```yaml config/locales/en.yml
+en:
+  spree:
+    brand: Brand
+```
+
+## Testing the Association
+
+Verify everything works in the Rails console:
+
+```ruby
+# Create a brand and product
+brand = Spree::Brand.create!(name: 'Nike')
+product = Spree::Product.first
+product.update!(brand: brand)
+
+# Test associations
+product.brand        # => #<Spree::Brand id: 1, name: "Nike"...>
+brand.products       # => [#<Spree::Product...>]
+brand.products.count # => 1
+```
+
+## Decorator Best Practices
+
+
+  - **Use prepended callback** — Always use `self.prepended(base)` for class-level additions like associations, validations, and scopes.
+
+  - **Keep decorators focused** — Each decorator should have a single responsibility. Create multiple decorators if needed.
+
+  - **Call super when overriding** — When overriding methods, call `super` to preserve original behavior unless you intentionally want to replace it.
+
+  - **Test decorated behavior** — Write tests specifically for your decorated functionality to catch regressions.
+
+
+### Common Decorator Patterns
+
+#### Adding Validations
+
+```ruby
+def self.prepended(base)
+  base.validates :custom_field, presence: true
+end
+```
+
+#### Adding Scopes
+
+```ruby
+def self.prepended(base)
+  base.scope :featured, -> { where(featured: true) }
+end
+```
+
+#### Adding Callbacks
+
+> **WARNING:** For callbacks that trigger side effects (syncing to external services, sending notifications, etc.), use [Events subscribers](/developer/core-concepts/events) instead of decorator callbacks. Events are easier to test and won't break during Spree upgrades.
+
+**Decorator approach** (use only for simple, internal logic):
+
+```ruby
+def self.prepended(base)
+  base.before_save :normalize_name
+end
+
+def normalize_name
+  self.name = name.strip.titleize if name.present?
+end
+```
+
+**Events approach** (recommended for side effects):
+
+```ruby app/subscribers/my_app/product_sync_subscriber.rb
+module MyApp
+  class ProductSyncSubscriber < Spree::Subscriber
+    subscribes_to 'product.updated'
+
+    def handle(event)
+      product = Spree::Product.find_by(id: event.payload['id'])
+      return unless product
+
+      ExternalSyncService.sync(product)
+    end
+  end
+end
+```
+
+#### Adding Class Methods
+
+```ruby
+def self.prepended(base)
+  base.extend ClassMethods
+end
+
+module ClassMethods
+  def my_class_method
+    # Class method logic
+  end
+end
+```
+
+## Complete Files
+
+### Product Decorator
+
+```ruby app/models/spree/product_decorator.rb
+module Spree
+  module ProductDecorator
+    def self.prepended(base)
+      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
+    end
+  end
+
+  Product.prepend(ProductDecorator)
+end
+```
+
+### Brand Model (Updated)
+
+```ruby app/models/spree/brand.rb
+module Spree
+  class Brand < Spree::Base
+    has_many :products, class_name: 'Spree::Product', dependent: :nullify
+
+    has_one_attached :logo
+    has_rich_text :description
+
+    validates :name, presence: true
+  end
+end
+```
+
+> **INFO:** SEO features like slugs, meta titles, and FriendlyId are covered in the [SEO](/developer/tutorial/seo) tutorial.
+
+### Spree Initializer Additions
+
+```ruby config/initializers/spree.rb
+# Permit brand_id in product params
+Spree::PermittedAttributes.product_attributes << :brand_id
+```
+
+**Spree 5.2+:**
+
+```ruby config/initializers/spree.rb
+    Rails.application.config.after_initialize do
+      # Add brand field to product form
+      Spree.admin.partials.product_form << 'spree/admin/products/brand_field'
+    end
+    ```
+
+  **Spree 5.1 and below:**
+
+```ruby config/initializers/spree.rb
+    # Add brand field to product form
+    Rails.application.config.spree_admin.product_form_partials << 'spree/admin/products/brand_field'
+    ```
+
+
+## Related Documentation
+
+- [Model Tutorial](/developer/tutorial/model) - Creating the Brand model
+- [Admin Tutorial](/developer/tutorial/admin) - Building the admin interface
+- [Events](/developer/core-concepts/events) - Subscribe to model changes without decorators
+- [Webhooks](/developer/core-concepts/webhooks) - HTTP callbacks for external integrations
+- [Decorators](/developer/customization/decorators) - Full decorator reference
+- [Customization Overview](/developer/customization/quickstart) - More customization patterns
+- [Products](/developer/core-concepts/products) - Product model documentation