@adyen/bento-mcp 0.0.0 → 0.1.0

package/dist/assets/components/filter-bar/filter-bar.docs.mdx

@@ -0,0 +1,1005 @@
+import { Canvas, Story, Meta, Source } from '@storybook/blocks';
+import * as FilterBarStories from './filter-bar.stories';
+import FilterBarConfigFilterValuesExample from './__tests__/filter-bar-config-filter-values-example.vue?raw';
+import FilterBarConfigFilterValuesObjectExample from './__tests__/filter-bar-config-filter-values-object-example.vue?raw';
+
+<Meta title="Filter bar" name="Filter bar" of={FilterBarStories} />
+
+# Filter Bar
+
+<Canvas withSource="closed">
+    <Story of={FilterBarStories.Default} />
+</Canvas>
+
+Filter bar allows users to filter the content so that only the information they're interested in is displayed.
+
+## Table of contents
+
+- [Filter Bar](#filter-bar)
+    - [Table of contents](#table-of-contents)
+    - [Behavior](#behavior)
+    - [Search bar](#search-bar)
+    - [Filter configuration and Filter values](#filter-configuration-and-filter-values)
+        - [Applying a filter](#applying-a-filter)
+        - [Clearing a filter](#clearing-a-filter)
+        - [Clear all](#clear-all)
+    - [Persistent filters](#persistent-filters)
+        - [Resetting a filter](#resetting-a-filter)
+        - [Reset all](#reset-all)
+    - [Use Cases](#use-cases)
+        - [Do not use](#do-not-use)
+    - [Variations](#variations)
+        - [Available filter configurations](#available-filter-configurations)
+        - [Input filter](#input-filter)
+            - [Options](#options)
+            - [Configuration Interface](#configuration-interface)
+        - [Input with dropdown filter](#input-with-dropdown-filter)
+            - [Options](#options-1)
+            - [Configuration Interface](#configuration-interface-1)
+            - [Value Interface](#value-interface)
+        - [Range filter](#range-filter)
+            - [Configuration Interface](#configuration-interface-2)
+            - [Value Interface](#value-interface-1)
+        - [~~Boolean filter~~ (`DEPRECATED`)](#boolean-filter-deprecated)
+            - [Configuration Interface](#configuration-interface-3)
+            - [Filter value Interface](#filter-value-interface)
+            - [Custom boolean options](#custom-boolean-options)
+        - [Select filter](#select-filter)
+            - [Options](#options-2)
+            - [Configuration Interface](#configuration-interface-4)
+            - [Value Interface](#value-interface-2)
+            - [External filtering](#external-filtering)
+            - [External filtering and Lazy Loading simultaneously](#external-filtering-and-lazy-loading-simultaneously)
+            - [Nested multi-select filter](#nested-multi-select-filter)
+        - [Date filter](#date-filter)
+            - [Options](#options-3)
+            - [Configuration Interface](#configuration-interface-5)
+            - [Value Interface](#value-interface-3)
+        - [Date range filter](#date-range-filter)
+            - [Options](#options-4)
+            - [Configuration Interface](#configuration-interface-6)
+            - [Value Interface](#value-interface-4)
+        - [Radio group filter](#radio-group-filter)
+            - [Configuration Interface](#configuration-interface-7)
+        - [Checkbox group filter](#checkbox-group-filter)
+            - [Options](#options-5)
+            - [Configuration Interface](#configuration-interface-7)
+            - [Value Interface](#value-interface-5)
+    - [Custom filters](#custom-filters)
+        - [Creating a custom filter](#creating-a-custom-filter)
+            - [Custom filter component](#custom-filter-component)
+            - [Connecting internal values and events](#connecting-internal-values-and-events)
+        - [Configure fields in `bento-filter-bar`](#configure-fields-in-bento-filter-bar)
+    - [Responsiveness](#responsiveness)
+    - [Accessibility 🚧](#accessibility-)
+        - [Roles, States, and Properties](#roles-states-and-properties)
+
+## Behavior
+
+By default filter bar displays the most common filters for that particular page/component.
+
+Pressing the filter button opens a popover where a filter can be applied. Only one filter can be opened at a time.
+
+## Search bar
+
+The search bar allows general filtering of the data by adding a `bento-search-bar` to the `bento-filter-bar`.
+
+> Important!
+>
+> `searchTerm` needs to be `''` (at minimum) to be able to display the search bar
+
+Properties:
+
+| Available props |                                                      |
+| --------------- | ---------------------------------------------------- |
+| `search`        | Allows to set properties to the search bar.          |
+| `searchTerm`    | Set the value of the search bar. Works with `.sync`. |
+
+<Source
+    format={'html'}
+    code={`
+<template>
+    <bento-filter-bar
+        :search-term.sync="searchTerm"
+        :search="searchProps"
+        @search-input="onSearchUpdate"
+        @update:search-term="onSearchUpdate"
+    />
+</template>
+<script setup lang="ts">
+    import {
+        BentoFilterBar,
+        BentoFilterBarSearchBarProps,
+        BentoFilterBarSearchTerm,
+    } from '@adyen/bento-vue2'
+    const searchTerm = ref<BentoFilterBarSearchTerm>('');
+    const searchProps: BentoFilterBarSearchBarProps = {
+        inputFieldAriaLabel: 'Input field aria label description',
+        debounceTime: 500,
+        hint: 'Hint',
+        placeholder: 'Placeholder content',
+    }
+    const onSearchUpdate = (newTerm: string) => {
+        // ...
+    }
+</script>
+`}
+/>
+
+## Filter configuration and Filter values
+
+The `BentoFilterBar` allows you to separate its configuration from its values. Use the `config` prop to define the
+filters' structure and appearance, and manage their state using either the `filterValues` (array) or
+`filterValuesObject` (object) props. When a filter's value is updated, the component emits `update:filter-values` or
+`update:filter-values-object` events. For convenience, you can use the `.sync` modifier (in Vue 2) or `v-model` (in
+Vue 3) to keep your local data synchronized.
+
+The `filterValues` prop uses an array of objects, which can be a bit verbose:
+
+<Source dark format={'html'} code={FilterBarConfigFilterValuesExample} />
+
+As an alternative, you can use the `filter-values-object` prop, which uses a simpler key-value object structure. This is
+often more convenient to work with.
+
+<Source dark format={'html'} code={FilterBarConfigFilterValuesObjectExample} />
+
+> **Note**
+>
+> If both `filterValues` and `filterValuesObject` are provided for the same filter field, `filterValuesObject` will take
+> precedence.
+
+### Applying a filter
+
+Selecting an option or typing the value and pressing the filter's "Apply" button closes the popover and applies the
+filter. When no changes have been made, the "Apply" button is disabled.
+
+Applying a filter triggers the `@update:filter-values` event, returning a new array of filter values
+(`BentoFilterValues`).
+
+### Clearing a filter
+
+Pressing the filter's "Clear" button clears the applied filter and closes the popover. If no filter is applied, the
+"Clear" button is disabled. This also applies when a user selects/types a filter, but hasn't applied it yet.
+
+Clearing a filter triggers the `@update:filter-values` event, returning a new array of filter values
+(`BentoFilterValues`).
+
+### Clear all
+
+Clearing all filters removes all the applied filters and shows a toast. If there are no filters applied, the "Clear all"
+button is hidden.
+
+Clearing all filters triggers the `@update:filter-values` event, returning a new array of filter values
+(`BentoFilterValues`).
+
+## Persistent filters
+
+<Canvas withSource="closed">
+    <Story of={FilterBarStories.Persistent} />
+</Canvas>
+
+Persistent filters are filters that cannot be fully cleared. For technical reasons (to limit the amount of data that
+needs to be fetched) some pages may have a persistent filter applied with a default value. The default value can be
+defined by teams implementing the filter using the `defaultValue` property on any filter.
+
+If no `value` is set for the filter the `defaultValue` will be used as the initial value.
+
+### Resetting a filter
+
+Pressing Reset button resets the applied persistent filter back to default value and closes the popover. If currently
+applied filter is the persistent filter's default value, Reset button should be disabled. This also applies when a user
+selects/types a new filter, but hasn't applied it yet.
+
+### Reset all
+
+Resetting/Clearing all filters removes (or resets, in case of persistent filters) all the applied filters and shows a
+toast.
+
+Note: When persistent filter is present, the button says "Reset all". When there are no persistent filters, the button
+says "Clear all".
+
+If there are no filters applied or when persistent filter values have not been changed, Reset all/Clear all button is
+hidden.
+
+## Use Cases
+
+Here are some examples:
+
+- Used in the data grid component to filter data sets. Accessible via the `filters` prop in the data grid.
+- Filtering a custom list of items.
+
+### Do not use
+
+Here are some some "don't dos":
+
+- Filtering a custom `table` of items. Please use the data grid.
+- Using the component inside of `header` slot of the data grid. Please use the `filter` component.
+
+## Variations
+
+### Available filter configurations
+
+- `BentoFilterItemType.INPUT`: Input filter
+- `BentoFilterItemType.INPUT_DROPDOWN`: Input with dropdown filter
+- ~~`BentoFilterItemType.BOOLEAN`~~ (DEPRECATED): Boolean (yes/no) filter
+- `BentoFilterItemType.RANGE`: Range (from/to) filter
+- `BentoFilterItemType.SELECT`: Select filter
+- `BentoFilterItemType.SELECT_AVATAR`: Avatar select filter
+- `BentoFilterItemType.SELECT_COUNTRY`: Country select filter
+- `BentoFilterItemType.SELECT_CURRENCY`: Currency select filter
+- `BentoFilterItemType.SELECT_PAYMENT_METHOD`: Payment method select filter
+- `BentoFilterItemType.SELECT_TAG`: Tag select filter
+- `BentoFilterItemType.DATE`: Single date filter
+- `BentoFilterItemType.DATE_RANGE`: Date range filter
+- `BentoFilterItemType.RADIO_GROUP`: Radio group filter
+- `BentoFilterItemType.CHECKBOX_GROUP`: Checkbox group filter
+
+### Input filter
+
+Single input field to filter by a string of text and/or numbers. Provided by the `BentoFilterItemType.INPUT` filter
+type.
+
+#### Options
+
+- `placeholder: string`: Sets a placeholder in the input field.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.INPUT;
+    value: string | null;
+    options: {
+        placeholder: string;
+    },
+    defaultValue: string | null;
+}
+```
+
+### Input with dropdown filter
+
+Single input field with a dropdown to filter by a string of text and/or numbers and a modifier added by the dropdown
+value. Provided by the `BentoFilterItemType.INPUT_DROPDOWN` filter type
+
+#### Options
+
+Currently the input with dropdown filter supports the following options:
+
+- `dropdown: BentoInputDropdownProps`: Here you can set the input field dropdown properties like `items` to populate the
+  inner dropdown.
+- `dropdownPosition?: 'start' | 'end'`: Allows you to set the position of the dropdown inside the input field to the
+  beginning or the end of the element.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.INPUT;
+    value: string | null;
+    defaultValue: string | null;
+    options: {
+        dropdown: BentoInputDropdownProps;
+        dropdownPosition?: 'start' | 'end';
+    };
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    inputValue: string;
+    dropdownValue: string:
+}
+```
+
+### Range filter
+
+Two input fields allowing the user to provide a range between 2 values. Provided by the `BentoFilterItemType.RANGE`
+filter type.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.RANGE;
+    defaultValue: string[] | null;
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: string[] | null;
+}
+```
+
+### ~~Boolean filter~~ (`DEPRECATED`)
+
+> Deprecated filter
+>
+> Use "`BentoFilterItemType.RADIO_GROUP`" instead. See the [Radio group filter](#radio-group-filter) documentation for
+> more details
+
+A 'yes' / 'no' filter allowing the user to choose between these 2 options. Provided by the
+~~`BentoFilterItemType.BOOLEAN`~~ filter type. By default, the options `yes` & `no` are displayed but they can be
+customized through the `options` property.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.BOOLEAN;
+    options: {
+        positiveOption: {
+            label: string;
+            value: string;
+        }
+        negativeOption: {
+            label: string;
+            value: string;
+        }
+    }
+    defaultValue: 'yes' | 'no' | null;
+}
+```
+
+#### Filter value Interface
+
+```typescript
+{
+    field: string;
+    value: 'yes' | 'no' | null;
+}
+```
+
+#### Custom boolean options
+
+Custom boolean options can be displayed instead of the default `yes` / `no`:
+
+```typescript
+
+<bento-filter-bar
+  :config="[{
+    field: 'my-boolean-filter',
+    label: 'Boolean',
+    type: BentoFilterItemType.BOOLEAN,
+    visible: true,
+    :options="{
+        positiveOption: {
+            value: 'first-option';
+            label: 'My first option';
+        }
+        negativeOption: {
+            value: 'second-option';
+            label: 'My second option';
+        }
+    }"
+  }]"
+  :filter-values="[{
+    field: 'my-boolean-filter',
+    value: 'second-option'
+  }]"
+/>
+```
+
+### Select filter
+
+Single input field to filter by a string of text and/or numbers. Provided by the `BentoFilterItemType.SELECT` filter
+type.
+
+#### Options
+
+- `dynamicFiltering?: boolean`: Enables the search bar on popovers and search behaviour on the "all filters" modal.
+  **Default** is `true`
+- `enableValueLabelPair?: boolean`: Enables value/label value handling. When `true`, the component expects and emits
+  value/label pair objects instead of primitive values. This affects both the `value` prop and the `input` event
+  payload.
+
+    - **Input (`value` prop):** Expects a `{ value: string | number, label: string }` object (or an array of them for
+      multi-select).
+    - **Output (`input` event):** Emits a `{ value: string | number, label: string }` object (or an array of them) upon
+      selection.
+
+    This is particularly useful when a selected item's label is not available in the `items` prop, allowing the
+    component to display the correct label for values loaded from external sources. Default is `false`.
+
+- `emptyState?: BentoListboxEmptyStateProps`: Empty state props that will be used with the inner empty state component
+  to be displayed when no search results are found.
+- `isOptionDisabled?: BentoListboxIsOptionDisabled`: A function that defines which option in the list-box is disabled.
+- `lazy?: object`:
+    - `hasMoreItems: boolean`: Indicates whether there are more items to load.
+    - `lazyLoadType: BentoListboxLazyLoadType | string`: The type of `Lazy Load`. Type "automatic" will enable infinite
+      scrolling. Type "button" will enable lazy loading with "Show more" button.
+    - `loading: boolean`: Indicates if new options are loading.
+    - `showMoreEvent?: () => void`: The click event that fires when the user press on the "show more" button OR when the
+      user scrolls down to bottom of the select filter box.
+- `listboxItems: BentoListboxOptions`: Option items for the list-box.
+- `loading?: boolean`: Toggles the loading state of the listbox.
+- `multiple?: boolean`: Defines if the list-box should be a multi-select filter.
+- `onOpen?: () => void`: This event fires when the dropdown is opened.
+- `search?: object`:
+    - `debounceTime?`: The debounce time for when the searchEvent is fired.
+    - `searchEvent`: The event that triggers upon user filtering the listbox items.
+- `staticCategories?: boolean`: Defines if the list-box should support static categories.
+- `tooltipPosition?: BentoTooltipPosition | string`: Position the tooltip should take if space is available.
+- `tooltipText?: string`: Attaches a `BentoTooltip` if present. Text showed in the tooltip on hover.
+- `virtualScroll?: BentoListboxVirtulisationOptions`: Enables virtual scrolling if set to true or by providing an object
+  with itemHeight function. The itemHeight function is used to calculate the height of rendered item given it's index.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.SELECT;
+    defaultValue: Array<string | number>;
+    options: {
+        dynamicFiltering?: boolean;
+        emptyState?: BentoListboxEmptyStateProps;
+        listboxItems: BentoListboxOptions;
+        multiple?: boolean;
+        onOpen?: () => void;
+        lazy?: {
+            hasMoreItems: boolean;
+            lazyLoadType: BentoListboxLazyLoadType | `${BentoListboxLazyLoadType}`;
+            loading: boolean;
+            showMoreEvent?: () => void;
+        };
+        loading?: boolean;
+        search?: BentoListboxSearchOptions;
+        staticCategories?: boolean;
+        isOptionDisabled?: BentoListboxIsOptionDisabled;
+        virtualScroll?: BentoListboxVirtulisationOptions;
+        tooltipText?: string;
+        tooltipPosition?: BentoTooltipPosition | `${BentoTooltipPosition}`;
+        enableValueLabelPair?: boolean;
+    };
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: Array<string | number>,
+}
+```
+
+#### External filtering
+
+<Canvas withSource="closed">
+    <Story of={FilterBarStories.ExternalFilteringSelectFilter} />
+</Canvas>
+
+To handle filtering via an external source, like an API, you can configure the select filter's `options` to manage the
+search event and loading state. This is ideal for large datasets where client-side filtering is not performant.
+
+Here's how to set it up:
+
+1.  **Implement the `searchEvent`**: Add a `search` object to your filter's `options`. The `searchEvent` function within
+    this object will be called whenever the user types in the search input. This is where you should trigger your API
+    call with the search term.
+
+2.  **Manage the loading state**: While your API is fetching the results, set the top-level `loading` property in
+    `options` to `true`. This will display a loading indicator over the list, providing visual feedback to the user.
+
+3.  **Update `listboxItems`**: Once the API call is complete, update the `listboxItems` array in your `options` with the
+    new data and set `loading` back to `false`.
+
+#### External filtering and Lazy Loading simultaneously
+
+<Canvas withSource="closed">
+    <Story of={FilterBarStories.ExternalFilteringAndLazyLoadingSelectFilter} />
+</Canvas>
+
+To implement a select filter that both searches a remote source and lazy-loads more results, you need to manage two
+separate loading states and handle two distinct events.
+
+**State Management**
+
+You'll need to maintain several state variables:
+
+- `listboxItems`: An array to hold the items currently displayed in the dropdown.
+- `isSearchLoading`: A boolean to indicate when a new search is being performed. This controls the main loading
+  indicator for the select filter.
+- `isLazyLoading`: A boolean for when more items are being fetched via scrolling. This controls the loading spinner at
+  the bottom of the list.
+- `hasMoreItems`: A boolean to know if the API has more items to provide.
+- `currentPage`: To keep track of the pagination for lazy loading.
+- `currentSearchTerm`: To store the current search query.
+
+**Event Handlers**
+
+1.  **`onSearch` function**: This function is triggered by the `search.searchEvent`. It should:
+    - Reset `currentPage` to `1`.
+    - Set `isSearchLoading` to `true`.
+    - Fetch the initial set of data from your API based on the new search term.
+    - Replace `listboxItems` with the new data.
+    - Update `hasMoreItems`.
+    - Set `isSearchLoading` to `false` when done.
+2.  **`onLazyLoad` function**: This function is triggered by `lazy.showMoreEvent`. It should:
+    - Check if a lazy load is already in progress or if there are no more items.
+    - Increment `currentPage`.
+    - Set `isLazyLoading` to `true`.
+    - Fetch the next page of data from your API.
+    - Append the new items to the existing `listboxItems`.
+    - Update `hasMoreItems`.
+    - Set `isLazyLoading` to `false` when done.
+
+**Configuration**
+
+In your filter configuration, you'll pass these states and handlers to the `options` of your select filter:
+
+- `options.loading` should be bound to `isSearchLoading`.
+- `options.search.searchEvent` should be your `onSearch` handler.
+- `options.lazy.loading` should be bound to `isLazyLoading`.
+- `options.lazy.showMoreEvent` should be your `onLazyLoad` handler.
+- `options.lazy.hasMoreItems` should be bound to `hasMoreItems`.
+
+#### Nested multi-select filter
+
+The Multi select can also be set up as a nested multi-select with the following settings:
+
+- `type`: `BentoFilterItemType.SELECT`
+- `options.multiple`: `true`
+- `options.listboxItems`: An array with the `Array<BentoListboxOptionItem>` type. For example:
+
+```tyepscript
+[
+    {
+        label: 'Belgium',
+        description: 'Country',
+        value: 'belgium',
+    },
+    {
+        label: 'Netherlands',
+        description: 'Country',
+        value: 'netherlands',
+        items: [
+            {
+                label: 'Amsterdam',
+                description: 'City',
+                value: 'amsterdam',
+            },
+            {
+                label: 'Den Haag',
+                description: 'City',
+                value: 'den-haag',
+            },
+        ],
+    },
+],
+```
+
+For more details see the `bento-dropdown` documentation.
+
+### Date filter
+
+#### Options
+
+- `firstDayOfWeek: BentoDatePickerFirstDayOfWeek`: Allows you to set the first day of the week: MONDAY, SUNDAY,
+  SATURDAY. (Default: MONDAY)
+- `isDateDisabled: (date: Date) => boolean`: Function that allows to disable individual dates
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.DATE;
+    options: {
+        firstDayOfWeek?: BentoDatePickerFirstDayOfWeek,
+        isDateDisabled?: (date: Date) => boolean,
+    },
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: Date;
+}
+```
+
+### Date range filter
+
+#### Options
+
+- `allowTimeInput: boolean`: Allows user to enter time values in the form
+- `firstDayOfWeek: BentoDatePickerFirstDayOfWeek`: Allows user to set the first day of the week: MONDAY, SUNDAY
+  SATURDAY. (Default: MONDAY)
+- `isDateDisabled: (date: Date) => boolean`: Function that allows to disable individual dates
+- `maxRange: number`: Set a maximum number of dates to be selectable by the range.
+- `numberOfMonths: number`: Number of months rendered in the filter
+- `quickSelectRanges`:
+  `Array<{ label: string, value: string, data: { startDate: Date, endDate?: Date, isRelativeToNow?: boolean } }>`: An
+  array of predefined date range options for the user to select. Please see more info
+  [here](../?path=/docs/components-date-picker-range-dates--docs#quick-select-ranges).
+- `showEndDateOnOpen: boolean`: Toggles whether the picker will open on the end date's month
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.DATE;
+    options: {
+        allowTimeInput?: boolean;
+        firstDayOfWeek?: BentoDatePickerFirstDayOfWeek;
+        isDateDisabled?: (date: Date) => boolean;
+        maxRange?: number;
+        numberOfMonths?: number;
+        quickSelectRanges: { label: string, value: string, data: { startDate: Date, endDate?: Date, isRelativeToNow?: boolean } }[];
+        showEndDateOnOpen?: boolean;
+    }; // i.e. BentoDateRangeFilterOptions
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: { startDate: Date, endDate: Date} // i.e. BentoDateRangeFilterValue
+}
+```
+
+### Checkbox group filter
+
+A filter that displays a group of checkboxes. Provided by the `BentoFilterItemType.CHECKBOX_GROUP` filter type.
+
+#### Options
+
+- `checkboxItems: BentoCheckboxGroupOption[]`: An array of objects to create the checkboxes. Each object must have a
+  `label` and `value` property.
+- `tooltipPosition?: BentoTooltipPosition | string`: Position the tooltip should take if space is available.
+- `tooltipText?: string`: Attaches a `BentoTooltip` if present. Text showed in the tooltip on hover.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.CHECKBOX_GROUP;
+    defaultValue?: Array<string | number  | null>;
+    options: {
+        checkboxItems: BentoCheckboxGroupItems;
+        tooltipText?: string;
+        tooltipPosition?: 'top' | 'bottom' | 'left' | 'right';
+    };
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: Array<string | number | null>;
+}
+```
+
+### Radio group filter
+
+- `items: BentoRadioGroupFilterValue`: Sets a placeholder in the input field.
+- `tooltipText?: string`: Attaches a `BentoTooltip` if present. Text showed in the tooltip on hover.
+- `tooltipPosition?: BentoTooltipPosition | string`: Position the tooltip should take if space is available.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.RADIO_GROUP;
+    defaultValue: BentoRadioGroupFilterValue;
+    value: BentoRadioGroupFilterValue;
+    options: {
+        items: BentoRadioGroupFilterValue;
+        tooltipText?: string;
+        tooltipPosition?: BentoTooltipPosition | `${BentoTooltipPosition}`;
+    }
+    visible: boolean;
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: Array<string | number>;
+}
+```
+
+### Toggle filter
+
+A 'true' / 'false' (on/off) filter allowing the user to choose between these 2 options. Provided by the
+`BentoFilterItemType.TOGGLE` filter type.
+
+#### Options
+
+- `tooltipPosition?: BentoTooltipPosition | string`: Position the tooltip should take if space is available.Expand
+  commentComment on line R660ResolvedCode has comments. Press enter to view.
+- `tooltipText?: string`: Attaches a `BentoTooltip` if present. Text showed in the tooltip on hover.
+
+#### Configuration Interface
+
+```typescript
+{
+    field: string;
+    label: string;
+    type: BentoFilterItemType.TOGGLE;
+    options: {
+        description?: string
+        tooltipText?: string;
+        tooltipPosition?: BentoTooltipPosition | `${BentoTooltipPosition}`;
+    };
+}
+```
+
+#### Value Interface
+
+```typescript
+{
+    field: string;
+    value: boolean; // i.e. BentoToggleFilterValue
+}
+```
+
+## Custom filters
+
+Custom filters are supported through the use of the `config` prop and the values settings `filter-values-object`.
+
+> All custom filters must implement the `bento-base-filter` component and it's recommended to use the
+> `useBentoBaseFilter` composable to easily wire and control the events and buttons of the filter.
+
+By setting a custom filter with these properties and components we ensure the correct functioning of the `reset`
+(persistent filters) & `clear` (non-persistent filters) events alongside with the correct integration with the
+`All filters` modal.
+
+<Canvas withSource="closed">
+    <Story of={FilterBarStories.CustomFilters} />
+</Canvas>
+
+### Creating a custom filter
+
+For a detail usage of the `bento-base-filter`
+[see the documentation](../?path=/docs/components-filter-bar-base-filters--docs).
+
+#### Custom filter component
+
+Every custom filter must:
+
+- Use the `bento-base-filter` component.
+- Define the events from the `BentoBaseFilterEvents` interface.
+- Define properties from the `BentoBaseFilterProps` interface.
+
+With types:
+
+<Source
+    format={'html'}
+    dark
+    code={`
+<template>
+    <bento-base-filter
+        :label="label"
+        :field="field"
+        :disabled="disabled"
+        :only-slot="onlySlot"
+        class="my-custom-filter"
+    >
+        <!-- your filter here -->
+    </bento-base-filter>
+</template>
+<script setup lang="ts">
+    import {
+        BentoBaseFilter
+        type BentoBaseFilterEvents,
+        type BentoBaseFilterProps
+    } from '@adyen/bento-vue2'
+    // Value and Options type definitions
+    type FilterValue = string;
+    interface FilterOptions {};
+    type CustomFilterProps = BentoBaseFilterProps<FilterValue, FilterOptions>
+    // Define emits
+    const emit = defineEmits<BentoBaseFilterEvents<CustomFilterProps>>();
+    // Define props
+    const props = withDefaults(defineProps<CustomFilterProps>(), {
+        defaultValue: null,
+    });
+</script>
+<style lang="scss" scoped>
+    /* The styles must be provided by the implementer. */
+    .my-custom-filter {
+        /* Use --b-spacer-070 when the padding is needed */
+        padding: var(--b-spacer-070);
+    }
+</style>
+    `}
+/>
+
+Without types:
+
+<Source
+    format={'html'}
+    dark
+    code={`
+<template>
+    <bento-base-filter
+        :label="label"
+        :field="field"
+        :disabled="disabled"
+        :only-slot="onlySlot"
+        class="my-custom-filter"
+    >
+        <!-- your filter here -->
+    </bento-base-filter>
+</template>
+<script setup lang="ts">
+    import {
+        BentoBaseFilter
+        BentoBaseFilterEvents,
+        BentoBaseFilterProps
+    } from '@adyen/bento-vue2'
+    // Define emits
+    const emit = defineEmits(BentoBaseFilterEvents);
+    // Define props
+    const props = defineProps(BentoBaseFilterProps);
+</script>
+<style lang="scss" scoped>
+    /* The styles must be provided by the implementer. */
+    .my-custom-filter {
+        /* Use --b-spacer-070 when the padding is needed */
+        padding: var(--b-spacer-070);
+    }
+</style>
+    `}
+
+/>
+
+#### Connecting internal values and events
+
+- Connect button events
+- Events provided by `useBentoBaseFilter` receive a callback that allows intercepting the events
+- `buttonSecondaryLabel` use on _Single value_ filters, indicate the state of the filter
+- `appliedFiltersCount` use on _Multi value_ filters, indicates how many values of the filter have been applied
+
+<Source
+    format={'html'}
+    dark
+    code={`
+<template>
+    <bento-base-filter
+        :label="label"
+        :field="field"
+        :disabled="disabled"
+        :only-slot="onlySlot"
+        :applied-filters-count="appliedFiltersCount"
+        :button-secondary-label="buttonSecondaryLabel"
+        :disable-apply-button="isApplyButtonDisabled"
+        :disable-secondary-button="isSecondaryButtonDisabled"
+        @apply="updateFilter"
+        @clear="clearFilter(updateFilter)"
+        @open="openFilter"
+        @reset="resetFilter(updateFilter)"
+    >
+        <!-- v-model binding-->
+        <input v-model="internalFilterValue" @input="onValueChanged">
+    </bento-base-filter>
+</template>
+<script setup lang="ts">
+    import {
+        // ...
+        useBentoBaseFilter
+    } from '@adyen/bento-vue2'
+    type FilterValue = string;
+    const {
+        // Fields
+        internalFilterValue, isSecondaryButtonDisabled, isApplyButtonDisabled,
+        // Methods
+        clearFilter, openFilter, resetFilter
+    } = useBentoBaseFilter<FilterValue>(
+        toRef(props, 'value'),
+        toRef(props, 'defaultValue')
+    );
+    const appliedFiltersCount = ref();
+    const buttonSecondaryLabel = computed(() => (/* Content depends on "internalFilterValue" */));
+    function updateFilter() {
+        appliedFiltersCount.value = 12; // Depends on "internalFilterValue"
+        /* Both events must be emitted */
+        emit('input', { ...props, value: internalFilterValue.value });
+        emit('update', { ...props, value: internalFilterValue.value });
+    }
+    function onValueChanged() {
+        /* Must be emitted to update the "All filters" modal before applying */
+        emit('input', { ...props, value: internalFilterValue.value });
+    }
+</script>
+    `}
+/>
+
+### Configure fields in `bento-filter-bar`
+
+- Pass the _custom filter_ as `type` inside the `config` property
+- Define the filter value `filter-values-object`
+- Extend from `BentoFilterBarValue` if there are filters provided by Bento
+
+<Source
+    format={'html'}
+    dark
+    code={`
+<template>
+    <bento-filter-bar
+        :config="filtersConfig"
+        :filter-values-object="filterValues"
+        @update:filter-values-object="filterValuesChanged"
+    />
+</template>
+<script setup lang="ts">
+    import {
+        BentoFilterBar,
+        type BentoFilterBarModel,
+        type BentoFilterBarValue,
+        type BentoFilterValueObject,
+    } from '@adyen/bento-vue2';
+    import {
+        CustomFilter,
+        FilterValue,
+        FilterOptions,
+    } from './custom-filter'
+    const filtersConfig = ref<BentoFilterBarModel<FilterOptions>>([
+        // ...Other filter definitions
+        {
+            field: 'custom-filter',
+            label: 'Custom filter',
+            type: CustomFilter,
+            visible: true,
+        },
+    ])
+    type FilterKeys = 'custom-filter';
+    type CustomFilterValues = BentoFilterBarValue | FilterValue; // Extend BentoFilterBarValue
+    const filterValues = ref<BentoFilterValueObject<FilterKeys, CustomFilterValues>>({
+        'custom-filter': undefined,
+    });
+    function filterValuesChanged(newFilterValues: BentoFilterValueObject<FilterKeys, CustomFilterValues>) {
+        filterValues.value = newFilterValues;
+    }
+</script>
+    `}
+/>
+
+## Responsiveness
+
+The `bento-filter-var` component uses
+[container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries) to adapt its
+styles responsively based on the size of its container.
+
+If you want to place this component in a flexbox, you should set `flex: 1` to the filter bar in your css in order for
+the container query to work correctly.
+
+## Accessibility 🚧
+
+### Roles, States, and Properties
+
+The full accessibility implementation for this component is still under development, so changes to this section are to
+be expected. However, as for all the other `bento` components we are adhering to
+[WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/) standard.