@spree/docs 0.1.177 → 0.1.178

package/dist/developer/admin/tables.md

@@ -1,490 +0,0 @@
----
-title: Admin Tables
-sidebarTitle: Tables
-description: Use the Spree Admin Tables DSL to define columns, sorting, filtering, and bulk actions for resource listings, and extend existing admin tables.
----
-
-Spree Admin provides a flexible table system for displaying resource listings with customizable columns, sorting, filtering, and bulk actions. The Tables DSL allows you to define table configurations for your resources and extend existing ones.
-
-> **INFO:** The Tables system uses a declarative API accessible via `Spree.admin.tables`. This allows you to programmatically add, modify, and remove table columns and bulk actions directly in your initializers.
-
-## Basic Usage
-
-### Creating a New Table
-
-Register a new table for your resource in `config/initializers/spree.rb`:
-
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  # Register a new table
-  Spree.admin.tables.register(:brands, model_class: Spree::Brand, search_param: :name_cont)
-
-  # Add columns
-  Spree.admin.tables.brands.add :name,
-    label: :name,
-    type: :link,
-    sortable: true,
-    default: true,
-    position: 10
-
-  Spree.admin.tables.brands.add :products_count,
-    label: :products,
-    type: :number,
-    sortable: false,
-    default: true,
-    position: 20,
-    method: ->(brand) { brand.products.count }
-
-  Spree.admin.tables.brands.add :created_at,
-    label: :created_at,
-    type: :datetime,
-    sortable: true,
-    default: false,
-    position: 30
-end
-```
-
-### Using the Table in Views
-
-Render the table in your index view using the `render_table` helper:
-
-```erb app/views/spree/admin/brands/index.html.erb
-<%= render_table @collection, :brands %>
-```
-
-With additional options:
-
-```erb
-<%= render_table @collection, :brands,
-                 bulk_operations: true,
-                 export_type: Spree::Exports::Brands %>
-```
-
-## Table Registration Options
-
-When registering a table, you can specify these options:
-
-- **`model_class`** (`Class`) — The model class for the table (e.g., `Spree::Brand`).
-
-- **`search_param`** (`Symbol`) — The Ransack search parameter for the search box.
-
-- **`search_placeholder`** (`String`) — Custom placeholder text for the search box.
-
-- **`row_actions`** (`Boolean`) — Enable row action buttons (edit/delete dropdown).
-
-- **`row_actions_edit`** (`Boolean`) — Show edit action in row actions dropdown.
-
-- **`row_actions_delete`** (`Boolean`) — Show delete action in row actions dropdown.
-
-- **`new_resource`** (`Boolean`) — Show "New Resource" button when collection is empty.
-
-- **`date_range_param`** (`Symbol`) — Enable date range filter for the specified column (e.g., `:created_at`).
-
-- **`link_to_action`** (`Symbol`) — Action for link columns (`:edit` or `:show`).
-
-## Column Options
-
-All columns support the following options:
-
-- **`label`** (`Symbol or String`) — The column header label. Can be a symbol (translation key using `Spree.t`) or a string.
-
-- **`type`** (`String`) — The column type. Determines how the value is rendered.
-
-  Available types:
-  - `string` - Plain text
-  - `number` - Numeric value
-  - `date` - Date formatted with `spree_date` helper
-  - `datetime` - Relative time with `spree_time_ago` helper
-  - `money` - Currency formatted with `Spree::Money`
-  - `status` - Badge with status-based styling
-  - `link` - Clickable link to resource
-  - `boolean` - Active/inactive badge
-  - `image` - Thumbnail image
-  - `association` - Associated record name(s)
-  - `custom` - Custom partial rendering
-
-- **`sortable`** (`Boolean`) — Whether the column can be sorted.
-
-- **`filterable`** (`Boolean`) — Whether the column appears in the query builder filter options.
-
-- **`displayable`** (`Boolean`) — Whether the column can be shown/hidden by users. Set to `false` for filter-only columns.
-
-- **`default`** (`Boolean`) — Whether the column is visible by default.
-
-- **`position`** (`Integer`) — Column order. Lower numbers appear first.
-
-- **`method`** (`Symbol or Lambda`) — Custom method to extract the column value. Can be a method name or lambda.
-
-- **`align`** (`String`) — Text alignment: `left`, `center`, or `right`.
-
-- **`width`** (`String`) — Column width class (e.g., `"20"` for `w-20`).
-
-- **`if`** (`Lambda`) — Conditional visibility. Column only appears if lambda returns true.
-
-### Filter-specific Options
-
-- **`filter_type`** (`String`) — Override the filter input type. Available: `string`, `number`, `date`, `datetime`, `money`, `status`, `boolean`, `autocomplete`, `select`.
-
-- **`ransack_attribute`** (`String`) — Custom Ransack attribute name for filtering/sorting (defaults to column key).
-
-- **`operators`** (`Array`) — Available filter operators. Defaults based on column type.
-
-- **`value_options`** (`Array or Lambda`) — Options for select/status filters. Array of hashes with `value` and `label` keys.
-
-- **`search_url`** (`String | Lambda`) — URL for autocomplete filter type. Use a Lambda for dynamic paths: `search_url: ->(view_context) { view_context.spree.admin_taxons_select_options_path(format: :json) }`.
-
-### Custom Sort Options
-
-- **`sort_scope_asc`** (`Symbol`) — Custom scope name for ascending sort (bypasses Ransack).
-
-- **`sort_scope_desc`** (`Symbol`) — Custom scope name for descending sort (bypasses Ransack).
-
-### Custom Partial Options
-
-- **`partial`** (`String`) — Partial path for `custom` type columns.
-
-- **`partial_locals`** (`Hash or Lambda`) — Additional locals to pass to the partial. Lambda receives the record.
-
-## Column Types Examples
-
-### String Column
-
-```ruby
-Spree.admin.tables.brands.add :name,
-  label: :name,
-  type: :string,
-  sortable: true,
-  default: true
-```
-
-### Link Column
-
-Links to the resource edit or show page:
-
-```ruby
-Spree.admin.tables.brands.add :name,
-  label: :name,
-  type: :link,
-  sortable: true,
-  default: true
-```
-
-### Money Column
-
-Displays formatted currency:
-
-```ruby
-Spree.admin.tables.products.add :price,
-  label: :price,
-  type: :money,
-  sortable: true,
-  default: true,
-  align: :right,
-  method: ->(product) { product.display_price }
-```
-
-### Status Column
-
-Displays a colored badge based on the status value:
-
-```ruby
-Spree.admin.tables.orders.add :state,
-  label: :state,
-  type: :status,
-  filter_type: :select,
-  sortable: true,
-  default: true,
-  value_options: -> {
-    Spree::Order.state_machine(:state).states.map { |s|
-      { value: s.name.to_s, label: s.name.to_s.humanize }
-    }
-  }
-```
-
-Status values are automatically styled:
-- **Green** (`badge-active`): `active`, `complete`, `completed`, `paid`, `shipped`, `available`
-- **Yellow** (`badge-warning`): `draft`, `pending`, `processing`, `ready`
-- **Gray** (`badge-inactive`): `archived`, `canceled`, `cancelled`, `failed`, `void`, `inactive`
-
-### Boolean Column
-
-```ruby
-Spree.admin.tables.products.add :available,
-  label: :available,
-  type: :boolean,
-  sortable: true,
-  default: true
-```
-
-### DateTime Column
-
-Displays relative time (e.g., "2 hours ago"):
-
-```ruby
-Spree.admin.tables.orders.add :completed_at,
-  label: :completed_at,
-  type: :datetime,
-  sortable: true,
-  default: true
-```
-
-### Association Column
-
-For displaying related records:
-
-```ruby
-Spree.admin.tables.products.add :taxons,
-  label: :taxons,
-  type: :association,
-  filter_type: :autocomplete,
-  sortable: false,
-  filterable: true,
-  default: false,
-  ransack_attribute: 'taxons_id',
-  operators: [:in],
-  search_url: ->(view_context) { view_context.spree.admin_taxons_select_options_path(format: :json) },
-  method: ->(product) { product.taxons.map(&:pretty_name).join(', ') }
-```
-
-### Custom Partial Column
-
-For complex rendering:
-
-```ruby
-Spree.admin.tables.products.add :name,
-  label: :name,
-  type: :custom,
-  sortable: true,
-  default: true,
-  partial: 'spree/admin/tables/columns/product_name'
-
-# With dynamic locals
-Spree.admin.tables.orders.add :customer,
-  label: :customer,
-  type: :custom,
-  default: true,
-  partial: 'spree/admin/orders/customer_summary',
-  partial_locals: ->(record) { { order: record } }
-```
-
-The partial receives `record`, `column`, and `value` locals plus any custom locals.
-
-### Filter-only Column
-
-Columns that can be filtered but not displayed:
-
-```ruby
-Spree.admin.tables.orders.add :sku,
-  label: :sku,
-  type: :string,
-  sortable: false,
-  filterable: true,
-  displayable: false,
-  ransack_attribute: 'line_items_variant_sku'
-```
-
-## Modifying Existing Tables
-
-### Adding Columns to Existing Tables
-
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  # Add a custom column to products
-  Spree.admin.tables.products.add :vendor,
-    label: 'Vendor',
-    type: :string,
-    sortable: false,
-    default: true,
-    position: 25,
-    method: ->(product) { product.vendor&.name },
-    if: -> { defined?(Spree::Vendor) }
-end
-```
-
-### Updating Existing Columns
-
-```ruby
-Rails.application.config.after_initialize do
-  # Change the position of an existing column
-  Spree.admin.tables.products.update :price, position: 15
-
-  # Make a column default
-  Spree.admin.tables.products.update :sku, default: true
-
-  # Change column label
-  Spree.admin.tables.orders.update :number, label: 'Order #'
-end
-```
-
-### Removing Columns
-
-```ruby
-Rails.application.config.after_initialize do
-  # Remove a column entirely
-  Spree.admin.tables.products.remove :sku
-end
-```
-
-### Inserting Columns at Specific Positions
-
-```ruby
-Rails.application.config.after_initialize do
-  # Insert before an existing column
-  Spree.admin.tables.products.insert_before :price, :cost_price,
-    label: 'Cost Price',
-    type: :money,
-    default: false
-
-  # Insert after an existing column
-  Spree.admin.tables.products.insert_after :name, :brand,
-    label: 'Brand',
-    type: :string,
-    default: true,
-    method: ->(product) { product.brand&.name }
-end
-```
-
-## Bulk Actions
-
-Add bulk actions that appear when users select multiple rows:
-
-```ruby
-Rails.application.config.after_initialize do
-  Spree.admin.tables.products.add_bulk_action :set_active,
-    label: 'admin.bulk_ops.products.title.set_active',
-    icon: 'circle-check',
-    action_path: ->(view_context) { view_context.spree.bulk_status_update_admin_products_path(status: 'active') },
-    body: 'admin.bulk_ops.products.body.set_active',
-    position: 10,
-    if: -> { can?(:activate, Spree::Product) }
-end
-```
-
-The modal is automatically rendered via `/admin/bulk_operations/new?kind=:action_key&table_key=:table_key`.
-
-### Bulk Action Options
-
-- **`label`** (`String`) — Translation key or text for the action button.
-
-- **`icon`** (`String`) — Icon name from [Tabler Icons](https://tabler.io/icons).
-
-- **`action_path`** (`String | Lambda`) — URL for the bulk action endpoint. Use a Lambda for dynamic paths: `action_path: ->(view_context) { view_context.custom_path }`.
-
-- **`method`** (`Symbol`) — HTTP method for the action (`:get`, `:post`, `:put`, `:patch`, `:delete`).
-
-- **`position`** (`Integer`) — Order in the bulk actions menu.
-
-- **`if`** (`Lambda`) — Conditional visibility based on user permissions.
-
-- **`confirm`** (`String`) — Confirmation message before executing the action.
-
-- **`button_text`** (`String`) — Custom text for the modal submit button. Supports translation keys. Defaults to "Confirm".
-
-- **`button_class`** (`String`) — CSS class for the modal submit button (e.g., `btn-danger` for destructive actions).
-
-### Managing Bulk Actions
-
-```ruby
-# Update a bulk action
-Spree.admin.tables.products.update_bulk_action :set_active, position: 5
-
-# Remove a bulk action
-Spree.admin.tables.products.remove_bulk_action :set_archived
-```
-
-## Custom Sorting
-
-For columns that need custom database queries:
-
-```ruby
-# In your model
-class Spree::Product < Spree.base_class
-  scope :ascend_by_price, -> { joins(:master).order('spree_variants.price ASC') }
-  scope :descend_by_price, -> { joins(:master).order('spree_variants.price DESC') }
-end
-
-# In your initializer
-Spree.admin.tables.products.add :price,
-  label: :price,
-  type: :money,
-  sortable: true,
-  default: true,
-  sort_scope_asc: :ascend_by_price,
-  sort_scope_desc: :descend_by_price,
-  method: ->(product) { product.price }
-```
-
-## Available Tables
-
-Spree registers tables for all built-in resources:
-
-| Table Key | Model Class |
-|-----------|-------------|
-| `:products` | `Spree::Product` |
-| `:orders` | `Spree::Order` |
-| `:checkouts` | `Spree::Order` (draft) |
-| `:users` | `Spree.user_class` |
-| `:promotions` | `Spree::Promotion` |
-| `:customer_returns` | `Spree::CustomerReturn` |
-| `:option_types` | `Spree::OptionType` |
-| `:newsletter_subscribers` | `Spree::NewsletterSubscriber` |
-| `:policies` | `Spree::Policy` |
-| `:stock_transfers` | `Spree::StockTransfer` |
-| `:metafield_definitions` | `Spree::MetafieldDefinition` |
-| `:gift_cards` | `Spree::GiftCard` |
-| `:stock_items` | `Spree::StockItem` |
-| `:webhook_endpoints` | `Spree::WebhookEndpoint` |
-| `:webhook_deliveries` | `Spree::WebhookDelivery` |
-| `:price_list_products` | `Spree::Product` (nested) |
-
-## API Reference
-
-### Table Methods
-
-```ruby
-table = Spree.admin.tables.products
-
-# Column management
-table.add(key, **options)           # Add a new column
-table.remove(key)                   # Remove a column
-table.update(key, **options)        # Update column options
-table.find(key)                     # Find a column by key
-table.exists?(key)                  # Check if column exists
-table.insert_before(target, key, **options)
-table.insert_after(target, key, **options)
-
-# Query columns
-table.available_columns             # All displayable columns
-table.default_columns               # Columns shown by default
-table.visible_columns(selected, ctx) # Columns for current view
-table.sortable_columns              # Columns that can be sorted
-table.filterable_columns            # Columns for query builder
-
-# Bulk actions
-table.add_bulk_action(key, **options)
-table.remove_bulk_action(key)
-table.update_bulk_action(key, **options)
-table.find_bulk_action(key)
-table.visible_bulk_actions(context)
-table.bulk_operations_enabled?
-```
-
-### Registry Methods
-
-```ruby
-# Check if a table is registered
-Spree.admin.tables.registered?(:brands)
-
-# Get a table
-Spree.admin.tables.get(:products)
-
-# Shorthand access
-Spree.admin.tables.products
-```
-
-## Related Documentation
-
-- [Admin Navigation](navigation.md) - Add custom menu items to the admin
-- [Extending Admin UI](extending-ui.md) - Inject partials into admin pages
-- [Search & Filtering](../core-concepts/search-filtering.md) - Add searchable/filterable fields
-- [Customization Quickstart](../customization/quickstart.md) - Overview of all customization options

package/dist/developer/advanced/adding_spree_to_rails_app.md

@@ -1,92 +0,0 @@
----
-title: Adding to an existing Rails app
-description: This guide will show you how to add Spree to an existing Ruby on Rails application.
----
-
-> **WARNING:** This guide is aimed at advanced users who want to add Spree to an existing Rails application. If you are new to Spree, please follow the [Quickstart guide](/getting-started/quickstart).
-
-## Overview
-
-If you already have a Ruby on Rails application, you can add Spree to it by following these steps.
-
-> **INFO:** Spree works with **PostgreSQL**, **MySQL**, and **SQLite** — whatever database your Rails app already uses. No database migration is needed.
-
-## 1. Add Spree gems
-
-Add these lines to your project `Gemfile`:
-
-```ruby
-spree_opts = { 'github': 'spree/spree', 'branch': 'main' }
-gem 'spree', spree_opts # core, API, and CLI
-gem 'spree_admin', spree_opts # Admin panel (optional)
-gem 'spree_emails', spree_opts # transactional emails (optional)
-```
-
-And run the following command to install the gems:
-
-```bash
-bundle install
-```
-
-## 2. Run the install generators
-
-Spree uses a modular installation approach. First install the core, then add optional components.
-
-### Install core Spree
-
-This installs core models, API, CLI, and authentication:
-
-```bash
-bin/rails g spree:install --user_class=Spree::User --authentication=devise
-```
-
-**Core installation options:**
-
-| Option | Description |
-|--------|-------------|
-| `user_class` | The class for your users, eg. `Spree::User` or `User` |
-| `admin_user_class` | The class for admin users (defaults to `user_class`) |
-| `authentication` | Authentication gem: `devise` or `custom` |
-| `migrate` | Whether to run migrations (default: true) |
-| `seed` | Whether to run the seed file (default: true) |
-| `sample` | Whether to add sample data (default: false) |
-| `admin_email` | Email of the first admin user |
-| `admin_password` | Password of the first admin user |
-
-### Install Admin Panel (optional)
-
-```bash
-bin/rails g spree:admin:install
-bin/rails g spree:admin:devise  # if using Devise authentication
-```
-
-### Add sample data (optional)
-
-To add sample data to your store, run:
-
-```bash
-bin/rake spree:load_sample_data
-```
-
-This will add some products, categories and multiple markets to your store.
-
-## Accessing Admin Panel
-
-Navigate to [http://localhost:3000/admin](http://localhost:3000/admin) and log in with the default credentials:
-
-| | |
-|---|---|
-| **Email** | `spree@example.com` |
-| **Password** | `spree123` |
-
-Upon successful authentication, you should see the admin screen:
-
-<img src="/images/spree_admin_dashboard.png" />
-
----
-
-Congrats! You've set up your Spree Commerce and it's looking amazing!
-
-Give Spree a [GitHub Star](https://github.com/spree/spree), why don't ya? Thank you for supporting Spree open-source! 
-
-Need support or want to give some feedback? Join our [Discord](https://discord.spreecommerce.org/)

package/dist/developer/core-concepts/adjustments.md

@@ -1,113 +0,0 @@
----
-title: Adjustments
-description: How Spree adjustments apply taxes, promotions, and other price modifications to orders, line items, and shipments, and how totals are recalculated.
----
-
-## Overview
-
-An Adjustment modifies the price of an [Order](orders.md), a [Line Item](orders.md#line-items), or a [Shipment](shipments.md). Adjustments can be positive (charges) or negative (credits).
-
-```mermaid
-erDiagram
-    Adjustment {
-        decimal amount
-        string label
-        boolean eligible
-        boolean mandatory
-        string state
-        boolean included
-        string source_type
-        string adjustable_type
-    }
-
-    Order ||--o{ Adjustment : "has many"
-    Order ||--o{ LineItem : "has many"
-    Order ||--o{ Shipment : "has many"
-    LineItem ||--o{ Adjustment : "has many"
-    Shipment ||--o{ Adjustment : "has many"
-    TaxRate ||--o{ Adjustment : "creates"
-    PromotionAction ||--o{ Adjustment : "creates"
-```
-
-**Key relationships:**
-- **Adjustment** modifies prices on orders, line items, or shipments
-- **Source** is where the adjustment comes from ([Tax Rate](taxes.md) or [Promotion Action](promotions.md))
-- **Adjustable** is what's being adjusted (Order, LineItem, or Shipment)
-- Positive amounts are charges, negative amounts are credits
-
-## Adjustment Types
-
-### Included vs Additional
-
-- **Included** adjustments are part of the item's displayed price (e.g., VAT in European stores)
-- **Additional** adjustments are added on top of the item's price (e.g., US sales tax)
-
-### Sources
-
-Adjustments are created by two sources:
-
-| Source | Example | Typical Amount |
-|--------|---------|----------------|
-| [Tax Rate](taxes.md) | Sales tax, VAT | Positive (charge) |
-| [Promotion Action](promotions.md) | Coupon discount, free shipping | Negative (credit) |
-
-## Adjustment Attributes
-
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| `amount` | The monetary value of the adjustment | `-10.00` |
-| `label` | Human-readable description | `10% off order` |
-| `eligible` | Whether the adjustment currently applies | `true` |
-| `mandatory` | If `true`, always applied regardless of eligibility rules | `false` |
-| `state` | `open` (auto-updated) or `closed` (locked) | `open` |
-| `included` | Whether the amount is included in the item's displayed price | `false` |
-
-## Adjustment Lifecycle
-
-- **Open** adjustments are recalculated whenever the order is updated (e.g., items added/removed, address changed)
-- **Closed** adjustments are locked and will not be automatically recalculated
-- When a promotion becomes ineligible (e.g., item removed from cart), its adjustments are automatically removed
-
-## Store API
-
-Adjustments appear in order responses when you [`?expand=items,fulfillments`](../../api-reference/store-api/relations.md) on the order. The response exposes the [`amount`, `adjustment_total`, and the tax totals](../../api-reference/store-api/monetary-amounts.md) as money fields:
-
-
-```typescript Store SDK
-const order = await client.orders.get('or_abc123', { expand: ['items', 'fulfillments'] }, {
-  spreeToken: '<token>',
-})
-
-// Line item adjustments (promotions, taxes)
-order.items?.forEach(item => {
-  item.adjustment_total  // total adjustments on this item
-  item.additional_tax_total
-  item.included_tax_total
-})
-
-// Order-level totals
-order.adjustment_total       // total of all adjustments
-order.discount_total         // total promotional discounts
-order.display_discount_total // formatted promotional discounts
-order.additional_tax_total
-order.included_tax_total
-```
-
-```typescript Admin SDK
-const order = await adminClient.orders.get('or_abc123')
-```
-
-```bash cURL
-curl 'https://api.mystore.com/api/v3/store/orders/or_abc123?expand=items,fulfillments' \
-  -H 'X-Spree-API-Key: pk_xxx' \
-  -H 'X-Spree-Token: <token>'
-```
-
-
-## Related Documentation
-
-- [Promotions](promotions.md) — Promotion-based adjustments
-- [Taxes](taxes.md) — Tax adjustments
-- [Shipments](shipments.md) — Shipping adjustments
-- [Orders](orders.md) — How adjustments affect order totals
-- [Calculators](calculators.md) — How tax rate and promotion action amounts are computed