@fluid-app/fluid-cli-theme-dev 0.1.38 → 0.1.40
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.
|
@@ -3,9 +3,9 @@ name: themes-cart-feedback
|
|
|
3
3
|
description: |
|
|
4
4
|
Wire up shopper feedback for cart mutations in a Fluid Liquid theme, using the FairShare
|
|
5
5
|
web-widget SDK. Two surfaces: (1) the built-in feedback — a toast that confirms or reports
|
|
6
|
-
a cart add/update/remove and add-to-cart
|
|
7
|
-
|
|
8
|
-
`data-fluid-button-loading
|
|
6
|
+
a cart add/update/remove and default add-to-cart button spinners; enable the toast with
|
|
7
|
+
`FairShareSDK.configureCartFeedback(...)` or `data-fluid-toast`, and disable button loading
|
|
8
|
+
with `buttonLoading: false` or `data-fluid-button-loading="false"`; (2) the cart operation events —
|
|
9
9
|
`CART_OPERATION_SUCCESS` and `CART_OPERATION_ERROR` window events that fire on every cart
|
|
10
10
|
mutation regardless of toast config, so custom UI can react. Use when building or reviewing
|
|
11
11
|
anything that adds to cart or reacts to a cart change: custom product cards, shop / collection
|
|
@@ -19,7 +19,7 @@ description: |
|
|
|
19
19
|
|
|
20
20
|
When a shopper adds, updates, or removes a cart item on a Fluid theme, the FairShare web-widget SDK can surface the result two ways:
|
|
21
21
|
|
|
22
|
-
1. **Built-in feedback** — a **toast** confirms success or reports a failure, and add-to-cart **buttons** show a spinner while the request is in flight.
|
|
22
|
+
1. **Built-in feedback** — a **toast** confirms success or reports a failure, and add-to-cart **buttons** show a spinner while the request is in flight. Enable the toast once; button loading is on by default in web-widgets 0.16.0 and later. This is the right default for most themes.
|
|
23
23
|
2. **Cart operation events** — the SDK dispatches `CART_OPERATION_SUCCESS` and `CART_OPERATION_ERROR` on `window` for **every** mutation, whether or not the toast is enabled. Listen to these when you're building custom commerce UI that has to react — update a mini-cart badge, re-render a cart drawer, flash an inline confirmation on the specific product card, or route an enrollment flow forward.
|
|
24
24
|
|
|
25
25
|
This skill is the **result** half of theme commerce. The **trigger** half — the declarative `data-fluid-add-to-cart`, `data-fluid-add-enrollment-pack`, `data-fluid-cart` attributes and the CDN `<script>` — lives in the `themes-review` skill's [FairShare attributes reference](../themes-review/references/fairshare-attributes.md). Read that first if the theme doesn't yet load the SDK or wire up add-to-cart buttons.
|
|
@@ -57,9 +57,9 @@ Without it, `window.FairShareSDK` is undefined and no events fire. See the [Fair
|
|
|
57
57
|
|
|
58
58
|
# Part 1 — Built-in feedback
|
|
59
59
|
|
|
60
|
-
The built-in toast + button-loading covers the 80% case with no custom JavaScript.
|
|
60
|
+
The built-in toast + button-loading covers the 80% case with no custom JavaScript. Enable the toast once, localize the strings, optionally restyle, and keep the default button loading unless the theme supplies its own.
|
|
61
61
|
|
|
62
|
-
## Enable
|
|
62
|
+
## Enable the toast
|
|
63
63
|
|
|
64
64
|
Two ways, and they merge (**precedence: `configureCartFeedback()` call > script-tag attributes > defaults**).
|
|
65
65
|
|
|
@@ -72,7 +72,6 @@ Put this in `layouts/theme.liquid` (or a section that renders on every commerce
|
|
|
72
72
|
window.addEventListener("DOMContentLoaded", () => {
|
|
73
73
|
window.FairShareSDK?.configureCartFeedback({
|
|
74
74
|
toast: true,
|
|
75
|
-
buttonLoading: true,
|
|
76
75
|
position: "bottom-right",
|
|
77
76
|
messages: {
|
|
78
77
|
add: {{ 'cart.added' | t | json }},
|
|
@@ -98,7 +97,6 @@ Add attributes to the same `<script id="fluid-cdn-script">` tag:
|
|
|
98
97
|
src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
|
|
99
98
|
data-fluid-shop="{{ shop.handle }}"
|
|
100
99
|
data-fluid-toast="true"
|
|
101
|
-
data-fluid-button-loading="true"
|
|
102
100
|
data-fluid-toast-position="bottom-right"
|
|
103
101
|
defer
|
|
104
102
|
></script>
|
|
@@ -111,7 +109,7 @@ Use this only when the theme doesn't need translated strings. Anything you can p
|
|
|
111
109
|
| Key (`configureCartFeedback`) | Type | Default | Notes |
|
|
112
110
|
| ----------------------------- | --------- | ---------------- | ---------------------------------------------------------------------------------- |
|
|
113
111
|
| `toast` | boolean | `false` | Master switch for the toast. |
|
|
114
|
-
| `buttonLoading` | boolean | `
|
|
112
|
+
| `buttonLoading` | boolean | `true` | Set to `false` to disable the auto-spinner on `data-fluid-add-to-cart` / `data-fluid-add-enrollment-pack` buttons. |
|
|
115
113
|
| `position` | string | `bottom-center` | `bottom-center` \| `bottom-left` \| `bottom-right` \| `top-center` \| `top-left` \| `top-right`. |
|
|
116
114
|
| `duration` | number | `4000` | Auto-dismiss delay in ms. |
|
|
117
115
|
| `class` | string | — | Extra CSS class on the toast, for styling. |
|
|
@@ -142,9 +140,9 @@ messages: {
|
|
|
142
140
|
|
|
143
141
|
Two ways to spin a button while its cart request is in flight.
|
|
144
142
|
|
|
145
|
-
### Declarative — for `data-fluid-*` buttons
|
|
143
|
+
### Declarative — automatic for `data-fluid-*` buttons
|
|
146
144
|
|
|
147
|
-
|
|
145
|
+
In web-widgets 0.16.0 and later, any button carrying `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` spins automatically. Customize the label with `data-fluid-loading-text`:
|
|
148
146
|
|
|
149
147
|
```liquid
|
|
150
148
|
<button
|
|
@@ -156,6 +154,8 @@ With `buttonLoading: true` (or `data-fluid-button-loading="true"`), any button c
|
|
|
156
154
|
</button>
|
|
157
155
|
```
|
|
158
156
|
|
|
157
|
+
To disable automatic loading, set `buttonLoading: false` in `configureCartFeedback()` or add `data-fluid-button-loading="false"` to the SDK script. The script attribute is a kill switch; do not add `"true"` to enable loading.
|
|
158
|
+
|
|
159
159
|
### Programmatic — for buttons that call the SDK directly
|
|
160
160
|
|
|
161
161
|
When you drive the mutation from your own JS (not via a `data-fluid-*` attribute), wrap the call so the spinner clears no matter how it resolves:
|
|
@@ -372,7 +372,7 @@ An enrollment CTA adds the pack, spins while it's in flight, then advances on su
|
|
|
372
372
|
</script>
|
|
373
373
|
```
|
|
374
374
|
|
|
375
|
-
|
|
375
|
+
The declarative button handles its in-flight state automatically; the events handle the outcome.
|
|
376
376
|
|
|
377
377
|
---
|
|
378
378
|
|
|
@@ -384,7 +384,7 @@ Combine `data-fluid-button-loading` (declarative spinner) with the events (routi
|
|
|
384
384
|
- **Registering the listener per section / per card.** Sections re-render; you'll double- or triple-fire. Attach once at layout level, or guard with a `window.__…Attached` flag.
|
|
385
385
|
- **Calling `configureCartFeedback` / the SDK without `?.` or before `DOMContentLoaded`.** The `defer`'d SDK may not be ready; guard every access with `window.FairShareSDK?.`.
|
|
386
386
|
- **Hardcoding toast strings.** Use `messages: { add: {{ 'cart.added' | t | json }} }`. Hand-quoting `{{ '…' | t }}` breaks on apostrophes and defeats localization.
|
|
387
|
-
- **Reimplementing a button spinner.**
|
|
387
|
+
- **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.
|
|
388
388
|
- **Guessing `e.detail.cart` field names.** Use `getCartItemCount()` for the count; only read cart fields you've verified in a running theme.
|
|
389
389
|
|
|
390
390
|
## Quick audit
|
|
@@ -419,11 +419,11 @@ Each hit is a candidate finding — confirm in context before flagging.
|
|
|
419
419
|
|
|
420
420
|
**Built-in feedback (Part 1)**
|
|
421
421
|
|
|
422
|
-
- [ ] `configureCartFeedback({ toast,
|
|
422
|
+
- [ ] `configureCartFeedback({ toast, messages, … })` called once, in a `DOMContentLoaded` listener
|
|
423
423
|
- [ ] `messages` sourced from `locales/*.json` via `{{ 'key' | t | json }}` (never hand-quoted)
|
|
424
424
|
- [ ] The four message keys (`cart.added` / `cart.updated` / `cart.removed` / `cart.error`) exist in every locale file
|
|
425
425
|
- [ ] Toast styled through `#fluid-toast` + `data-variant`, reusing theme CSS variables (not hardcoded brand colors)
|
|
426
|
-
- [ ]
|
|
426
|
+
- [ ] Declarative buttons use default loading; direct SDK buttons use `withButtonLoading` (no hand-rolled spinner)
|
|
427
427
|
|
|
428
428
|
**Events (Part 2)**
|
|
429
429
|
|
|
@@ -75,7 +75,6 @@ Both events expose an identical `detail` object structure. Fields marked "when k
|
|
|
75
75
|
window.addEventListener("DOMContentLoaded", () => {
|
|
76
76
|
window.FairShareSDK?.configureCartFeedback({
|
|
77
77
|
toast: true,
|
|
78
|
-
buttonLoading: true,
|
|
79
78
|
position: "bottom-right",
|
|
80
79
|
class: "theme-toast",
|
|
81
80
|
duration: 5000,
|
|
@@ -98,7 +97,7 @@ All keys optional.
|
|
|
98
97
|
| Key | Type | Default | Notes |
|
|
99
98
|
| --------------- | --------- | ---------------- | -------------------------------------------------------------------------------------------------- |
|
|
100
99
|
| `toast` | boolean | `false` | Enable the built-in toast. |
|
|
101
|
-
| `buttonLoading` | boolean | `
|
|
100
|
+
| `buttonLoading` | boolean | `true` | Set to `false` to disable the auto-spinner on `data-fluid-add-to-cart` / `data-fluid-add-enrollment-pack` buttons. |
|
|
102
101
|
| `position` | string | `bottom-center` | `bottom-center` \| `bottom-left` \| `bottom-right` \| `top-center` \| `top-left` \| `top-right`. |
|
|
103
102
|
| `class` | string | — | Extra CSS class on the toast element. |
|
|
104
103
|
| `duration` | number | `4000` | Auto-dismiss delay (ms). |
|
|
@@ -115,7 +114,7 @@ Set on the `<script id="fluid-cdn-script">` tag. Use these when no localization
|
|
|
115
114
|
| Attribute | Maps to | Notes |
|
|
116
115
|
| -------------------------------- | -------------------------- | -------------------------------------------------------- |
|
|
117
116
|
| `data-fluid-toast` | `toast` | `"true"` to enable. |
|
|
118
|
-
| `data-fluid-button-loading` | `buttonLoading` | `"
|
|
117
|
+
| `data-fluid-button-loading` | `buttonLoading` | Kill switch: `"false"` disables automatic loading. |
|
|
119
118
|
| `data-fluid-toast-class` | `class` | Custom class name. |
|
|
120
119
|
| `data-fluid-toast-position` | `position` | Same six values as `position` (default `bottom-center`). |
|
|
121
120
|
| `data-fluid-toast-duration` | `duration` | Milliseconds (default `4000`). |
|
|
@@ -171,12 +170,14 @@ The toast renders in **light DOM** (no shadow root), so plain theme CSS reaches
|
|
|
171
170
|
|
|
172
171
|
## Button-loading APIs
|
|
173
172
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
|
177
|
-
|
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
173
|
+
Declarative buttons with `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` auto-spin by default in web-widgets 0.16.0 and later.
|
|
174
|
+
|
|
175
|
+
| API | Behavior |
|
|
176
|
+
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
177
|
+
| `data-fluid-button-loading="false"` (script attr) / `buttonLoading: false` (config) | Global opt-out from automatic loading. |
|
|
178
|
+
| `data-fluid-loading-text` | Per-button label shown while loading. |
|
|
179
|
+
| `withButtonLoading(el, fn)` | Runs `fn` with the spinner shown; clears it in a `finally`. **Preferred** for custom mutations. |
|
|
180
|
+
| `setButtonLoading(el, on)` | Manual toggle; idempotent; sets `aria-busy`. Clear it yourself in a `finally`. |
|
|
180
181
|
|
|
181
182
|
The spinner inherits the button's text color, so it needs no per-theme CSS.
|
|
182
183
|
|
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.40",
|
|
4
4
|
"description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
|
|
5
5
|
"files": [
|
|
6
6
|
"dist",
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"open": "^10.0.0",
|
|
28
28
|
"ora": "^8.0.0",
|
|
29
29
|
"prompts": "^2.4.2",
|
|
30
|
-
"@fluid-app/fluid-cli": "0.1.
|
|
30
|
+
"@fluid-app/fluid-cli": "0.1.17"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
33
|
"@swc/core": "^1.15.18",
|
|
@@ -39,9 +39,9 @@
|
|
|
39
39
|
"tsdown": "^0.21.0",
|
|
40
40
|
"typescript": "^5",
|
|
41
41
|
"@fluid-app/api-client-core": "0.1.0",
|
|
42
|
-
"@fluid-app/
|
|
42
|
+
"@fluid-app/theme-schema": "0.1.0",
|
|
43
43
|
"@fluid-app/themes-api-client": "0.1.0",
|
|
44
|
-
"@fluid-app/
|
|
44
|
+
"@fluid-app/typescript-config": "0.0.0"
|
|
45
45
|
},
|
|
46
46
|
"engines": {
|
|
47
47
|
"node": ">=18.0.0"
|