@spree/docs 0.1.0

package/dist/developer/admin/tables.md

@@ -0,0 +1,491 @@
+---
+title: Admin Tables
+sidebarTitle: 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` |
+| `:posts` | `Spree::Post` |
+| `:post_categories` | `Spree::PostCategory` |
+| `: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](/developer/admin/navigation) - Add custom menu items to the admin
+- [Extending Admin UI](/developer/admin/extending-ui) - Inject partials into admin pages
+- [Search & Filtering](/developer/core-concepts/search-filtering) - Add searchable/filterable fields
+- [Customization Quickstart](/developer/customization/quickstart) - Overview of all customization options

package/dist/developer/advanced/adding_spree_to_rails_app.md

@@ -0,0 +1,106 @@
+---
+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_storefront', spree_opts # Storefront (optional)
+gem 'spree_emails', spree_opts # transactional emails (optional)
+gem 'spree_sample', spree_opts # dummy data like products, taxons, etc (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
+```
+
+### Install Storefront (optional)
+
+```bash
+bin/rails g spree:storefront:install
+bin/rails g spree:storefront:devise  # if using Devise authentication
+```
+
+## 3. Add sample data (optional)
+
+To add sample data to your store, run:
+
+```bash
+bin/rake spree_sample:load
+```
+
+This will add some products, categories, and will setup a checkout flow to your store.
+
+## 4. Exploring Your Store
+
+Feel free to explore your store. You can do so because Spree comes with a default pre-built Storefront and Admin Panel.
+
+### Logging into the Admin Dashboard
+
+Use your browser window to navigate to [http://localhost:3000/admin](http://localhost:3000/admin). You can log in with the default credentials:
+  - login: `spree@example.com`
+  - password: `spree123`
+
+Upon successful authentication, you should see the admin screen:
+
+![](https://vendo-production-res.cloudinary.com/image/upload/v1740668008/docs/admin_dashboard.png)
+
+Feel free to explore some of the Admin Panel features that Spree has to offer and to verify that your installation is working properly.
+
+### Browsing Storefront
+
+Spree comes with a default pre-built Storefront. You can access it by navigating to [http://localhost:3000](http://localhost:3000).
+
+You can later customize this Storefront or choose another one if you prefer Next.js or Vue.js.
+
+## All Done!
+
+Congrats! You've set up your Spree Commerce and it's looking amazing! Need support or want to give some feedback? You can join our [community](https://slack.spreecommerce.org/) or drop us an email at [hello@spreecommerce.org](mailto:hello@spreecommerce.org).