@fluid-app/fluid-cli-theme-dev 0.1.243 → 0.1.245
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.mjs +360 -3
- package/dist/index.mjs.map +1 -1
- package/dist/skills/themes-cart-feedback/SKILL.md +93 -21
- package/dist/skills/themes-cart-feedback/references/cart-operation-events.md +4 -3
- package/dist/skills/themes-review/references/fairshare-attributes.md +15 -0
- package/package.json +2 -2
|
@@ -32,7 +32,7 @@ This skill is the **result** half of theme commerce. The **trigger** half — th
|
|
|
32
32
|
| Localize or restyle that toast, or move it to a corner | **Built-in feedback** + config |
|
|
33
33
|
| Update a custom cart-count badge / mini-cart when the cart changes | **Events** ([Part 2](#part-2--cart-operation-events)) |
|
|
34
34
|
| Flash an inline "Added ✓" on the exact product card the shopper clicked | **Events**, matched by `variantIds` |
|
|
35
|
-
|
|
|
35
|
+
| Draw a hand-built cart drawer, including the line of an add that is still filling | **Events** + [custom drawer recipe](#custom-buttons-and-drawers-async-carts) (`getPendingCartItems` + `onCartChange`) |
|
|
36
36
|
| Advance an enrollment-pack join flow after the pack lands (or show its error) | **Events**, keyed on `enrollmentPackId` |
|
|
37
37
|
| Report a failure that the SDK would otherwise swallow (`addCartItems`, `decrementCartItem`) | **Events** — `CART_OPERATION_ERROR` (a `try/catch` won't see it) |
|
|
38
38
|
|
|
@@ -164,6 +164,8 @@ When you drive the mutation from your own JS (not via a `data-fluid-*` attribute
|
|
|
164
164
|
<button id="custom-add" type="button">Add to cart</button>
|
|
165
165
|
<script>
|
|
166
166
|
document.getElementById("custom-add")?.addEventListener("click", (e) => {
|
|
167
|
+
// Show the SDK cart drawer at the click, before the add resolves.
|
|
168
|
+
window.FairShareSDK?.cart.control.open();
|
|
167
169
|
window.FairShareSDK?.withButtonLoading(e.currentTarget, () =>
|
|
168
170
|
window.FairShareSDK?.addCartItems(11111, { quantity: 1 }),
|
|
169
171
|
);
|
|
@@ -173,6 +175,7 @@ When you drive the mutation from your own JS (not via a `data-fluid-*` attribute
|
|
|
173
175
|
|
|
174
176
|
- `withButtonLoading(el, fn)` — runs `fn`, shows the spinner, and clears it in a `finally` (so an error still stops the spin). Prefer this.
|
|
175
177
|
- `setButtonLoading(el, on)` — manual toggle; idempotent, sets `aria-busy`. Use only when you can't wrap the call in a single function (then clear it in your own `finally`).
|
|
178
|
+
- Call `FairShareSDK.cart.control.open()` at the click when this button should show the SDK drawer. Declarative `data-fluid-add-to-cart` buttons open it at the click for you; a direct `addCartItems` call does not.
|
|
176
179
|
|
|
177
180
|
The spinner inherits the button's text color, so it fits any button style with no extra CSS.
|
|
178
181
|
|
|
@@ -242,7 +245,7 @@ Both events carry a `CustomEvent.detail`. The fields you'll actually use:
|
|
|
242
245
|
|
|
243
246
|
Full field list (plus `toast`, `timestamp`, `error`) is in [references/cart-operation-events.md](references/cart-operation-events.md).
|
|
244
247
|
|
|
245
|
-
> **Reading the cart count:**
|
|
248
|
+
> **Reading the cart count:** the SDK keeps every `id="fluid-cart-count"` element in sync by itself (worked example A), so a badge needs no handler. `getCartItemCount()` counts only the stored cart's items, so it is `0` while a new cart is still filling and ignores lines still pending; in your own handler call it only after `await window.FairShareSDK.whenCartSettled()`, or redraw from `onCartChange`. Use `e.detail.cart` only for fields you've confirmed exist.
|
|
246
249
|
|
|
247
250
|
## Attach the listener once
|
|
248
251
|
|
|
@@ -251,8 +254,10 @@ Register the listener a single time, at the theme/layout level — **not** insid
|
|
|
251
254
|
```html
|
|
252
255
|
{%- comment -%} In layouts/theme.liquid or a once-per-page section {%- endcomment -%}
|
|
253
256
|
<script>
|
|
254
|
-
window.addEventListener("CART_OPERATION_SUCCESS", (e) => {
|
|
255
|
-
|
|
257
|
+
window.addEventListener("CART_OPERATION_SUCCESS", async (e) => {
|
|
258
|
+
// A new cart can still be filling: wait before reading the stored cart.
|
|
259
|
+
await window.FairShareSDK?.whenCartSettled();
|
|
260
|
+
const badge = document.getElementById("my-cart-badge"); // not #fluid-cart-count: the SDK fills that one
|
|
256
261
|
if (badge) badge.textContent = String(window.FairShareSDK?.getCartItemCount() ?? "0");
|
|
257
262
|
});
|
|
258
263
|
</script>
|
|
@@ -269,13 +274,13 @@ if (!window.__themeCartListenerAttached) {
|
|
|
269
274
|
|
|
270
275
|
## Error handling — the swallow-vs-reject rule
|
|
271
276
|
|
|
272
|
-
**This is why the error event matters.** Some mutations reject their promise on failure (you can `try/catch`); two **swallow** the failure and resolve `undefined` for backward compatibility, so a `try/catch` sees nothing:
|
|
277
|
+
**This is why the error event matters.** Some mutations reject their promise on failure (you can `try/catch`); two **swallow** the failure and resolve `undefined` for backward compatibility, so a `try/catch` sees nothing. On success `addCartItems` resolves with the filled cart (see [the resolve value](#custom-buttons-and-drawers-async-carts)), so `undefined` always means the add, or the cart fill, failed:
|
|
273
278
|
|
|
274
279
|
| Mutation | On failure | Can `try/catch` see it? |
|
|
275
280
|
| ----------------------- | --------------------------------- | ----------------------- |
|
|
276
281
|
| `addCartItems` | resolves `undefined` (swallowed) | **No** — use the event |
|
|
277
282
|
| `decrementCartItem` | resolves `undefined` (swallowed) | **No** — use the event |
|
|
278
|
-
| `addEnrollmentPack` | rethrows
|
|
283
|
+
| `addEnrollmentPack` | rethrows (`undefined` if the cart fill fails) | Yes (the fill failure: use the event) |
|
|
279
284
|
| `updateCartItems` | rethrows | Yes |
|
|
280
285
|
| `updateCartItemVariant` | rethrows | Yes |
|
|
281
286
|
| `removeCartItemById` | rethrows | Yes |
|
|
@@ -288,6 +293,26 @@ window.addEventListener("CART_OPERATION_ERROR", (e) => {
|
|
|
288
293
|
});
|
|
289
294
|
```
|
|
290
295
|
|
|
296
|
+
## Custom buttons and drawers (async carts)
|
|
297
|
+
|
|
298
|
+
Every Fluid storefront creates carts in the background. A new cart comes back empty with `population_status: "pending"` and fills over the realtime channel (`complete` or `failed`), usually within a few hundred ms to about 2 s. Theme code that adds to the cart or draws its own cart must allow for that. Full reference: [Carts that fill in the background](https://docs.fluid.app/sdk/cart-api#carts-that-fill-in-the-background) and [Custom cart drawers](https://docs.fluid.app/themes/custom-cart-drawer).
|
|
299
|
+
|
|
300
|
+
**The resolve value.** `addCartItems`, `addEnrollmentPack` and `setEnrollment` wait (at most 10 s) for the fill and resolve with the FILLED cart. When the add or the fill fails they resolve `undefined` and `CART_POPULATION_FAILED` fires for a failed fill. `getCart()` and `refreshCart()` also wait while the cart fills. `await window.FairShareSDK.whenCartSettled()` waits explicitly; call it before reading `getLocalCart()` right after an add.
|
|
301
|
+
|
|
302
|
+
**Events around an add.** `CART_ITEMS_ADDING` fires synchronously before any request, with the lines being added (`detail.lines`). `CART_ITEMS_SETTLED` fires when the add ends (`detail.outcome` is `"success"` or `"error"`). Its `detail.cart` can be a cart that is still filling, so read items from it only when `population_status` is `"complete"`.
|
|
303
|
+
|
|
304
|
+
**Open the drawer at the click.** A declarative `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` button opens the SDK drawer at the click with an optimistic line. A theme that calls `addCartItems` itself and wants the SDK drawer calls `window.FairShareSDK.cart.control.open()` at the click, before it awaits the add.
|
|
305
|
+
|
|
306
|
+
**Never use `createCart()` to read data.** `FairShareSDK.createCart()` always creates a NEW empty cart and replaces the shopper's cart token. To read the country or language use `getCountryCode()` / `getLanguage()`; to read the cart use `getLocalCart()`.
|
|
307
|
+
|
|
308
|
+
**Custom drawer recipe.** A hand-built drawer (not the Fluid cart widget) draws the stored cart plus the lines of adds the server has not answered yet:
|
|
309
|
+
|
|
310
|
+
1. Open the drawer at the click, or on the `CART_ITEMS_ADDING` window event. On an SDK button set `data-fluid-open-cart-after-add="false"` so the SDK drawer does not open as well.
|
|
311
|
+
2. Render once with `getLocalCart()` and `getPendingCartItems()`; the `onCartChange` handler is not called on subscribe.
|
|
312
|
+
3. Subscribe with `onCartChange(({ cart, pendingItems }) => render(cart, pendingItems))` and redraw on every call. It fires when an add starts or settles, when a cart body arrives, when a fill fails and when a pending item expires.
|
|
313
|
+
4. Draw `pendingItems` after `cart.items`. Show totals as pending while `pendingItems.length > 0`.
|
|
314
|
+
5. `await window.FairShareSDK.waitForCheckoutReady()` before you send the shopper to checkout yourself; `checkout()` already waits.
|
|
315
|
+
|
|
291
316
|
## Worked examples
|
|
292
317
|
|
|
293
318
|
### A. Live cart-count badge (product cards, shop grids, navbar)
|
|
@@ -298,18 +323,19 @@ The single most common need, and it needs no JavaScript. The SDK keeps the text
|
|
|
298
323
|
<span id="fluid-cart-count">0</span>
|
|
299
324
|
```
|
|
300
325
|
|
|
301
|
-
Do not seed it with `{{ cart.item_count }}`: `cart` exists only in `cart_page` templates, so everywhere else it renders empty until the SDK fills it. To drive a different element,
|
|
326
|
+
Do not seed it with `{{ cart.item_count }}`: `cart` exists only in `cart_page` templates, so everywhere else it renders empty until the SDK fills it. To drive a different element, subscribe with `window.FairShareSDK.onCartChange(...)` and count `cart.items` yourself. `getCartItemCount()` counts only the stored cart's items (`0` while a new cart is still filling), so call it only after `await window.FairShareSDK.whenCartSettled()`.
|
|
302
327
|
|
|
303
328
|
### B. Inline "Added ✓" on the exact card clicked (`variantIds` match)
|
|
304
329
|
|
|
305
|
-
When a grid of product cards shares one listener, use `variantIds` to light up only the card the shopper acted on.
|
|
330
|
+
When a grid of product cards shares one listener, use `variantIds` to light up only the card the shopper acted on. Use the declarative button (it spins on its own and needs no inline JavaScript), and reveal a **separate** confirmation element rather than overwriting the button text. `data-fluid-open-cart-after-add="false"` keeps the cart drawer closed so the flag is the confirmation:
|
|
306
331
|
|
|
307
332
|
```html
|
|
308
333
|
{%- comment -%} Each card carries its variant id; a hidden confirmation sits alongside the button {%- endcomment -%}
|
|
309
334
|
<div class="product-card" data-variant-id="{{ product.selected_or_first_available_variant.id }}">
|
|
310
335
|
<button
|
|
311
336
|
type="button"
|
|
312
|
-
|
|
337
|
+
data-fluid-add-to-cart="{{ product.selected_or_first_available_variant.id }}"
|
|
338
|
+
data-fluid-open-cart-after-add="false"
|
|
313
339
|
>
|
|
314
340
|
{{ 'product.add_to_cart' | t }}
|
|
315
341
|
</button>
|
|
@@ -326,19 +352,52 @@ When a grid of product cards shares one listener, use `variantIds` to light up o
|
|
|
326
352
|
</script>
|
|
327
353
|
```
|
|
328
354
|
|
|
329
|
-
### C.
|
|
355
|
+
### C. Draw a custom cart drawer (`getPendingCartItems` + `onCartChange`)
|
|
330
356
|
|
|
331
|
-
A hand-built
|
|
357
|
+
A hand-built drawer must show an added line at the click, even when the add creates the cart and the server's cart is still empty. Do not wait for `CART_OPERATION_SUCCESS` to open or redraw it. Draw the stored cart, then the pending items on top, and redraw on every `onCartChange`:
|
|
332
358
|
|
|
333
|
-
```
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
359
|
+
```html
|
|
360
|
+
<button data-fluid-add-to-cart="22190" data-fluid-open-cart-after-add="false">Add</button>
|
|
361
|
+
<aside id="my-cart" hidden>
|
|
362
|
+
<ul id="my-cart-lines"></ul>
|
|
363
|
+
<p id="my-cart-total"></p>
|
|
364
|
+
</aside>
|
|
365
|
+
<script>
|
|
366
|
+
window.addEventListener("DOMContentLoaded", () => {
|
|
367
|
+
const sdk = window.FairShareSDK;
|
|
368
|
+
if (!sdk) return;
|
|
369
|
+
const drawer = document.getElementById("my-cart");
|
|
370
|
+
const list = document.getElementById("my-cart-lines");
|
|
371
|
+
const total = document.getElementById("my-cart-total");
|
|
372
|
+
|
|
373
|
+
function render({ cart, pendingItems }) {
|
|
374
|
+
// Simplified: matches a line on its variant only. Subscription and bundle
|
|
375
|
+
// lines need the matching rules in the SDK README ("Custom cart drawers").
|
|
376
|
+
const rows = (cart?.items ?? []).map((item) => ({
|
|
377
|
+
variantId: item.variant?.id,
|
|
378
|
+
quantity: item.quantity,
|
|
379
|
+
title: item.product_title,
|
|
380
|
+
}));
|
|
381
|
+
for (const p of pendingItems) {
|
|
382
|
+
const row = rows.find((r) => r.variantId === p.variant_id);
|
|
383
|
+
if (row) row.quantity = p.listedQuantity + p.quantity;
|
|
384
|
+
else rows.push({ variantId: p.variant_id, quantity: p.quantity, title: p.preview?.product_title ?? "Adding…" });
|
|
385
|
+
}
|
|
386
|
+
list.replaceChildren(
|
|
387
|
+
...rows.map((r) => Object.assign(document.createElement("li"), { textContent: `${r.quantity} x ${r.title}` })),
|
|
388
|
+
);
|
|
389
|
+
// cart.sub_total_in_currency does not count the pending lines yet.
|
|
390
|
+
total.textContent = pendingItems.length ? "…" : (cart?.sub_total_in_currency ?? "");
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
window.addEventListener("CART_ITEMS_ADDING", () => { drawer.hidden = false; }); // before any request
|
|
394
|
+
sdk.onCartChange(render);
|
|
395
|
+
render({ cart: sdk.getLocalCart(), pendingItems: sdk.getPendingCartItems() }); // not called on subscribe
|
|
396
|
+
});
|
|
397
|
+
</script>
|
|
339
398
|
```
|
|
340
399
|
|
|
341
|
-
|
|
400
|
+
Send the shopper to checkout with `await sdk.waitForCheckoutReady(); sdk.checkout();`, or call `checkout()` alone, which waits too.
|
|
342
401
|
|
|
343
402
|
### D. Enrollment-pack join flow (`enrollmentPackId`)
|
|
344
403
|
|
|
@@ -380,7 +439,11 @@ The declarative button handles its in-flight state automatically; the events han
|
|
|
380
439
|
- **Calling `configureCartFeedback` / the SDK without `?.` or before `DOMContentLoaded`.** The `defer`'d SDK may not be ready; guard every access with `window.FairShareSDK?.`.
|
|
381
440
|
- **Hardcoding toast strings.** Use `messages: { add: {{ 'cart.added' | t | json }} }`. Hand-quoting `{{ '…' | t }}` breaks on apostrophes and defeats localization.
|
|
382
441
|
- **Reimplementing a button spinner.** Declarative `data-fluid-*` buttons spin automatically; use `withButtonLoading` for direct SDK calls. Both set `aria-busy` and inherit the button color.
|
|
383
|
-
- **Guessing `e.detail.cart` field names.** Use `getCartItemCount()`
|
|
442
|
+
- **Guessing `e.detail.cart` field names.** Use the SDK-synced `#fluid-cart-count` for a badge, or `getCartItemCount()` after `whenCartSettled()`; only read cart fields you've verified in a running theme.
|
|
443
|
+
- **Calling `createCart()` to read data.** It always creates a NEW empty cart and replaces the shopper's cart token. Use `getCountryCode()`, `getLanguage()` or `getLocalCart()`.
|
|
444
|
+
- **A custom `addCartItems` button that never opens the drawer at the click.** Call `FairShareSDK.cart.control.open()` at the click, before awaiting the add; otherwise the shopper sees nothing until the cart fills.
|
|
445
|
+
- **Redrawing a hand-built drawer only on `CART_OPERATION_SUCCESS`.** It arrives after the fill, so a new cart shows empty first. Use `getPendingCartItems()` + `onCartChange()` (worked example C).
|
|
446
|
+
- **Reading `getCartItemCount()` or `getLocalCart()` right after an add.** The stored cart can still be filling. Await `whenCartSettled()` first, or use the cart the add resolved with.
|
|
384
447
|
|
|
385
448
|
## Quick audit
|
|
386
449
|
|
|
@@ -399,6 +462,12 @@ grep -rnE 'window\.FairShareSDK\.' --include='*.liquid' --include='*.js' . 2>/de
|
|
|
399
462
|
# Hardcoded toast messages (missing | t | json)
|
|
400
463
|
grep -rnE 'messages:[[:space:]]*\{' --include='*.liquid' . 2>/dev/null
|
|
401
464
|
|
|
465
|
+
# createCart() used to read data (it replaces the shopper's cart)
|
|
466
|
+
grep -rnE 'createCart\(' --include='*.liquid' --include='*.js' . 2>/dev/null
|
|
467
|
+
|
|
468
|
+
# Custom addCartItems calls: confirm each one opens the drawer at the click
|
|
469
|
+
grep -rlE 'addCartItems' --include='*.liquid' --include='*.js' . 2>/dev/null | xargs grep -LE 'cart\.control\.open|openCart|data-fluid-cart="open"' 2>/dev/null
|
|
470
|
+
|
|
402
471
|
# Hand-rolled cart fetches that bypass the SDK
|
|
403
472
|
grep -rnE "fetch\(['\"][^'\"]*cart" --include='*.liquid' --include='*.js' . 2>/dev/null
|
|
404
473
|
```
|
|
@@ -426,7 +495,10 @@ Each hit is a candidate finding — confirm in context before flagging.
|
|
|
426
495
|
- [ ] Listener attached once (layout level or guarded), never per-section / per-card
|
|
427
496
|
- [ ] Failures surfaced from `CART_OPERATION_ERROR`, not a `try/catch` (mandatory for `addCartItems` / `decrementCartItem`)
|
|
428
497
|
- [ ] Per-card / per-item reactions matched via `variantIds` / `itemId`; enrollment via `enrollmentPackId`
|
|
429
|
-
- [ ] Cart count
|
|
498
|
+
- [ ] Cart count comes from `#fluid-cart-count`, or from `getCartItemCount()` after `whenCartSettled()`, not a guessed `e.detail.cart` field
|
|
499
|
+
- [ ] A custom `addCartItems` button opens the SDK drawer at the click (`FairShareSDK.cart.control.open()`), before awaiting the add
|
|
500
|
+
- [ ] A hand-built drawer draws `getPendingCartItems()` and redraws on `onCartChange()`, not only on `CART_OPERATION_SUCCESS`
|
|
501
|
+
- [ ] No `createCart()` call reads data (it replaces the shopper's cart); use `getCountryCode()` / `getLanguage()` / `getLocalCart()`
|
|
430
502
|
|
|
431
503
|
**Correctness**
|
|
432
504
|
|
|
@@ -438,7 +510,7 @@ Each hit is a candidate finding — confirm in context before flagging.
|
|
|
438
510
|
## Boundaries — local edits, lint, never push
|
|
439
511
|
|
|
440
512
|
- Everything here is a **local file edit** — Liquid, JS, and CSS in the theme repo. This skill never runs `fluid theme push`, never calls the API, and never writes to the live theme **without explicit approval**.
|
|
441
|
-
- Run `fluid theme lint --json` after schema-adjacent edits and parse the JSON, as with any theme change. **But note:** the linter validates `{% schema %}` and section references
|
|
513
|
+
- Run `fluid theme lint --json` after schema-adjacent edits and parse the JSON, as with any theme change. **But note:** the linter validates `{% schema %}` and section references, and warns (never errors) on two cart-code patterns: `cart/create-cart-for-data` (`FairShareSDK.createCart()` used to read data; it creates a new empty cart, so use `getCountryCode()` / `getLocalCart()`) and `cart/custom-add-without-drawer-open` (a file calls `addCartItems` / `addEnrollmentPack` / `setEnrollment` but never opens the drawer at click or renders from `onCartChange()` / `getPendingCartItems()`; the SDK drawer does not open for a scripted add, only for declarative buttons). It does **not** execute or check the event wiring or the toast config. The real check for this skill is **`fluid theme dev`**: open the storefront, add/update/remove an item, and watch the toast, the spinner, the badge, and (via the console) the events actually fire.
|
|
442
514
|
- When reviewing a PR rather than authoring, follow the `themes-review` workflow — inline `file:line` findings with a `blocker` / `should` / `nit` severity, and don't push to the author's branch.
|
|
443
515
|
|
|
444
516
|
## Reference
|
|
@@ -41,8 +41,8 @@ Every cart mutation dispatches one of the two events. The **failure column matte
|
|
|
41
41
|
|
|
42
42
|
| Function | Category | On success | On failure |
|
|
43
43
|
| ----------------------- | -------- | ------------------------ | ----------------------------------------------------- |
|
|
44
|
-
| `addCartItems` | add | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed) |
|
|
45
|
-
| `addEnrollmentPack` | add | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows**
|
|
44
|
+
| `addCartItems` | add | `CART_OPERATION_SUCCESS` (resolves with the filled cart) | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed); also when the cart fill fails |
|
|
45
|
+
| `addEnrollmentPack` | add | `CART_OPERATION_SUCCESS` (resolves with the filled cart) | `CART_OPERATION_ERROR` — **rethrows** (resolves `undefined` when the cart fill fails) |
|
|
46
46
|
| `updateCartItems` | update | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows** |
|
|
47
47
|
| `decrementCartItem` | update | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **resolves `undefined`** (swallowed) |
|
|
48
48
|
| `updateCartItemVariant` | update | `CART_OPERATION_SUCCESS` | `CART_OPERATION_ERROR` — **rethrows** |
|
|
@@ -67,7 +67,7 @@ Both events expose an identical `detail` object structure. Fields marked "when k
|
|
|
67
67
|
| `itemId` | `number` | when known | Cart item id (item-scoped ops). |
|
|
68
68
|
| `enrollmentPackId` | `number` | when known | Enrollment pack id (`addEnrollmentPack`). |
|
|
69
69
|
|
|
70
|
-
>
|
|
70
|
+
> For a count, use the SDK-synced `id="fluid-cart-count"` element, or call `window.FairShareSDK.getCartItemCount()` after `await window.FairShareSDK.whenCartSettled()`: the getter counts only the stored cart's items, so it is `0` while a new cart is still filling and ignores lines still pending. The `cart` object's shape is not enumerated here, so read `e.detail.cart` fields only after confirming them in a running theme.
|
|
71
71
|
|
|
72
72
|
## `configureCartFeedback()` — complete config keys
|
|
73
73
|
|
|
@@ -184,6 +184,7 @@ The spinner inherits the button's text color, so it needs no per-theme CSS.
|
|
|
184
184
|
```javascript
|
|
185
185
|
// Automated cleanup (preferred)
|
|
186
186
|
button.addEventListener("click", (e) => {
|
|
187
|
+
window.FairShareSDK?.cart.control.open(); // only if the SDK drawer should show the add; open at click
|
|
187
188
|
window.FairShareSDK?.withButtonLoading(e.currentTarget, () =>
|
|
188
189
|
window.FairShareSDK.addCartItems(11111, { quantity: 1 }),
|
|
189
190
|
);
|
|
@@ -151,6 +151,16 @@ The reviewer should flag these on any element that uses `data-fluid-*`:
|
|
|
151
151
|
| `data-fluid-quantity="{{ section.settings.default_qty | default: 1 }}"` rendering to empty | `should` | Always provide a `default:` filter for settings that are required by the SDK to be integers. |
|
|
152
152
|
| `data-fluid-bundled-items` JSON built with un-escaped Liquid (commas/quotes from user content) | `blocker` | Render through ` | json` or hand-craft only with sanitized numeric IDs. User-controlled strings inside JSON attributes are an XSS path. |
|
|
153
153
|
|
|
154
|
+
#### Cart calls in theme JavaScript
|
|
155
|
+
|
|
156
|
+
Every storefront creates carts in the background: a new cart is empty and `population_status: "pending"` for a few hundred ms to about 2 s. `addCartItems`, `addEnrollmentPack` and `setEnrollment` wait for the fill and resolve with the filled cart (`undefined` when the add or the fill fails). See [Cart operation feedback](../../themes-cart-feedback/SKILL.md#custom-buttons-and-drawers-async-carts) for the recipes.
|
|
157
|
+
|
|
158
|
+
| You see | Severity | Fix |
|
|
159
|
+
| --- | --- | --- |
|
|
160
|
+
| `FairShareSDK.createCart()` used to read data such as the country | `blocker` | `createCart()` always creates a NEW empty cart and replaces the shopper's cart token. Read with `getCountryCode()`, `getLanguage()` or `getLocalCart()`. |
|
|
161
|
+
| A theme script calls `addCartItems(...)` for a button that should show the SDK cart drawer and never calls `FairShareSDK.cart.control.open()` | `should` | Call `FairShareSDK.cart.control.open()` at the click, before awaiting the add. Only declarative `data-fluid-add-to-cart` / `data-fluid-add-enrollment-pack` buttons open the drawer at click on their own. |
|
|
162
|
+
| A hand-built drawer opens or redraws only on `CART_OPERATION_SUCCESS` | `should` | Draw `getPendingCartItems()` on top of the cart and redraw on `onCartChange()`. |
|
|
163
|
+
|
|
154
164
|
### Quick audit
|
|
155
165
|
|
|
156
166
|
From the theme repo root:
|
|
@@ -172,6 +182,9 @@ done
|
|
|
172
182
|
|
|
173
183
|
# Wrong cart action values
|
|
174
184
|
grep -rE 'data-fluid-cart="(?!(open|close|toggle)")' --include='*.liquid' . 2>/dev/null
|
|
185
|
+
|
|
186
|
+
# createCart() used to read data (it replaces the shopper's cart)
|
|
187
|
+
grep -rnE 'createCart\(' --include='*.liquid' --include='*.js' . 2>/dev/null
|
|
175
188
|
```
|
|
176
189
|
|
|
177
190
|
### Checklist for FairShare-attributed elements
|
|
@@ -183,5 +196,7 @@ grep -rE 'data-fluid-cart="(?!(open|close|toggle)")' --include='*.liquid' . 2>/d
|
|
|
183
196
|
- [ ] `data-fluid-bundled-items` / `data-fluid-bundle-selections` are valid JSON arrays with numeric IDs and quantities
|
|
184
197
|
- [ ] Attributes live on a `<button>` or `<a>` (or have appropriate ARIA + click semantics)
|
|
185
198
|
- [ ] Script tag has `id="fluid-cdn-script"` and `data-fluid-shop` set, and there is exactly one
|
|
199
|
+
- [ ] No `FairShareSDK.createCart()` call reads data; it replaces the shopper's cart
|
|
200
|
+
- [ ] A custom `addCartItems` button opens the SDK drawer at the click with `FairShareSDK.cart.control.open()`
|
|
186
201
|
|
|
187
202
|
---
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fluid-app/fluid-cli-theme-dev",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.245",
|
|
4
4
|
"description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init, crawl, compare",
|
|
5
5
|
"files": [
|
|
6
6
|
"dist",
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
"access": "public"
|
|
22
22
|
},
|
|
23
23
|
"dependencies": {
|
|
24
|
-
"@fluid-app/fluid-cli": "0.1.
|
|
24
|
+
"@fluid-app/fluid-cli": "0.1.61",
|
|
25
25
|
"chalk": "^5.6.2",
|
|
26
26
|
"chokidar": "^4.0.0",
|
|
27
27
|
"commander": "^12.0.0",
|