Merge branch 'main' of github.com:avo-hq/docs.avohq.io

docs/3.0/basic-filters.md

@@ -90,7 +90,7 @@ end
 
 ## Filter types
 
-Avo has several types of filters available [Boolean filter](#boolean_filter), [Select filter](#select_filter), [Multiple select filter](#multiple_select_filter) and [Text filter](#text_filter).
+Avo has several types of filters available [Boolean filter](#Boolean%20Filter), [Select filter](#Select%20Filter), [Multiple select filter](#Multiple%20select%20filter), [Text filter](#Text%20Filter) and since version <Version version="3.11.8" /> [Date time filter](#Date%20time%20Filter).
 
 <Image src="/assets/img/filters.png" width="404" height="727" alt="Avo filters" />
 
@@ -377,6 +377,130 @@ end
 ```
 </Option>
 
+<Option name="Date time Filter">
+<VersionReq version="3.11.8" />
+
+The ideal filter for date selection. This filter allows you to generate a date input, with options to include time selection and even a range selection mode. Customizable to suit your specific needs.
+
+:::warning Timezone Handling
+This filter sends the selected value exactly as selected, without any timezone adjustments. If you need to apply timezone conversion or adjustments, please ensure to handle it during the [`apply`](#apply) method.
+:::
+
+Generate one by using:
+```bash
+rails generate avo:filter created_at --type date_time
+```
+
+The generated file should be following a similar format:
+```ruby
+# frozen_string_literal: true
+
+class Avo::Filters::CreatedAt < Avo::Filters::DateTimeFilter
+  self.name = "Created at"
+  # self.type = :date_time
+  # self.mode = :range
+  # self.visible = -> do
+  #   true
+  # end
+
+  def apply(request, query, value)
+    query
+  end
+
+  # def format
+  #   case type
+  #   when :date_time
+  #     'yyyy-LL-dd TT'
+  #   when :date
+  #     'yyyy-LL-dd'
+  #   end
+  # end
+
+  # def picker_format
+  #   case type
+  #   when :date_time
+  #     'Y-m-d H:i:S'
+  #   when :time
+  #     'Y-m-d'
+  #   end
+  # end
+end
+
+```
+
+### Type
+Determines the format of the input field.
+
+##### Default value
+
+`:date_time`
+
+By default, the input allows users to select both a date and a time.
+
+##### Possible values
+
+- `:date`
+  - This option restricts the input to date selection only, ideal for scenarios where time input is unnecessary.
+  <Image src="/assets/img/date_type.png" class="mt-2" width="385" height="377" alt="Avo date time filter date type" />
+
+- `:time`
+  - This option limits the input to time selection only, suitable to apply where only the time is relevant.
+  <Image src="/assets/img/time_type.png" class="mt-2" width="385" height="50" alt="Avo date time filter time type" />
+
+- `:date_time`
+  - This combined option enables both date and time selection, providing a comprehensive input for more detailed needs.
+  <Image src="/assets/img/date_time_type.png" class="mt-2" width="385" height="427" alt="Avo date time filter date_time type" />
+
+### Mode
+Defines whether the input allows selection of a single date or a range of dates.
+
+##### Default value
+
+`:range`
+
+By default, the input permits users to select a range of dates, ideal for scenarios such as booking periods or event durations.
+
+##### Possible values
+- `:range`
+  - Allows users to choose a start and end date, making it suitable for applications that require a time span, such as reservations or scheduling.
+  <Image src="/assets/img/range_mode.png" class="mt-2" width="385" height="377" alt="Avo date time filter range mode" />
+  :::info
+  In `:range` mode the `value` will be formatted as `"2024-08-13 to 2024-08-16"`.
+
+  To separate the start and end dates, use `date_1, date_2 = value.split(" to ")`, which will split the value into `["2024-08-13", "2024-08-16"]`
+  :::
+
+- `:single`
+  - Limits the selection to a single date, perfect for use cases where only one specific day needs to be selected, such as an appointment or event date.
+  <Image src="/assets/img/single_mode.png" class="mt-2" width="385" height="370" alt="Avo date time filter single mode" />
+
+### `picker_options`
+
+This filter uses [flatpickr](https://flatpickr.js.org) as the date and time picker. If you wish to customize the picker’s options, you can do so by overriding the [`picker_options(value)`](https://github.com/avo-hq/avo/blob/menu/lib/avo/filters/date_time_filter.rb#L22) method. You can merge your custom options with those provided by [flatpickr](https://flatpickr.js.org), which are detailed [here](https://flatpickr.js.org/options/).
+
+```ruby{10-14}
+# frozen_string_literal: true
+
+class Avo::Filters::StartingAt < Avo::Filters::DateTimeFilter
+  self.name = "The starting at filter"
+  self.button_label = "Filter by start time"
+  self.empty_message = "Search by start time"
+  self.type = :time
+  self.mode = :single
+
+  def picker_options(value)
+    super.merge({
+      minuteIncrement: 3
+    })
+  end
+
+  def apply(request, query, value)
+    query.where("to_char(starting_at, 'HH24:MI:SS') = ?", value)
+  end
+end
+```
+</Option>
+
 ## Dynamic filter options
 
 <DemoVideo demo-video="https://youtu.be/M2RsNPPFOio" />

docs/3.0/dynamic-filters.md

@@ -477,6 +477,10 @@ Suggestions work on filters that provide text input, enhancing the user experien
 
 `nil`
 
+:::info
+<VersionReq version="3.11.8" /> on `tags` fields the `suggestions` are fetched from the field.
+:::
+
 #### Possible values
 
 - Array of strings
@@ -510,6 +514,77 @@ field :first_name,
 dynamic_filter :first_name,
   suggestions: -> { ["Avo", "Cado", params[:extra_suggestion]] }
 ```
+
+
+- Array of hashes with the keys `value`, `label` and optionally an `avatar`
+<VersionReq version="3.11.8" />
+:::warning Applicable only to filters with type tags.
+:::
+
+:::code-group
+```ruby {6-13,19-26} [Direct assign]
+# Using field's filterable option
+field :tags,
+  as: :tags,
+  filterable: {
+    # ...
+    suggestions: [
+      {
+        value: 1,
+        label: 'one',
+        avatar: 'https://images.unsplash.com/photo-1560363199-a1264d4ea5fc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop',
+      },
+      # ...
+    ]
+    # ...
+  }
+
+# Using dynamic_filter method
+dynamic_filter :tags,
+  suggestions: [
+    {
+      value: 1,
+      label: 'one',
+      avatar: 'https://images.unsplash.com/photo-1560363199-a1264d4ea5fc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop',
+    },
+    # ...
+  ]
+```
+
+```ruby {6-15,21-30} [Proc]
+# Using field's filterable option
+field :tags,
+  as: :tags,
+  filterable: {
+    # ...
+    suggestions: -> {
+      [
+        {
+          value: 1,
+          label: 'one', # or params[:something]
+          avatar: 'https://images.unsplash.com/photo-1560363199-a1264d4ea5fc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop',
+        },
+        # ...
+      ]
+    }
+    # ...
+  }
+
+# Using dynamic_filter method
+dynamic_filter :tags,
+  suggestions: -> {
+    [
+      {
+        value: 1,
+        label: 'one', # or params[:something]
+        avatar: 'https://images.unsplash.com/photo-1560363199-a1264d4ea5fc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&w=256&h=256&fit=crop',
+      },
+      # ...
+    ]
+  }
+```
+:::
+
 </Option>
 
 <Option name="`options`">

docs/3.0/fields/tags.md

@@ -19,6 +19,8 @@ field :skills, as: :tags
 <Option name="`suggestions`">
 
 :::warning
+**This warning no longer applies** <VersionReq version="3.11.8" />
+
 If you're using this field as `filterable`, dynamic filters are not yet picking these suggestions.
 
 Please use the custom dynamic filters [suggestions](../dynamic-filters#suggestions) option to specify filter suggestions.

docs/3.0/testing.md

@@ -42,7 +42,7 @@ end
 ```ruby
 require 'rails_helper'
 
-RSpec.feature ReleaseFish, type: :feature do
+RSpec.feature Avo::Actions::ReleaseFish, type: :feature do
   let(:fish) { create :fish }
   let(:current_user) { create :user }
   let(:resource) { Avo::Resources::User.new.hydrate model: fish }
@@ -54,7 +54,7 @@ RSpec.feature ReleaseFish, type: :feature do
       },
       current_user: current_user,
       resource: resource,
-      records: [fish]
+      query: [fish]
     }
 
     action = described_class.new(resource: resource, user: current_user, view: :edit)