# Variant-aware catalog filter contract

Fictional Harbor Merchandise catalog. Rule version `variant-filters-v1`; six products, twelve variants, two products per page. This is a local matching exercise, not a live stock, order, or payment system.

## Match one row, then count products

- Within a dimension, selected values use **OR**: S or M.
- Across dimensions, use **AND on one variant**: category, size, color, and declared availability must all match that same row.
- An empty dimension is unrestricted. Selecting every value is equivalent for matching, though the applied filters still show your explicit selections.
- Available, Unavailable, and Unknown are three separate values. Unknown does not qualify for Available-only or Unavailable-only.
- Count stable product IDs once, even if several variants pass. Product names are not IDs.
- Sort products by name, then product ID. Show two products per page. Variant explanations sort by variant ID.
- A filter change or removed filter resets to page 1. A zero result retains the filters and explains how to remove one or reset; it does not substitute popular products.

Download the [source variant rows](catalog-variants.csv) and [complete 4,096-case answer matrix](catalog-answer-cases.csv). Empty filter cells in the answer matrix mean unrestricted; semicolons separate OR values or matching IDs. A blank result-ID cell with count 0 means no match. Case IDs are stable within this fixture version.

## Cases worth testing

| Filters | Expected products | Matching variants | Why |
| --- | --- | --- | --- |
| None | P05 P04 P01 P03 P02 P06 | All 12 | Six distinct products, three pages |
| Hoodies + S + Green + Available | None | None | P01 has S/Navy and M/Green; neither is S/Green |
| Hoodies + S-or-M + Green + Available | P01 | V02 | Adding M admits the single M/Green variant |
| Tees + S-or-M + Green + Available | P02 | V03 V04 | Two matching variants still produce one product card |
| Unknown availability only | P04 P03 | V08 V05 | Unknown stays separate; product name determines display order |
| Available only | P05 P04 P01 P02 P06 | V09 V07 V01 V02 V03 V04 V12 | Five products from seven matching variants |
| Tees, all other groups empty | P02 P06 | V03 V04 V11 V12 | Both are named Trail tee, but their IDs remain separate |

On baseline page 3, the two displayed products are P02 and P06. Select S + Green + Available: return to page 1 with P02 only. The page's visible card count must not replace the full matching-product count.

For the zero-result hoodie case, remove Size S: P01 returns through V02. The aid moves keyboard focus back to the Size S control when its filter chip is removed.

## Reproduce the answer space

Each of the four dimensions has three values, hence eight possible selected subsets including empty: **8×8×8×8 = 4,096** combinations. The complete answer table identifies matching product and variant IDs plus each page. It is an exhaustive check of this fixed fixture, not evidence that a real catalog has correct stock or checkout behavior.

## Your own filter contract

| Decision | Your rule and evidence |
| --- | --- |
| Product ID and variant ID | |
| Dimension values, including unknowns | |
| One real same-variant counterexample | |
| Empty-group, OR and AND rules | |
| Distinct result count and stable ordering | |
| Page size and filter-change behavior | |
| Zero-result and remove-one recovery | |
| How and when availability is verified | |
| Actual keyboard/mobile/download test | Not tested |

Keep sample school branding, contact details, proceeds claims, and other template marketing separate from your own verified merchandise offer. Test stock, orders, payments, and fulfillment separately before making those promises.