# Argument Modes

> Exact behavior of default, meta, taxonomy, date, ACF relationship, query bundle, and mapped bundle modes.

<!-- Sources: src/Components/Facets/Shared/FacetQueryProperties.php; src/Components/Facets/Shared/FacetQueryBlockVariants.php; src/Components/Facets/SearchFacet/SearchFacet.php; src/Facets/FacetBlockInterceptor.php; src/Facets/FacetClauseCanonicalizer.php; client/src/domains/facets/service/facet-query-mappings.ts; tests/e2e/components/facets/wp-query-args.spec.ts; tests/e2e/components/facets/taxonomy-query.spec.ts; tests/e2e/components/facets/meta-query-variants.spec.ts; tests/e2e/components/facets/date-query.spec.ts -->

# Argument Modes

Argument mode decides what a facet value becomes in the backend query. Select, SearchSelect, Radio List, and Checkbox List share the `FacetQueryProperties` mode system. Search Facet implements the same mode names separately because text search needs partial-match aliases and multi-argument text bundling.

## Mode Summary

| Mode | Runtime facet type | Used by | Value meaning |
| --- | --- | --- | --- |
| `default` | selected query argument, such as `category_name` or `post_type` | Search and option facets | The value is assigned to a standard WP query argument. |
| `meta` | `meta_value` | Search and option facets | The value is compared against a configured post meta key. |
| `tax` | `tax_query` for option facets, `tax_query_like` for Search Facet | Search and option facets | The value is interpreted as a term field for a configured taxonomy. |
| `date` | `date_query` | Search and option facets | The value is interpreted as a date range for a configured post date column. |
| `acf_relationship` | `acf_relationship` | Search and option facets | The value is a related post ID, or comma-separated IDs, matched against a serialized relationship meta field. |
| multi-argument Search Facet | `query_bundle` | Search Facet only | One typed text value expands into multiple query clauses. |
| multi-argument option facet | `mapped_bundle` | Select, SearchSelect, Radio List, Checkbox List | One authored option expands into multiple query clauses with per-option mapped values. |

## Default Query Argument

Default mode writes a standard query argument.

Option facets use values from `FacetQueryProperties`, including:

```text
search, p, name, title, post_type, order, orderby, category_name, tag, author, author_name, year, monthnum, posts_per_page
```

Search Facet has a filter-oriented set and uses partial aliases for text fields:

```text
search, p, title_like, name_like, post_type, category_name_like, tag_like, author, author_name_like, year, monthnum
```

Use default mode for common query arguments like post type, category slug, tag slug, author, year, month, ordering, and posts per page.

## Meta Argument

Meta mode uses:

- `meta_key`
- `meta_compare`
- `meta_type`

Option facets default `meta_compare` to `=`, while Search Facet defaults it to `LIKE`. Supported compares are:

```text
=, !=, >, >=, <, <=, LIKE, NOT LIKE, IN, NOT IN, BETWEEN, NOT BETWEEN, EXISTS, NOT EXISTS
```

Use comma-separated values for `IN`, `NOT IN`, `BETWEEN`, and `NOT BETWEEN`. E2E coverage verifies exact numeric matches, char matches, bool matches, range compares, substring compares, set compares, and values with spaces.

## Taxonomy Argument

Tax mode uses:

- `taxonomy`
- `tax_field`

Supported fields are:

```text
slug, term_id, name, term_taxonomy_id
```

Option facets produce exact `tax_query` clauses. Search Facet produces `tax_query_like`, so it can search term names or slugs by typed text where supported by the backend clause handling.

The taxonomy E2E scenario verifies `facet_color` with all four fields and also covers multiple taxonomy filters.

## Date Query

Date mode uses a configured date column:

```text
post_date, post_modified, post_date_gmt, post_modified_gmt
```

Authored option values should use:

```text
YYYY-MM-DD,YYYY-MM-DD
```

The first date is the start, and the second is the end. Search Facet sends the typed input through the same `date_query` facet type.

## ACF Relationship

ACF relationship mode uses `acf_relationship_argument.meta_key`, which is the relationship field stored on the posts being filtered.

The value must be a numeric related post ID, or a comma-separated list of related post IDs. It does not reverse-resolve a bidirectional relationship stored only on the related posts.

Example rule:

```text
If you filter Events by Speaker, the Event posts must store the selected Speaker IDs in the configured relationship field.
```

The `wp_query_args` E2E scenario verifies select and checkbox ACF relationship filters, counts, unavailable state, comma-list option values, and direct URL hydration.

## Search Facet Query Bundle

When `target_multiple_query_arguments` is enabled on Search Facet, the control renders as `query_bundle`.

One typed search value is applied to every row in `query_argument_mappings`. The `query_argument_relation` setting controls whether the generated clauses are joined with `AND` or `OR`. Search mappings normalize common exact types to partial search aliases, for example `title` becomes `title_like` and `category_name` becomes `category_name_like`.

Use this when one text field should search several places, such as title or priority, or title or category.

## Option Facet Mapped Bundle

When `target_multiple_query_arguments` is enabled on Select, SearchSelect, Radio List, or Checkbox List, the root facet type becomes `mapped_bundle`.

The parent facet defines `query_argument_mappings`. Each option defines `query_value_mappings`. At runtime, an option is valid only when its value mappings can be matched to the parent mapping keys.

Example:

```text
Parent mappings:
- category -> default category_name
- priority -> meta facet_priority

Option "News + High priority":
- category = facets-e2e-news
- priority = high
```

The mapped bundle E2E coverage verifies filtering, URL restore, counts, unavailable state, and availability updates after other filters change.
