Mix & match

The mix & match widget never shows anything, on any product

Same self-hiding shape as the bundle/volume widgets - <storesynk-mix-match> sets [ss-empty] in every “nothing to say” case, so they all look identical:

1. No namespace configured. The widget needs the Storesynk app’s concrete metafield namespace (app--<numeric-app-id>) - Storefront queries can’t use the $app: shorthand. Set app-namespace="app--…" on <storesynk-store> or namespace on the widget; neither warns SSK-211 and the widget stays ss-empty with no network request at all (that absence is the diagnostic). This applies in both modes - handle mode builds its metaobject type from the namespace too (<namespace>--mix_match).
2. Not inside the page’s <storesynk-product>, and no handle. Without a handle the widget reads the current product’s mix_match metafield, so it needs a product ancestor (SSK-102). On a standalone builder page give it handle="…" instead - that’s the supported no-product mode.
3. No template. Its first element child must be (or contain) a <mix-match-offer> (SSK-107). Same for the three inner containers: <mix-match-section-list> needs a <mix-match-section> first child, <mix-match-item-list> needs a <storesynk-product> pool card, <mix-match-selection-list> needs a pick template.
4. No live bundle - by design. Only active bundles inside their date window render (cap: 5 per product). If the app says a bundle exists, check its status and window dates, and that the pool products are published to the headless channel.
5. Currency gate. A bundle whose fixed_amount / set_price discount was recorded in a different currency than the storefront presents is skipped at render time on purpose - never a wrong price. Switching the buyer’s market can therefore make a bundle vanish; that is correct behavior, not a bug.

The bundle renders but a section’s title / requirement / count / progress is blank

Those show-section-* leaves consume the per-section context that <mix-match-section-list> attaches to each clone - they must live inside the <mix-match-section> section template (SSK-105). Authored one level up (a sibling of the section, or directly under <mix-match-offer>) they sit on the detached template forever and are never touched. Same rule for <toggle-section> and <mix-match-item-list>.

The picked-items strip, the “+N”, or the box totals are blank

show-pick-image / show-pick-quantity need a <mix-match-selection-list> ancestor and belong inside its first-child pick template; <show-selection-overflow> belongs inside the list but after that template (it reads the list’s max). The show-mix-match-* totals and <add-mix-match-to-cart> need a <mix-match-offer> ancestor (SSK-105). Note that the total / original total / savings / tier hint deliberately hide (hidden + [ss-empty]) while nothing is picked or there are no positive savings - by design, not a bug.

The section pool is empty, or every card shows the same product

The pool cards are clones of the first element child of <mix-match-item-list>, which must be (or contain) a <storesynk-product> (SSK-107). Author exactly one card and let the engine clone it - a hand-written list of N cards means only the first is a template and the rest are inert markup. The card must carry no handle/product-id: it is fed via provideProduct(). It is also the one place besides <bundle-member-list> where a nested <storesynk-product> is legal (SSK-103 exempts it).

A pool card shows no variant dropdown, though the product has options

The card’s variant list was truncated by the pool query, so it degrades to its default variant and the engine flags it [ss-variants-truncated]. Show an affordance rather than hiding the problem - e.g. storesynk-product[ss-variants-truncated] .card-title::after { content: " (more options on the product page)" } (build-patterns §2.13).

Clicking a section header does nothing / the accordion won’t open

<toggle-section> dispatches sf:section-toggle up to <mix-match-section-list>, which owns the state - so a toggle-section outside the section template never reaches a list (SSK-105), and a <mix-match-section> outside a <mix-match-section-list> is never cloned or stamped (SSK-106). If it toggles but nothing appears, suspect CSS: the panel’s visibility is the engine’s native hidden on <mix-match-item-list> (plus its engine-assigned id, the aria-controls target). CSS that forces display on the panel unconditionally defeats both.

Sections open and close on their own

That’s the designed accordion: the first unmet section opens by default, and when the open section’s min is met it collapses and the next unmet one opens. A manual <toggle-section> click overrides that until the next met-transition. Style it off [ss-open] / [ss-met] on <mix-match-section>.

The “Add box to cart” button is greyed out / clicks do nothing

<add-mix-match-to-cart> carries [ss-incomplete] + aria-disabled until every section’s picked count is inside its [min, max] - an over-filled section blocks it as surely as an empty one, so check the maxima, not just the minima. If it does nothing with ss-incomplete absent, the standard actions aren’t installed: the page is missing its <storesynk-store> boot (SSK-101/206) or the elements script (SSK-401). During the add it carries [ss-loading].

An “Add” or ”+” control is dead on some cards

By design: add-mix-match-item mirrors the card’s availability ([ss-out-of-stock] / [ss-unavailable] on the wrapper, aria-disabled on the control), and both it and increase-mix-match-item get [ss-max] + aria-disabled once the section is at capacity. decrease / remove are aria-disabled while the card isn’t picked. Style those states rather than removing the controls.

A screen reader announces the stepper buttons as just “button”

The three icon-only steppers - increase-mix-match-item, decrease-mix-match-item, remove-mix-match-item - are the one control family the engine deliberately does not name (a generic label would be wrong per card), so ”+” / ”−” / ”×” is all AT gets. Put an aria-label on each tag or its nested <button>; the validator warns SSK-501.

The box total doesn’t match what checkout charges

The quote is advisory: integer-cent math shared with the app’s Discount Function, which applies the real discount at checkout from the _ss_mm / _ss_mm_group / _ss_mm_section attributes <add-mix-match-to-cart> stamps on each line. Small display-vs-checkout differences are expected. If the cart shows the lines but no discount, the app’s Function isn’t installed/active for the shop, or something stripped those line attributes - the widget sends them in one multi-line updateCart per click (a fresh _ss_mm_group nonce each time, so two boxes stay distinct groups).

The standalone builder page (handle mode) flashes empty before it loads

Expected: handle mode is client-fetch only - the server transform leaves it untouched, so there is no pre-hydration HTML. Style the [ss-loading] / [ss-empty] states as your skeleton. The PDP placement is the one that server-renders and adopts with zero refetch.

---

Imported from the Storesynk skill v0.1.0 (references/known-issues.md). To change this page, change it there.