solidus_admin 0.2.0 → 0.3.0

data/app/controllers/solidus_admin/users_controller.rb

@@ -3,12 +3,15 @@
 module SolidusAdmin
   class UsersController < SolidusAdmin::BaseController
     include SolidusAdmin::ControllerHelpers::Search
+    include Spree::Core::ControllerHelpers::StrongParameters
 
-    search_scope(:customers, default: true) { _1.left_outer_joins(:role_users).where(role_users: { id: nil }) }
+    before_action :set_user, only: [:edit, :addresses, :update_addresses, :orders, :items]
+
+    search_scope(:all, default: true)
+    search_scope(:customers) { _1.left_outer_joins(:role_users).where(role_users: { id: nil }) }
     search_scope(:admin) { _1.joins(:role_users).distinct }
     search_scope(:with_orders) { _1.joins(:orders).distinct }
     search_scope(:without_orders) { _1.left_outer_joins(:orders).where(orders: { id: nil }) }
-    search_scope(:all)
 
     def index
       users = apply_search_to(
@@ -23,6 +26,52 @@ module SolidusAdmin
       end
     end
 
+    def addresses
+      respond_to do |format|
+        format.turbo_stream { render turbo_stream: '<turbo-stream action="refresh" />' }
+        format.html { render component('users/addresses').new(user: @user) }
+      end
+    end
+
+    def update_addresses
+      set_address_from_params
+
+      if @address.valid? && @user.update(user_params)
+        flash[:success] = t(".#{@type}.success")
+
+        respond_to do |format|
+          format.turbo_stream { render turbo_stream: '<turbo-stream action="refresh" />' }
+          format.html { render component('users/addresses').new(user: @user) }
+        end
+      else
+        respond_to do |format|
+          format.html { render component('users/addresses').new(user: @user, address: @address, type: @type), status: :unprocessable_entity }
+        end
+      end
+    end
+
+    def orders
+      set_orders
+
+      respond_to do |format|
+        format.html { render component('users/orders').new(user: @user, orders: @orders) }
+      end
+    end
+
+    def items
+      set_items
+
+      respond_to do |format|
+        format.html { render component('users/items').new(user: @user, items: @items) }
+      end
+    end
+
+    def edit
+      respond_to do |format|
+        format.html { render component('users/edit').new(user: @user) }
+      end
+    end
+
     def destroy
       @users = Spree.user_class.where(id: params[:id])
 
@@ -34,13 +83,43 @@ module SolidusAdmin
 
     private
 
-    def load_user
-      @user = Spree.user_class.find_by!(number: params[:id])
-      authorize! action_name, @user
+    def set_user
+      @user = Spree.user_class.find(params[:id])
     end
 
     def user_params
-      params.require(:user).permit(:user_id, permitted_user_attributes)
+      params.require(:user).permit(
+        :user_id,
+        permitted_user_attributes,
+        bill_address_attributes: permitted_address_attributes,
+        ship_address_attributes: permitted_address_attributes
+      )
+    end
+
+    # @note This method is used to generate validation errors on the address.
+    #   Since the update is being performed via the @user, and not directly on
+    #   the @address, we sadly don't seem to get these errors automatically.
+    def set_address_from_params
+      if user_params.key?(:bill_address_attributes)
+        @address = Spree::Address.new(user_params[:bill_address_attributes])
+        @type = "bill"
+      elsif user_params.key?(:ship_address_attributes)
+        @address = Spree::Address.new(user_params[:ship_address_attributes])
+        @type = "ship"
+      end
+    end
+
+    def set_orders
+      params[:q] ||= {}
+      @search = Spree::Order.reverse_chronological.ransack(params[:q].merge(user_id_eq: @user.id))
+      @orders = @search.result.page(params[:page]).per(Spree::Config[:admin_products_per_page])
+    end
+
+    def set_items
+      params[:q] ||= {}
+      @search = Spree::Order.reverse_chronological.includes(line_items: { variant: [:product, { option_values: :option_type }] }).ransack(params[:q].merge(user_id_eq: @user.id))
+      @orders = @search.result.page(params[:page]).per(Spree::Config[:admin_products_per_page])
+      @items = @orders&.map(&:line_items)&.flatten
     end
 
     def authorization_subject

data/app/controllers/solidus_admin/zones_controller.rb

@@ -28,11 +28,6 @@ module SolidusAdmin
 
     private
 
-    def load_zone
-      @zone = Spree::Zone.find_by!(number: params[:id])
-      authorize! action_name, @zone
-    end
-
     def zone_params
       params.require(:zone).permit(:zone_id, permitted_zone_attributes)
     end

data/app/helpers/solidus_admin/last_login_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  module LastLoginHelper
+    def last_login(user)
+      return t('solidus_admin.users.last_login.never') if user.try(:last_sign_in_at).blank?
+
+      t(
+        'solidus_admin.users.last_login.login_time_ago',
+        # @note The second `.try` is here for the specs and for setups that use a
+        # custom User class which may not have this attribute.
+        last_login_time: time_ago_in_words(user.try(:last_sign_in_at))
+      ).capitalize
+    end
+  end
+end

data/app/helpers/solidus_admin/permission_sets_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SolidusAdmin
+  module PermissionSetsHelper
+    # @param permission_sets [Array<Spree::PermissionSet>] an array of
+    #   PermissionSet objects to be organized into categories based on their
+    #   names.
+    # @param view_label [String] A string of your choice associated with "View"
+    #   or "Display" level permissions. Used when rendering the checkbox.
+    # @param edit_label [String] A string of your choice associated with "Edit"
+    #   or "Management" level permissions. Used when rendering the checkbox.
+    def organize_permissions(permission_sets:, view_label:, edit_label:)
+      return {} if permission_sets.blank?
+
+      permission_sets.each_with_object({}) do |permission, grouped_permissions|
+        group_key = permission.category.to_sym
+
+        case permission.privilege
+        when "display"
+          grouped_permissions[group_key] ||= []
+          grouped_permissions[group_key] << { label: view_label, id: permission.id }
+        when "management"
+          grouped_permissions[group_key] ||= []
+          grouped_permissions[group_key] << { label: edit_label, id: permission.id }
+        else
+          grouped_permissions[:other] ||= []
+          grouped_permissions[:other] << { label: permission.name, id: permission.id }
+        end
+      end
+    end
+  end
+end

data/app/views/layouts/solidus_admin/application.html.erb

@@ -11,6 +11,7 @@
     <%= stylesheet_link_tag SolidusAdmin::Config.theme_path(session[:admin_light_theme]), media: '(prefers-color-scheme: light)', "data-turbo-track": "reload" %>
     <%= stylesheet_link_tag SolidusAdmin::Config.theme_path(session[:admin_dark_theme]), media: '(prefers-color-scheme: dark)', "data-turbo-track": "reload" %>
     <%= javascript_importmap_tags "solidus_admin/application", shim: false, importmap: SolidusAdmin.importmap %>
+    <meta name="turbo-refresh-scroll", content="preserve">
   </head>
 
   <body class="bg-gray-15 font-sans">
@@ -29,7 +30,7 @@
 
     <div class="fixed inset-x-0 bottom-3 flex items-center justify-center flex-col gap-3 pointer-events-none" role="alert">
       <% flash.each do |key, message| %>
-        <%= render component("ui/toast").new(text: message, scheme: key == :error ? :error : :default) %>
+        <%= render component("ui/toast").new(text: message, scheme: key.to_sym == :error ? :error : :default) %>
       <% end %>
     </div>
   </body>

data/config/locales/adjustment_reasons.en.yml

@@ -3,4 +3,8 @@ en:
     adjustment_reasons:
       title: "Adjustment Reasons"
       destroy:
-        success: "Adjustment Reasons were successfully removed."
+        success: "Adjustment reasons were successfully removed."
+      create:
+        success: "Adjustment reason was successfully created."
+      update:
+        success: "Adjustment reason was successfully updated."

data/config/locales/adjustments.en.yml

@@ -0,0 +1,10 @@
+en:
+  solidus_admin:
+    adjustments:
+      title: "Adjustments"
+      lock:
+        success: "Locked successfully"
+      unlock:
+        success: "Unlocked successfully"
+      destroy:
+        success: "Deleted successfully"

data/config/locales/refund_reasons.en.yml

@@ -0,0 +1,10 @@
+en:
+  solidus_admin:
+    refund_reasons:
+      title: "Refund Reasons"
+      destroy:
+        success: "Refund reasons were successfully removed."
+      create:
+        success: "Refund reason was successfully created."
+      update:
+        success: "Refund reason was successfully updated."

data/config/locales/return_reasons.en.yml

@@ -3,4 +3,8 @@ en:
     return_reasons:
       title: "Return Reasons"
       destroy:
-        success: "Return Reasons were successfully removed."
+        success: "Return reasons were successfully removed."
+      create:
+        success: "Return reason was successfully created."
+      update:
+        success: "Return reason was successfully updated."

data/config/locales/roles.en.yml

@@ -0,0 +1,10 @@
+en:
+  solidus_admin:
+    roles:
+      title: "Roles"
+      destroy:
+        success: "Roles were successfully removed."
+      create:
+        success: "Role was successfully created."
+      update:
+        success: "Role was successfully updated."

data/config/locales/shipping_categories.en.yml

@@ -4,3 +4,7 @@ en:
       title: "Shipping Categories"
       destroy:
         success: "Shipping categories were successfully removed."
+      create:
+        success: "Shipping category was successfully created."
+      update:
+        success: "Shipping category was successfully updated."

data/config/locales/store_credit_reasons.en.yml

@@ -3,4 +3,8 @@ en:
     store_credit_reasons:
       title: "Store Credit Reasons"
       destroy:
-        success: "Store Credit Reasons were successfully removed."
+        success: "Store credit reasons were successfully removed."
+      create:
+        success: "Store credit reason was successfully created."
+      update:
+        success: "Store credit reason was successfully updated."

data/config/locales/tax_categories.en.yml

@@ -4,3 +4,7 @@ en:
       title: "Tax Categories"
       destroy:
         success: "Tax categories were successfully removed."
+      create:
+        success: "Tax category was successfully created."
+      update:
+        success: "Tax category was successfully updated."

data/config/locales/users.en.yml

@@ -4,3 +4,13 @@ en:
       title: "Users"
       destroy:
         success: "Users were successfully removed."
+      update_addresses:
+        bill:
+          success: "Billing Address has been successfully updated."
+        ship:
+          success: "Shipping Address has been successfully updated."
+        error: "Address could not be updated."
+      last_login:
+        never: "Never"
+        login_time_ago: "%{last_login_time} ago"
+        invitation_sent: "Invitation sent"

data/config/routes.rb

@@ -26,6 +26,14 @@ SolidusAdmin::Engine.routes.draw do
   admin_resources :orders, except: [
     :destroy, :index
   ], constraints: ->{ SolidusAdmin::Config.enable_alpha_features? } do
+    resources :adjustments, only: [:index] do
+      collection do
+        delete :destroy
+        put :lock
+        put :unlock
+      end
+    end
+
     resources :line_items, only: [:destroy, :create, :update]
     resource :customer
     resource :ship_address, only: [:show, :edit, :update], controller: "addresses", type: "ship"
@@ -37,24 +45,33 @@ SolidusAdmin::Engine.routes.draw do
     end
   end
 
-  admin_resources :users, only: [:index, :destroy]
+  admin_resources :users, only: [:index, :edit, :destroy] do
+    member do
+      get :addresses
+      put :update_addresses
+      get :orders
+      get :items
+    end
+  end
+
   admin_resources :promotions, only: [:index, :destroy]
   admin_resources :properties, only: [:index, :destroy]
   admin_resources :option_types, only: [:index, :destroy], sortable: true
   admin_resources :taxonomies, only: [:index, :destroy], sortable: true
   admin_resources :promotion_categories, only: [:index, :destroy]
-  admin_resources :tax_categories, only: [:index, :destroy]
+  admin_resources :tax_categories, except: [:show]
   admin_resources :tax_rates, only: [:index, :destroy]
   admin_resources :payment_methods, only: [:index, :destroy], sortable: true
   admin_resources :stock_items, only: [:index, :edit, :update]
   admin_resources :shipping_methods, only: [:index, :destroy]
-  admin_resources :shipping_categories, only: [:index, :destroy]
+  admin_resources :shipping_categories, except: [:show]
   admin_resources :stock_locations, only: [:index, :destroy]
   admin_resources :stores, only: [:index, :destroy]
   admin_resources :zones, only: [:index, :destroy]
-  admin_resources :refund_reasons, only: [:index, :destroy]
+  admin_resources :refund_reasons, except: [:show]
   admin_resources :reimbursement_types, only: [:index]
-  admin_resources :return_reasons, only: [:index, :destroy]
-  admin_resources :adjustment_reasons, only: [:index, :destroy]
-  admin_resources :store_credit_reasons, only: [:index, :destroy]
+  admin_resources :return_reasons, except: [:show]
+  admin_resources :roles, except: [:show]
+  admin_resources :adjustment_reasons, except: [:show]
+  admin_resources :store_credit_reasons, except: [:show]
 end

data/docs/components.md

@@ -0,0 +1,109 @@
+# Components
+
+Components are the main building blocks of the admin interface. They are implemented as ViewComponents and are rendered directly by controllers.
+
+The following documentation assumes familiariry with ViewComponents. If you are not please refer to the [ViewComponent documentation](https://viewcomponent.org/guide/).
+
+There are two types of components:
+
+- **UI components** are the building blocks of the interface. Tipically, they are small components that are used to build more complex components and are generic enough to be reused in various contexts. UI components are located under the `app/components/solidus_admin/ui` folder.
+- **Page components** are the primary components rendered by the controllers. Generally, they are full-page components rendered directly by the controllers. They are located under the `app/components/solidus_admin` directory following the naming convention of the controller and action names they are used in. For example `app/components/solidus_admin/orders/index/component.rb` is the component that is rendered by the `SolidusAdmin::OrdersController#index` action.
+
+## Generating components
+
+Components can be generated using the `solidus_admin:component` generator combined with the `bin/rails` command from the Solidus repository.
+
+```shell
+$ bin/rails admin g solidus_admin:component foo
+      create  app/components/solidus_admin/foo/component.rb
+      create  app/components/solidus_admin/foo/component.html.erb
+      create  app/components/solidus_admin/foo/component.yml
+      create  app/components/solidus_admin/foo/component.js
+```
+
+Using `bin/rails admin` will run the generator from the `solidus_admin` engine, instead of the sandbox application.
+
+## Coding style
+
+For UI components in particular, it's preferable to accept only simple Ruby values in the initializer and use alternative constructors to accept more complex objects. This makes components easier to use and test. For example:
+
+```ruby
+# bad
+
+class SolidusAdmin::UI::OrderStatus::Component < ViewComponent::Base
+  def initialize(order:)
+    @order = order
+  end
+end
+
+# good
+
+class SolidusAdmin::UI::OrderStatus::Component < ViewComponent::Base
+  def initialize(status:)
+    @status = status
+  end
+
+  def self.for_order(order)
+    new(status: order.status)
+  end
+end
+```
+
+For style variations within the component we use the term `scheme` rather than `variant` to avoid confusion with product variants.
+
+For size variations we use the term `size` with single letter values, e.g. `s`, `m`, `l`, `xl`, `xxl`.
+
+For text content we use the term `text` rather than `name` to avoid confusion with the `name` attribute of the HTML tag.
+
+## Component registry
+
+Components are registered in the `SolidusAdmin::Config.components` registry. This allows replacing components for customization purposes and components deprecation between versions.
+
+To retrieve component classes from the registry, use the `component` helper within controllers and components that inherit from `SolidusAdmin::BaseComponent` or include `SolidusAdmin::ComponentHelper`. For example, `component('ui/button')` will fetch `SolidusAdmin::UI::Button::Component`.
+
+## When to use UI vs. Page components
+
+Generally new components are built for a specific controller action and are used only within that action. In such cases, it's better to use a Page component and define it under the namespace of the action, e.g. `app/components/solidus_admin/orders/index/payment_status/component.rb`.
+
+If a component is used by multiple actions of the same controller it can be moved to the controller namespace, e.g. `app/components/solidus_admin/orders/payment_status/component.rb`.
+
+When a component is used by multiple controllers, you can either duplicate it in multiple places or move it to the `ui` namespace.
+
+Although it may seem counterintuitive, duplicating the component can often be beneficial. This allows you to modify the component in one place without affecting other components that might be using it. Over time, the two copies may share enough generic code that it can be extracted into a UI component.
+
+UI components should be very generic and reusable. However, they should not try to anticipate all possible use cases. Instead, they should be extracted from existing components that are already used in multiple places. This has proven to be the most effective way to build UI components. We've found that trying to anticipate theoretical use cases often leads to over-engineered code that eventually needs to be adapted to the actual use cases or is never used at all.
+
+## Naming conventions
+
+The project uses a naming convention for components that slightly deviates from ViewComponent defaults. This is done to simplify renaming components and moving them around.
+
+All files related to a component have a base name of `component`, each with its own extension. These files are placed in a folder named after the component class they define.
+
+
+E.g. `app/components/solidus_admin/orders/index/payment_status/component.rb` defines the `SolidusAdmin::Orders::Index::PaymentStatus::Component` class.
+
+With this approach, renaming a component is as simple as renaming the folder and the class name, without the need to change the names of all the files.
+
+## Translations
+
+Components can define their own translations in the `component.yml` file and they're expected to be self contained. This means that translations defined in `solidus_core` should not be used in components.
+
+Please refer to the [ViewComponent documentation](https://viewcomponent.org/guide/translations.html) for more information.
+
+## Previews and Lookbook
+
+For UI components we leverage [ViewComponent previews](https://viewcomponent.org/guide/previews.html) combined with [Lookbook](https://lookbook.build) to provide a live preview of the component. This approach is highly beneficial for understanding the component's appearance and how it can be modified using different arguments.
+
+Creating previews for page components can be challenging and prone to errors, as they often require a more complex context for rendering. Therefore, we typically don't use previews for page components, except for the most basic ones. However, if a component has a wide range of arguments and we want to cover all combinations, we might create a preview for it.
+
+In order to inspect previews it's enough to visit `/lookbook` in the browser while the server is running.
+
+## Testing
+
+Testing methods for components vary depending on whether they are UI or Page components. UI components are tested in isolation, while Page components, which often require a more complex context, are tested through feature specs.
+
+For UI components, we use previews to achieve maximum coverage. This approach is sufficient for most basic components, but more complex components may require additional specs. This method has proven to minimize maintenance and code churn in the spec code, and it avoids repeating the code needed to render the component with different arguments.
+
+Page components are tested in the context of the controller action they are used in. For example, `admin/spec/features/orders_spec.rb` covers interactions with the order listing and indirectly tests the `SolidusAdmin::Orders::Index::Component` class, among others.
+We've found this to be the most effective way to test page components, as recreating the context needed for them in isolation can be difficult and prone to errors.
+However, this is not a hard rule. If a Page component needs to be tested in isolation, or if a UI component requires a more complex context, you can always write additional specs.

data/docs/{customizing_view_components.md → customizing_components.md}

@@ -1,4 +1,4 @@
-# Customizing view components
+# Customizing components
 
 Solidus Admin uses [view components](https://viewcomponent.org/) to render the views. Components are
 a pattern for breaking up the view layer into small, reusable pieces, easy to
@@ -100,14 +100,9 @@ end
 If you need more control, you can explicitly register your component in the
 Solidus Admin container instead of using an implicit path:
 
-> ⓘ  Right now, that will raise an error when the application is reloaded. We
-> need to fix it.
-
 ```ruby
 # config/initalizers/solidus_admin.rb
-Rails.application.config.to_prepare do
-  SolidusAdmin::Config.components['ui/button'] = MyApplication::Button::Component
-end
+SolidusAdmin::Config.components['ui/button'] = "MyApplication::Button::Component"
 ```
 
 ### Tweaking a component

data/docs/index_pages.md

@@ -0,0 +1,146 @@
+# Adding index pages
+
+Index pages are common in the admin interface, and they are used to display a list of records for a specific model.
+
+Since these pages often have a similar appearance, we have a dedicated component to build them. This component helps avoid writing repetitive boilerplate code.
+
+## The `index` action
+
+The `index` action is the standard action used to display index pages. It's a standard `GET` action that renders the `index` component.
+
+To support search scopes and filters the controller should include the `SolidusAdmin::ControllerHelpers::Search` module and call
+`apply_search_to` as follows:
+
+```ruby
+class SolidusAdmin::UsersController < SolidusAdmin::BaseController
+  include SolidusAdmin::ControllerHelpers::Search
+
+  def index
+    users = apply_search_to(Spree.user_class.order(id: :desc), param: :q)
+    # ...
+```
+
+For pagination support, the index action should also call the `set_page_and_extract_portion_from` method provided by the `geared_pagination` gem. This method sets the `@page` instance variable to the paginated collection and returns the portion of the collection to be displayed on the current page.
+
+```ruby
+def index
+  users = apply_search_to(Spree.user_class.order(id: :desc), param: :q)
+  set_page_and_extract_portion_from(users)
+  # ...
+```
+
+Finally, the index action should render the `index` component passing the `@page` instance variable as the `collection` prop.
+
+```ruby
+def index
+  users = apply_search_to(Spree.user_class.order(id: :desc), param: :q)
+  set_page_and_extract_portion_from(users)
+  render component('users/index').new(page: @page)
+end
+```
+
+## The `ui/pages/index` component
+
+The `ui/pages/index` component is an abstract component that provides sensible defaults for index pages. It also offers template methods that can be used to customize the behavior of these pages.
+
+We recommend examining existing index pages and the UI component itself to understand how they work. In this section, we'll cover the most important aspects.
+
+The index component requires only the `page` argument during initialization, all other parameters are provided through template methods.
+
+```ruby
+class SolidusAdmin::Users::Index < Solidus::Admin::UI::Pages::Index
+  def model_class
+    Spree.user_class
+  end
+end
+
+render component('users/index').new(page: @page)
+```
+
+## Batch Actions
+
+Batch actions are operations that can be performed on multiple records simultaneously. The index page internally uses the `ui/table` component and depends on the `batch_actions` method to render the batch actions dropdown.
+
+In the component, batch actions are provided as an array of hashes, with each hash representing a single batch action. Each hash must contain the following keys:
+
+- `label`: the name of the batch action, this will be used as the label of the dropdown item
+- `icon`: the remix icon-name to be used as the icon of the dropdown item (see the `ui/icon` component for more information)
+- `action`: the name of the action to be performed when the batch action is selected. It can be a URL or a path
+- `method`: the HTTP method to be used when performing the action, such as `:delete`
+
+The `batch_actions` method is called in the context of the controller, so you can use any controller method or helper to build the batch actions.
+
+Batch actions will be submitted to the specified action with an `id` parameter containing the IDs of the selected records. Using `id` as the
+parameter name allows the same action to support both batch and single-record actions for standard routes.
+
+E.g.
+
+```ruby
+# in the component
+def batch_actions
+  [
+    {
+      label: "Delete",
+      icon: "trash",
+      action: solidus_admin.delete_admin_users_path,
+      method: :delete
+    }
+  ]
+end
+```
+
+```ruby
+# in the controller
+def delete
+  @users = Spree.user_class.where(id: params[:id])
+  @users.destroy_all
+  flash[:success] = "Admin users deleted"
+  redirect_to solidus_admin.users_path, status: :see_other
+end
+```
+
+## Search Scopes
+
+Search scopes are used to filter the records displayed on the index page. The index page internally uses the `ui/table` component and relies on the `scopes` method to render the search scope buttons.
+
+In the component, search scopes are provided as an array of hashes, with each hash representing a single search scope. Each hash must contain the following keys:
+
+- `label`: the name of the search scope, used as the label of the button
+- `name`: the name of the search scope, sent via `q[scope]` parameter when the button is clicked
+- `default`: whether this is the default search scope, used to highlight the button when when the page is loaded
+
+On the controller side, search scopes can be defined with the `search_scope` helper, provided by `SolidusAdmin::ControllerHelpers::Search`. This helper takes a name, an optional `default` keyword argument, and a block. The block will be called with the current scope and should return a new ActiveRecord scope.
+E.g.
+
+```ruby
+module SolidusAdmin
+  class UsersController < SolidusAdmin::BaseController
+    include SolidusAdmin::ControllerHelpers::Search
+
+    search_scope(:customers, default: true) { _1.left_outer_joins(:role_users).where(role_users: { id: nil }) }
+    search_scope(:admin) { _1.joins(:role_users).distinct }
+    search_scope(:with_orders) { _1.joins(:orders).distinct }
+    search_scope(:without_orders) { _1.left_outer_joins(:orders).where(orders: { id: nil }) }
+    search_scope(:all)
+
+    def index
+      users = apply_search_to(Spree.user_class.order(id: :desc), param: :q)
+      # ...
+```
+
+## Filters
+
+Filters are used to narrow down the records displayed on the index page. The index page internally uses the `ui/table/ransack_filter` component and depends on the `filters` method to render the filters dropdown.
+
+In the component, filters are represented as an array of hashes, with each hash representing a single filter. Each hash must contain the following keys:
+
+
+- `label`: the name of the filter, used as the label in the filter bar
+- `attribute`: the name of the ransack-enabled attribute to be filtered
+- `predicate`: the name of the ransack predicate to be used, e.g. `eq`, `in`, `cont`
+- `options`: an array of options to be used for the filter, in the standard rails form of `[["label", "value"], ...]`
+
+On the controller side it's enough to add ransack support to the index action by including `SolidusAdmin::ControllerHelpers::Search` and calling
+`apply_search_to` as explained in the [Index action](#index-action) section.
+
+On the controller side, you simply need to add Ransack support to the index action by including the `SolidusAdmin::ControllerHelpers::Search` module and calling the `apply_search_to` method, as explained in the [Index action](#index-action) section.

data/docs/{customizing_menu_items.md → menu_items.md}

@@ -1,4 +1,4 @@
-# Customizing the main navigation
+# Customizing the Menu
 
 You are allowed to add your custom links to the main navigation. To do so, you can access `SolidusAdmin::Config.menu_items` in an initializer: