Add field->Boost mapping + data-layer spec README for dw-boost-filter-topbar

3ebc8cd96aacad3e22eb2fbaf3d514ada2e8f00e · 2026-06-25 16:06:32 -0700 · Steve Abrams
Files touched

A shopify/sections/dw-boost-filter-topbar.README.md
Diff

commit 3ebc8cd96aacad3e22eb2fbaf3d514ada2e8f00e
Author: Steve Abrams <steve@designerwallcoverings.com>
Date:   Thu Jun 25 16:06:32 2026 -0700

    Add field->Boost mapping + data-layer spec README for dw-boost-filter-topbar
---
 shopify/sections/dw-boost-filter-topbar.README.md | 103 ++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/shopify/sections/dw-boost-filter-topbar.README.md b/shopify/sections/dw-boost-filter-topbar.README.md
new file mode 100644
index 00000000..359cb021
--- /dev/null
+++ b/shopify/sections/dw-boost-filter-topbar.README.md
@@ -0,0 +1,103 @@
+# DW Boost Filter Topbar — field → Boost mapping + data-layer spec
+
+**Section:** `shopify/sections/dw-boost-filter-topbar.liquid`
+**Architecture:** DTD verdict **B** (officer-yolo 2026-06-25) — a CUSTOM horizontal
+dropdown toolbar (Liquid + JS) above the Boost grid that **reads Boost's
+filter-tree DOM + the URL's `pf_*` params** and **writes `pf_*` / `sort_by` /
+`q` params then navigates**. Boost stays the filter **ENGINE**; this code is
+**UX-only**. It never mutates Boost's result-grid DOM (zero grid-init-abort
+surface — ref memory `reference_dw_theme_grid_init_abort`).
+
+This section is the THEME half. It only renders dropdowns for facets Boost is
+configured to emit — so the **data layer (Boost SD dashboard) must be set up
+first** for each field below to carry real options. That dashboard config is the
+GATED step (see the consolidated pending-approval memo / runbook).
+
+---
+
+## Field → Boost filter-option mapping
+
+Each toolbar field writes exactly one Boost URL param. Boost param prefixes
+(verified on the live page 2026-06-25): `pf_t_<tag>` = tag/option-backed facet,
+`pf_v_brand` = vendor facet, `pf_p_price` = price range.
+
+| Toolbar field | Boost param | Boost facet source (configure in dashboard) | Live today? |
+|---|---|---|---|
+| **Color** (swatch dots) | `pf_t_color` | Tag/option **Color**, display **Color swatch**. Backing data: `global.Color-Way` / `custom.color` / `dwc.color` metafield → tag, OR a `Color` product option | ✅ `pf_t_color` emitted |
+| **Style** | `pf_t_style` | Tag/option **Style**. Backing: `global.Style` / `global.DESIGN_STYLE` tags (Traditional, Modern, Floral, Damask, Geometric…) | ✅ `pf_t_style` emitted |
+| **Material** | `pf_t_material` | Tag/option **Material**. Backing: `global.Contents`/`Content`/`Construction` → material tag (Grasscloth, Vinyl, Silk, Cork, Paper…) | ⬜ add facet |
+| **Brand** | `pf_v_brand` | Vendor facet (Boost built-in "Vendor"/"Brand"). House lines only — deny-list scrub in the section drops Brewster/York/WallQuest/Command54/etc. | ✅ `pf_v_brand` emitted |
+| **Process** | `pf_t_process` | Tag/option **Process**. Backing: `global.Finish`/`Finishing`/`FINISH` → process tag (Flocked, Beaded, Embossed, Hand-Printed, Digital…) | ⬜ add facet |
+| **Vendor** (alias of Brand) | `pf_v_brand` | Same vendor facet as Brand (kept as a distinct toggleable field per Steve's list; same underlying param) | ✅ |
+| **Swatch** (alias of Color) | `pf_t_color` | Same color facet, swatch display (kept distinct per Steve's list) | ✅ |
+| **Contents** | `pf_t_contents` | Tag/option **Contents**. Backing: `global.Contents`/`Content` metafield → tag | ⬜ add facet |
+| **Pattern** | `pf_t_pattern` | Tag/option **Pattern**. Backing: pattern-type tag (Floral, Stripe, Plaid, Trellis, Toile, Ikat…) — NOT the unique pattern *name* (too many values), the pattern *family* | ⬜ add facet |
+| **SKU** | `pf_t_sku` | Tag/option **SKU**. Practical note: SKU is high-cardinality; recommend leaving this OFF by default and relying on the **search box** (`q`) for SKU lookup. The dropdown still works if a SKU tag facet is configured | ⬜ optional |
+| **Durability** | `pf_t_durability` | Tag/option **Durability** (Type I/II/III, Wyzenbeek class) | ✅ `pf_t_durability` emitted |
+| **Era** | `pf_t_historical_era` | Tag/option **Historical era** | ✅ `pf_t_historical_era` emitted |
+| **Price** | `pf_p_price` | Boost **Price range** facet (built-in). Format `pf_p_price=<min>:<max>` | ✅ `pf_p_price` emitted |
+| **Created** | `sort_by=created-descending` / `created-ascending` | NOT a filter facet — exposed via the **Sort** dropdown (Created · Newest / Oldest). Boost honors Shopify `sort_by` | ✅ via sort |
+
+### Notes on the field list vs Steve's ask
+Steve named two overlapping sets:
+- **Common-process dropdowns to toggle:** color, style, material, brand, process.
+- **Filter/sort fields:** price, vendor, swatch, contents, pattern, color, sku, created.
+
+All are present. `vendor`≡`brand` and `swatch`≡`color` are the same Boost param
+but kept as independent toggleable fields so the shopper can show either label.
+`created` is a sort, not a facet, so it lives in the Sort dropdown. Each field is
+individually toggled ON/OFF via the ⚙ gear menu; the choice persists in
+`localStorage('dw_topbar_fields')` (same convention as sort/density/search).
+
+---
+
+## Sort + density + search (ported from new.designerwallcoverings.com)
+
+- **Sort** → writes `sort_by` (Newest, Created↑↓, Title A→Z/Z→A, Price ↑↓, Best
+  selling). Persists `localStorage('dw_collection_sort')`.
+- **Density** → sets CSS var `--dw-grid-cols` (the live theme's Boost override
+  already binds this var to `.boost-sd__product-list`). Persists
+  `localStorage('dw_collection_density')`. Desktop-only. **Never removes grid
+  nodes** — only the CSS var; a node-level fallback runs only if the theme var
+  isn't wired.
+- **Search** → writes `q` (debounced 450ms / Enter). Persists
+  `localStorage('dw_collection_search')`.
+
+These coexist with the store's **infinite scroll** (IntersectionObserver in the
+live theme) — the topbar never paginates; it deletes `page` on every change so
+Boost re-queries from the top, then infinite scroll resumes.
+
+---
+
+## How the dropdowns get their option values (read-only)
+
+1. Values already in the URL's `pf_*` params are always shown (active state).
+2. Boost's emitted filter-tree DOM (`.boost-sd__filter-tree` /
+   `.boost-sd__sidebar`) is scanned **read-only** for option anchors carrying
+   the `pf_*` param (href) or `data-filter-value`. Labels + counts are lifted.
+3. A `MutationObserver` on the Boost tree re-reads options (debounced 300ms) when
+   Boost re-renders — but only to repopulate OUR dropdowns.
+
+If a facet isn't configured in Boost, that field's dropdown shows a
+"configure in Boost (param `pf_t_x`)" hint instead of breaking. Active
+selections still apply.
+
+---
+
+## DOM hooks this section relies on (must stay intact in the theme)
+
+Read-only / additive only; this section adds a sibling node and never removes:
+- `.boost-sd__product-list` (grid container — density var target)
+- `.boost-sd__filter-tree` / `.boost-sd__sidebar` (option source)
+- `--dw-grid-cols` CSS var (already bound in the live `dw-boost-overrides`)
+
+---
+
+## Wiring (the GATED theme step)
+
+Drop the section into the collection template's group, OR render it from
+`layout/theme.liquid` just above the Boost grid. Recommended: add to the
+collection template JSON so it's a positioned section editable in the theme
+editor. Do this on the **DEV theme** first (G2), preview, then publish (G3).
+Exact commands + the Boost-dashboard facet config (G1) are in the consolidated
+pending-approval memo.
← a5a75bec Add dw-boost-filter-topbar section: horizontal dropdown filt · back to Designer Wallcoverings · Stage gated G1/G2/G3 memo + DEV-theme staging script for Boo 4573b89e →