@adobe-commerce/elsie 2.0.0 → 2.0.1-alpha-20260728135101
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/.elsie.js +3 -3
- package/CHANGELOG.md +385 -112
- package/LICENSE.md +257 -157
- package/README.md +4 -2
- package/__mocks__/svg.js +3 -3
- package/bin/builders/build/index.js +2 -1
- package/bin/builders/changeset/index.js +1 -1
- package/bin/builders/concurrently/index.js +1 -1
- package/bin/builders/generate/api/index.js +7 -7
- package/bin/builders/generate/component/index.js +8 -8
- package/bin/builders/generate/config/index.js +5 -5
- package/bin/builders/generate/config/templates/elsie.js +1 -1
- package/bin/builders/generate/container/index.js +7 -7
- package/bin/builders/generate/index.js +36 -36
- package/bin/builders/gql/index.js +28 -28
- package/bin/builders/gql/validate.js +116 -105
- package/bin/builders/lint/index.js +1 -1
- package/bin/builders/serve/index.js +1 -1
- package/bin/builders/storybook/index.js +9 -1
- package/bin/builders/types/index.js +1 -2
- package/bin/builders/types/validate-tsconfig.js +5 -5
- package/bin/index.js +12 -6
- package/bin/lib/cli.js +9 -8
- package/bin/lib/resolve-bin.js +9 -0
- package/bin/lib/validate-typeof.js +3 -3
- package/bin/lib/write-file.js +3 -3
- package/bin/lib/write-parent-index.js +4 -4
- package/config/eslint.mjs +2 -1
- package/config/jest.mjs +7 -2
- package/config/plugins/dts-normalize-relative-replacer.cjs +1 -1
- package/config/plugins/dts.mjs +4 -3
- package/config/prettier.json +25 -3
- package/config/setEnvVars.mjs +2 -2
- package/config/storybook/addon.js +5 -5
- package/config/storybook/components/FileTree/FileTree.jsx +4 -4
- package/config/storybook/components/FileTree/index.js +4 -4
- package/config/storybook/components/Flex/Flex.jsx +3 -3
- package/config/storybook/components/Flex/index.js +3 -3
- package/config/storybook/components/OptionsTable/OptionsTable.jsx +3 -3
- package/config/storybook/components/OptionsTable/index.js +4 -4
- package/config/storybook/components/Panel/Panel.tsx +7 -7
- package/config/storybook/components/Panel/index.ts +3 -3
- package/config/storybook/components/Screenshot/Screenshot.jsx +3 -3
- package/config/storybook/components/Screenshot/index.js +4 -4
- package/config/storybook/components/Steps/Steps.jsx +3 -3
- package/config/storybook/components/Steps/index.js +4 -4
- package/config/storybook/components/StoryWrapper/StoryWrapper.jsx +3 -3
- package/config/storybook/components/StoryWrapper/index.js +3 -3
- package/config/storybook/components/Summary/Summary.jsx +3 -3
- package/config/storybook/components/Summary/index.js +3 -3
- package/config/storybook/components/Variants/Variants.jsx +11 -7
- package/config/storybook/components/Variants/index.js +3 -3
- package/config/storybook/manager.js +3 -3
- package/config/storybook/preview.jsx +3 -3
- package/config/storybook/theming/fonts.css +12 -4
- package/config/storybook/theming/preview.css +3 -1
- package/config/storybook/theming/theme.js +3 -3
- package/config/vite.mjs +53 -26
- package/package.json +36 -34
- package/src/components/Accordion/Accordion.css +1 -1
- package/src/components/Accordion/Accordion.stories.tsx +18 -18
- package/src/components/Accordion/Accordion.tsx +12 -8
- package/src/components/Accordion/index.ts +3 -3
- package/src/components/ActionButton/ActionButton.stories.tsx +8 -8
- package/src/components/ActionButton/ActionButton.tsx +7 -5
- package/src/components/ActionButton/index.ts +3 -3
- package/src/components/ActionButtonGroup/ActionButtonGroup.stories.tsx +3 -3
- package/src/components/ActionButtonGroup/ActionButtonGroup.tsx +2 -2
- package/src/components/ActionButtonGroup/index.ts +3 -3
- package/src/components/AlertBanner/AlertBanner.stories.tsx +6 -6
- package/src/components/AlertBanner/AlertBanner.tsx +12 -10
- package/src/components/AlertBanner/index.ts +3 -3
- package/src/components/Breadcrumbs/Breadcrumbs.stories.tsx +14 -14
- package/src/components/Breadcrumbs/Breadcrumbs.tsx +3 -3
- package/src/components/Breadcrumbs/index.ts +3 -3
- package/src/components/Button/Button.mdx +24 -11
- package/src/components/Button/Button.stories.tsx +6 -6
- package/src/components/Button/Button.tsx +7 -8
- package/src/components/Button/index.ts +3 -3
- package/src/components/Card/Card.stories.tsx +6 -6
- package/src/components/Card/Card.tsx +3 -3
- package/src/components/Card/index.ts +3 -3
- package/src/components/CartItem/CartItem.stories.tsx +12 -12
- package/src/components/CartItem/CartItem.tsx +4 -2
- package/src/components/CartItem/CartItemSkeleton.tsx +3 -3
- package/src/components/CartItem/index.ts +3 -3
- package/src/components/CartList/CartList.tsx +3 -3
- package/src/components/CartList/index.ts +3 -3
- package/src/components/Checkbox/Checkbox.stories.tsx +17 -14
- package/src/components/Checkbox/Checkbox.tsx +8 -6
- package/src/components/Checkbox/index.ts +3 -3
- package/src/components/ColorSwatch/ColorSwatch.css +8 -4
- package/src/components/ColorSwatch/ColorSwatch.stories.tsx +6 -6
- package/src/components/ColorSwatch/ColorSwatch.tsx +8 -6
- package/src/components/ColorSwatch/index.ts +3 -3
- package/src/components/ContentGrid/ContentGrid.css +15 -15
- package/src/components/ContentGrid/ContentGrid.stories.tsx +4 -4
- package/src/components/ContentGrid/ContentGrid.tsx +3 -3
- package/src/components/ContentGrid/index.ts +3 -3
- package/src/components/Divider/Divider.stories.tsx +7 -4
- package/src/components/Divider/Divider.tsx +3 -3
- package/src/components/Divider/index.ts +4 -4
- package/src/components/Field/Field.stories.tsx +7 -7
- package/src/components/Field/Field.tsx +4 -2
- package/src/components/Field/index.ts +3 -3
- package/src/components/Header/Header.stories.tsx +9 -10
- package/src/components/Header/Header.tsx +11 -7
- package/src/components/Header/index.ts +3 -3
- package/src/components/Icon/Icon.stories.helpers.jsx +4 -4
- package/src/components/Icon/Icon.stories.tsx +74 -60
- package/src/components/Icon/Icon.tsx +77 -44
- package/src/components/Icon/index.ts +3 -3
- package/src/components/IllustratedMessage/IllustratedMessage.stories.tsx +8 -8
- package/src/components/IllustratedMessage/IllustratedMessage.tsx +7 -5
- package/src/components/IllustratedMessage/index.ts +3 -3
- package/src/components/Image/Image.stories.tsx +3 -3
- package/src/components/Image/Image.tsx +4 -4
- package/src/components/Image/index.ts +3 -3
- package/src/components/ImageSwatch/ImageSwatch.css +8 -4
- package/src/components/ImageSwatch/ImageSwatch.stories.tsx +10 -10
- package/src/components/ImageSwatch/ImageSwatch.tsx +25 -23
- package/src/components/ImageSwatch/index.ts +3 -3
- package/src/components/InLineAlert/InLineAlert.stories.tsx +12 -7
- package/src/components/InLineAlert/InLineAlert.tsx +4 -2
- package/src/components/InLineAlert/index.ts +3 -3
- package/src/components/Incrementer/Incrementer.stories.tsx +9 -9
- package/src/components/Incrementer/Incrementer.tsx +75 -37
- package/src/components/Incrementer/index.ts +3 -3
- package/src/components/Input/Input.css +4 -1
- package/src/components/Input/Input.stories.tsx +5 -5
- package/src/components/Input/Input.tsx +5 -3
- package/src/components/Input/index.ts +3 -3
- package/src/components/InputDate/InputDate.tsx +3 -3
- package/src/components/InputDate/index.ts +3 -3
- package/src/components/InputFile/InputFile.css +16 -16
- package/src/components/InputFile/InputFile.stories.tsx +21 -16
- package/src/components/InputFile/InputFile.tsx +8 -6
- package/src/components/InputFile/index.ts +5 -5
- package/src/components/InputPassword/InputPassword.stories.tsx +4 -4
- package/src/components/InputPassword/InputPassword.tsx +5 -4
- package/src/components/InputPassword/PasswordStatusIndicator/PasswordStatusIndicator.tsx +1 -1
- package/src/components/InputPassword/PasswordStatusIndicator/index.ts +3 -3
- package/src/components/InputPassword/index.ts +3 -3
- package/src/components/Modal/Modal.stories.tsx +27 -16
- package/src/components/Modal/Modal.tsx +10 -11
- package/src/components/Modal/index.ts +3 -3
- package/src/components/MultiSelect/MultiSelect.stories.tsx +15 -15
- package/src/components/MultiSelect/MultiSelect.tsx +15 -15
- package/src/components/Pagination/Pagination.css +1 -1
- package/src/components/Pagination/Pagination.stories.tsx +0 -1
- package/src/components/Pagination/Pagination.tsx +17 -12
- package/src/components/Pagination/PaginationButton.tsx +2 -3
- package/src/components/Pagination/index.ts +3 -3
- package/src/components/Picker/Picker.css +3 -1
- package/src/components/Picker/Picker.stories.tsx +1 -1
- package/src/components/Picker/Picker.tsx +8 -6
- package/src/components/Picker/index.ts +3 -3
- package/src/components/Portal/Portal.stories.tsx +50 -44
- package/src/components/Portal/Portal.tsx +4 -4
- package/src/components/Price/Price.stories.tsx +3 -3
- package/src/components/Price/Price.tsx +4 -2
- package/src/components/Price/index.ts +3 -3
- package/src/components/PriceRange/PriceRange.stories.tsx +3 -3
- package/src/components/PriceRange/PriceRange.tsx +8 -6
- package/src/components/PriceRange/index.ts +3 -3
- package/src/components/ProductItemCard/ProductItemCard.tsx +4 -2
- package/src/components/ProductItemCard/ProductItemCardSkeleton.tsx +16 -16
- package/src/components/ProductItemCard/index.ts +4 -4
- package/src/components/ProgressSpinner/ProgressSpinner.stories.tsx +8 -8
- package/src/components/ProgressSpinner/ProgressSpinner.tsx +7 -5
- package/src/components/ProgressSpinner/index.ts +3 -3
- package/src/components/RadioButton/RadioButton.stories.tsx +1 -1
- package/src/components/RadioButton/RadioButton.tsx +4 -2
- package/src/components/Skeleton/Skeleton.stories.tsx +4 -4
- package/src/components/Skeleton/Skeleton.tsx +11 -7
- package/src/components/Skeleton/index.ts +3 -3
- package/src/components/Table/Table.css +106 -99
- package/src/components/Table/Table.stories.tsx +404 -227
- package/src/components/Table/Table.tsx +11 -7
- package/src/components/Table/index.ts +4 -4
- package/src/components/Tag/Tag.stories.tsx +6 -6
- package/src/components/Tag/Tag.tsx +7 -5
- package/src/components/Tag/index.ts +3 -3
- package/src/components/TextArea/TextArea.css +3 -1
- package/src/components/TextArea/TextArea.stories.tsx +9 -6
- package/src/components/TextArea/TextArea.tsx +3 -3
- package/src/components/TextArea/index.ts +3 -3
- package/src/components/TextSwatch/TextSwatch.css +4 -2
- package/src/components/TextSwatch/TextSwatch.stories.tsx +8 -8
- package/src/components/TextSwatch/TextSwatch.tsx +12 -7
- package/src/components/TextSwatch/index.ts +3 -3
- package/src/components/ToggleButton/ToggleButton.css +6 -2
- package/src/components/ToggleButton/ToggleButton.stories.tsx +10 -6
- package/src/components/ToggleButton/ToggleButton.tsx +8 -3
- package/src/components/ToggleButton/index.ts +3 -3
- package/src/components/UIProvider/UIProvider.css +3 -2
- package/src/components/UIProvider/UIProvider.tsx +11 -7
- package/src/components/UIProvider/debugger.css +5 -6
- package/src/components/UIProvider/index.ts +3 -3
- package/src/docs/API/event-bus.mdx +64 -37
- package/src/docs/API/graphql.mdx +69 -36
- package/src/docs/API/initializer.mdx +58 -35
- package/src/docs/API/render.mdx +45 -32
- package/src/docs/Design/colors.mdx +10 -12
- package/src/docs/Design/grid.mdx +41 -14
- package/src/docs/Design/overview.mdx +20 -4
- package/src/docs/Design/shapes.mdx +8 -7
- package/src/docs/Design/spacing.mdx +3 -1
- package/src/docs/Design/typography.mdx +3 -2
- package/src/docs/Utilities/VComponent.mdx +27 -10
- package/src/docs/Utilities/classList.mdx +7 -5
- package/src/docs/Utilities/debounce.mdx +6 -7
- package/src/docs/Utilities/getCookie.mdx +1 -2
- package/src/docs/Utilities/getFormErrors.mdx +1 -2
- package/src/docs/Utilities/getFormValues.mdx +1 -2
- package/src/docs/Utilities/getPathValue.mdx +2 -4
- package/src/docs/Utilities/links.mdx +16 -7
- package/src/docs/cli-usage.mdx +8 -3
- package/src/docs/components/overview.mdx +14 -4
- package/src/docs/quick-start.mdx +69 -22
- package/src/docs/slots.mdx +74 -37
- package/src/docs/welcome.mdx +13 -4
- package/src/i18n/index.ts +3 -3
- package/src/lib/aem/assets.ts +9 -9
- package/src/lib/aem/configs.ts +16 -8
- package/src/lib/classes.ts +4 -4
- package/src/lib/config.ts +3 -3
- package/src/lib/debounce.ts +3 -3
- package/src/lib/deepmerge.ts +6 -13
- package/src/lib/deviceUtils.ts +3 -3
- package/src/lib/form-values.ts +3 -3
- package/src/lib/get-price-formatter.ts +8 -3
- package/src/lib/i18n.ts +3 -3
- package/src/lib/image-params-keymap.ts +4 -5
- package/src/lib/initializer.ts +11 -12
- package/src/lib/is-number.ts +3 -3
- package/src/lib/locale-config.ts +4 -4
- package/src/lib/render.tsx +14 -8
- package/src/lib/resolve-image.ts +19 -16
- package/src/lib/signals.ts +4 -4
- package/src/lib/slot.tsx +34 -27
- package/src/lib/tests.tsx +6 -8
- package/src/lib/types.ts +3 -3
- package/src/lib/vcomponent.tsx +3 -3
- package/src/shims/importmap.js +3107 -20
- package/static/assets/images/index.ts +3 -3
- package/storybook-stories.js +3 -3
- package/tests/__mocks__/browserMocks.ts +3 -3
- package/tests/__mocks__/fileMocks.ts +3 -3
|
@@ -5,7 +5,10 @@ import { Meta, Unstyled } from '@storybook/addon-docs/blocks';
|
|
|
5
5
|
|
|
6
6
|
# Event Bus
|
|
7
7
|
|
|
8
|
-
The Event Bus provides a communication system for different parts of your
|
|
8
|
+
The Event Bus provides a communication system for different parts of your
|
|
9
|
+
application to exchange messages and stay synchronized. It enables event-driven
|
|
10
|
+
architecture for drop-ins, allowing Containers to react to changes from other
|
|
11
|
+
Containers and communicate data changes to the storefront.
|
|
9
12
|
|
|
10
13
|
## Import
|
|
11
14
|
|
|
@@ -15,7 +18,6 @@ From drop-in project using the SDK
|
|
|
15
18
|
import { events } from '@adobe-commerce/elsie/lib';
|
|
16
19
|
```
|
|
17
20
|
|
|
18
|
-
|
|
19
21
|
From integration project (storefront)
|
|
20
22
|
|
|
21
23
|
```js
|
|
@@ -39,6 +41,7 @@ eventListener.off();
|
|
|
39
41
|
```
|
|
40
42
|
|
|
41
43
|
**Example:**
|
|
44
|
+
|
|
42
45
|
```ts
|
|
43
46
|
// Listen for cart updates
|
|
44
47
|
const cartListener = events.on('cart/data', (cartData) => {
|
|
@@ -64,14 +67,15 @@ events.emit('<event>', payload);
|
|
|
64
67
|
```
|
|
65
68
|
|
|
66
69
|
**Examples:**
|
|
70
|
+
|
|
67
71
|
```ts
|
|
68
72
|
// Emit cart data
|
|
69
73
|
const cartData = {
|
|
70
74
|
id: 'cart-123',
|
|
71
75
|
totalQuantity: 2,
|
|
72
76
|
items: [
|
|
73
|
-
{ uid: 'item-1', quantity: 1, sku: 'PROD-001', name: 'Product Name' }
|
|
74
|
-
]
|
|
77
|
+
{ uid: 'item-1', quantity: 1, sku: 'PROD-001', name: 'Product Name' },
|
|
78
|
+
],
|
|
75
79
|
};
|
|
76
80
|
|
|
77
81
|
events.emit('cart/data', cartData);
|
|
@@ -86,6 +90,7 @@ const lastPayload = events.lastPayload('<event>');
|
|
|
86
90
|
```
|
|
87
91
|
|
|
88
92
|
**Example:**
|
|
93
|
+
|
|
89
94
|
```ts
|
|
90
95
|
// Get the current cart state without waiting for an event
|
|
91
96
|
const currentCart = events.lastPayload('cart/data');
|
|
@@ -108,43 +113,59 @@ events.enableLogger(true);
|
|
|
108
113
|
|
|
109
114
|
### Eager Loading
|
|
110
115
|
|
|
111
|
-
Execute the event handler immediately with the last known payload when
|
|
116
|
+
Execute the event handler immediately with the last known payload when
|
|
117
|
+
subscribing. This is useful for getting the current state without waiting for
|
|
118
|
+
the next event.
|
|
112
119
|
|
|
113
120
|
```ts
|
|
114
121
|
// Handler will execute immediately if there's a previous payload
|
|
115
|
-
const listener = events.on(
|
|
116
|
-
|
|
117
|
-
|
|
122
|
+
const listener = events.on(
|
|
123
|
+
'cart/data',
|
|
124
|
+
(cartData) => {
|
|
125
|
+
console.log('Cart data received:', cartData);
|
|
126
|
+
},
|
|
127
|
+
{ eager: true },
|
|
128
|
+
);
|
|
118
129
|
```
|
|
119
130
|
|
|
120
131
|
**Use Cases:**
|
|
132
|
+
|
|
121
133
|
- Initialize UI components with current state
|
|
122
134
|
- Avoid waiting for the first event emission
|
|
123
135
|
- Ensure components have the latest data on mount
|
|
124
136
|
|
|
125
137
|
### Event Scoping
|
|
126
138
|
|
|
127
|
-
Create namespaced events to avoid conflicts between different parts of your
|
|
139
|
+
Create namespaced events to avoid conflicts between different parts of your
|
|
140
|
+
application.
|
|
128
141
|
|
|
129
142
|
```ts
|
|
130
143
|
// Subscribe to a scoped event
|
|
131
|
-
const scopedListener = events.on(
|
|
132
|
-
|
|
133
|
-
|
|
144
|
+
const scopedListener = events.on(
|
|
145
|
+
'data/update',
|
|
146
|
+
(data) => {
|
|
147
|
+
console.log('Scoped data received:', data);
|
|
148
|
+
},
|
|
149
|
+
{ scope: 'feature-a' },
|
|
150
|
+
);
|
|
134
151
|
|
|
135
152
|
// Emit a scoped event
|
|
136
153
|
events.emit('data/update', payload, { scope: 'feature-a' });
|
|
137
154
|
|
|
138
155
|
// Get last payload for a scoped event
|
|
139
|
-
const lastScopedData = events.lastPayload('data/update', {
|
|
156
|
+
const lastScopedData = events.lastPayload('data/update', {
|
|
157
|
+
scope: 'feature-a',
|
|
158
|
+
});
|
|
140
159
|
```
|
|
141
160
|
|
|
142
|
-
**Scoped Event Names:**
|
|
143
|
-
|
|
161
|
+
**Scoped Event Names:** When using scopes, the actual event name becomes
|
|
162
|
+
`scope/event`. For example:
|
|
163
|
+
|
|
144
164
|
- `'feature-a/data/update'` instead of `'data/update'`
|
|
145
165
|
- `'module-b/user/action'` instead of `'user/action'`
|
|
146
166
|
|
|
147
167
|
**Use Cases:**
|
|
168
|
+
|
|
148
169
|
- Separate different features or modules
|
|
149
170
|
- Different contexts within the same application
|
|
150
171
|
- Component-specific event handling
|
|
@@ -155,32 +176,38 @@ Use both eager loading and scoping together for powerful event handling.
|
|
|
155
176
|
|
|
156
177
|
```ts
|
|
157
178
|
// Subscribe to a scoped event with eager loading
|
|
158
|
-
const listener = events.on(
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
179
|
+
const listener = events.on(
|
|
180
|
+
'locale',
|
|
181
|
+
(locale) => {
|
|
182
|
+
console.log('Current locale:', locale);
|
|
183
|
+
},
|
|
184
|
+
{
|
|
185
|
+
eager: true,
|
|
186
|
+
scope: 'user-preferences',
|
|
187
|
+
},
|
|
188
|
+
);
|
|
164
189
|
```
|
|
165
190
|
|
|
166
191
|
## Event-Driven Drop-ins
|
|
167
192
|
|
|
168
|
-
The Event Bus enables drop-ins to be truly event-driven, allowing for loose
|
|
193
|
+
The Event Bus enables drop-ins to be truly event-driven, allowing for loose
|
|
194
|
+
coupling between components and seamless communication across the application.
|
|
169
195
|
|
|
170
196
|
### Container-to-Container Communication
|
|
171
197
|
|
|
172
|
-
Containers can react to changes from other Containers, enabling complex
|
|
198
|
+
Containers can react to changes from other Containers, enabling complex
|
|
199
|
+
interactions without direct dependencies.
|
|
173
200
|
|
|
174
201
|
```ts
|
|
175
202
|
// Product Container: Emits when a product is added to cart
|
|
176
203
|
function ProductContainer() {
|
|
177
204
|
const handleAddToCart = (product) => {
|
|
178
205
|
// Add to cart logic...
|
|
179
|
-
|
|
206
|
+
|
|
180
207
|
// Notify other containers about the cart change
|
|
181
208
|
events.emit('cart/data', updatedCartData);
|
|
182
209
|
};
|
|
183
|
-
|
|
210
|
+
|
|
184
211
|
return (
|
|
185
212
|
<button onClick={() => handleAddToCart(product)}>
|
|
186
213
|
Add to Cart
|
|
@@ -195,10 +222,10 @@ function CartContainer() {
|
|
|
195
222
|
updateCartDisplay(cartData);
|
|
196
223
|
updateCartBadge(cartData.totalQuantity);
|
|
197
224
|
}, { eager: true });
|
|
198
|
-
|
|
225
|
+
|
|
199
226
|
return () => cartListener.off();
|
|
200
227
|
}, []);
|
|
201
|
-
|
|
228
|
+
|
|
202
229
|
return <CartDisplay />;
|
|
203
230
|
}
|
|
204
231
|
|
|
@@ -208,35 +235,36 @@ function MiniCartContainer() {
|
|
|
208
235
|
const cartListener = events.on('cart/data', (cartData) => {
|
|
209
236
|
updateMiniCart(cartData);
|
|
210
237
|
}, { eager: true });
|
|
211
|
-
|
|
238
|
+
|
|
212
239
|
return () => cartListener.off();
|
|
213
240
|
}, []);
|
|
214
|
-
|
|
241
|
+
|
|
215
242
|
return <MiniCart />;
|
|
216
243
|
}
|
|
217
244
|
```
|
|
218
245
|
|
|
219
246
|
### Storefront Communication
|
|
220
247
|
|
|
221
|
-
Drop-ins can communicate data changes to the storefront, enabling seamless
|
|
248
|
+
Drop-ins can communicate data changes to the storefront, enabling seamless
|
|
249
|
+
integration with the host application.
|
|
222
250
|
|
|
223
251
|
```ts
|
|
224
252
|
// Authentication Container: Notifies storefront of login/logout
|
|
225
253
|
function AuthContainer() {
|
|
226
254
|
const handleLogin = (userData) => {
|
|
227
255
|
// Login logic...
|
|
228
|
-
|
|
256
|
+
|
|
229
257
|
// Notify storefront of authentication change
|
|
230
258
|
events.emit('authenticated', true);
|
|
231
259
|
};
|
|
232
|
-
|
|
260
|
+
|
|
233
261
|
const handleLogout = () => {
|
|
234
262
|
// Logout logic...
|
|
235
|
-
|
|
263
|
+
|
|
236
264
|
// Notify storefront of authentication change
|
|
237
265
|
events.emit('authenticated', false);
|
|
238
266
|
};
|
|
239
|
-
|
|
267
|
+
|
|
240
268
|
return <AuthForm onLogin={handleLogin} onLogout={handleLogout} />;
|
|
241
269
|
}
|
|
242
270
|
|
|
@@ -253,11 +281,10 @@ const authListener = events.on('authenticated', (isAuthenticated) => {
|
|
|
253
281
|
}, { eager: true });
|
|
254
282
|
```
|
|
255
283
|
|
|
256
|
-
|
|
257
|
-
|
|
258
284
|
## Best Practices
|
|
259
285
|
|
|
260
|
-
1. **Always unsubscribe** from events when components unmount to prevent memory
|
|
286
|
+
1. **Always unsubscribe** from events when components unmount to prevent memory
|
|
287
|
+
leaks
|
|
261
288
|
2. **Use scopes** to organize events by feature or component
|
|
262
289
|
3. **Enable eager loading** when you need immediate access to current state
|
|
263
290
|
4. **Use descriptive event names** that clearly indicate what data they contain
|
package/src/docs/API/graphql.mdx
CHANGED
|
@@ -5,12 +5,16 @@ import { Meta, Unstyled } from '@storybook/addon-docs/blocks';
|
|
|
5
5
|
|
|
6
6
|
# GraphQL Extensibility API
|
|
7
7
|
|
|
8
|
-
The GraphQL Extensibility API allows developers to extend existing GraphQL
|
|
9
|
-
|
|
8
|
+
The GraphQL Extensibility API allows developers to extend existing GraphQL
|
|
9
|
+
operations used by a Drop-in to meet additional data requirements without
|
|
10
|
+
increasing code complexity or negatively impacting performance. This API
|
|
11
|
+
provides a flexible and efficient way to customize GraphQL Fragments by
|
|
12
|
+
integrating build-time modifications into the storefront's development pipeline.
|
|
10
13
|
|
|
11
14
|
## Extend your Drop-in GraphQL Fragments
|
|
12
15
|
|
|
13
|
-
To enable GraphQL Fragments to be extensible in your Drop-in, follow these
|
|
16
|
+
To enable GraphQL Fragments to be extensible in your Drop-in, follow these
|
|
17
|
+
steps:
|
|
14
18
|
|
|
15
19
|
### Step 1: Define Your Fragments
|
|
16
20
|
|
|
@@ -34,7 +38,8 @@ export const MY_FRAGMENT = `
|
|
|
34
38
|
|
|
35
39
|
### Step 2: Create Fragments Manifest File
|
|
36
40
|
|
|
37
|
-
Next, create a new file for your project to list all the fragments you want to
|
|
41
|
+
Next, create a new file for your project to list all the fragments you want to
|
|
42
|
+
expose.
|
|
38
43
|
|
|
39
44
|
```ts
|
|
40
45
|
// ./src/api/fragments.ts
|
|
@@ -71,18 +76,20 @@ module.exports = {
|
|
|
71
76
|
},
|
|
72
77
|
schema: {
|
|
73
78
|
endpoint: process.env.ENDPOINT,
|
|
74
|
-
headers: {}
|
|
75
|
-
}
|
|
79
|
+
headers: {},
|
|
80
|
+
},
|
|
76
81
|
};
|
|
77
82
|
```
|
|
78
83
|
|
|
79
84
|
## Extend the Data module
|
|
80
85
|
|
|
81
|
-
Now that we have made our fragments extensible, we must extend the data model
|
|
86
|
+
Now that we have made our fragments extensible, we must extend the data model
|
|
87
|
+
used in our Drop-ins.
|
|
82
88
|
|
|
83
89
|
### Step 1: Define Typing to the Initializer API
|
|
84
90
|
|
|
85
|
-
First, add the typing to your initializer API in
|
|
91
|
+
First, add the typing to your initializer API in
|
|
92
|
+
`./src/api/initialize/initialize.ts`.
|
|
86
93
|
|
|
87
94
|
```ts
|
|
88
95
|
// ./src/api/initialize/initialize.ts
|
|
@@ -97,7 +104,7 @@ type ConfigProps = {
|
|
|
97
104
|
// 👇 add your models configuration
|
|
98
105
|
models?: {
|
|
99
106
|
MyModel?: Model<MyModel>;
|
|
100
|
-
}
|
|
107
|
+
};
|
|
101
108
|
};
|
|
102
109
|
|
|
103
110
|
export const initialize = new Initializer<ConfigProps>({
|
|
@@ -114,7 +121,8 @@ export const config = initialize.config;
|
|
|
114
121
|
|
|
115
122
|
### Step 2: Extend the Data Transformer
|
|
116
123
|
|
|
117
|
-
Then, use the configuration to extend the data transformer the model uses by
|
|
124
|
+
Then, use the configuration to extend the data transformer the model uses by
|
|
125
|
+
deep merging the existing data transformation with the new configuration.
|
|
118
126
|
|
|
119
127
|
```ts
|
|
120
128
|
// ./src/data/transforms/transform-my-model.ts
|
|
@@ -130,7 +138,7 @@ export function transformMyModel(data: any): MyModel {
|
|
|
130
138
|
// Merge custom transformer, if provided
|
|
131
139
|
return merge(
|
|
132
140
|
model, // default transformer
|
|
133
|
-
config.getConfig().models?.MyModel?.transformer?.(data) // custom transformer
|
|
141
|
+
config.getConfig().models?.MyModel?.transformer?.(data), // custom transformer
|
|
134
142
|
);
|
|
135
143
|
}
|
|
136
144
|
```
|
|
@@ -139,8 +147,11 @@ export function transformMyModel(data: any): MyModel {
|
|
|
139
147
|
|
|
140
148
|
# Using the GraphQL Extensibility Feature in Your Storefront
|
|
141
149
|
|
|
142
|
-
By extending the GraphQL Fragments and Models of drop-ins, you can leverage the
|
|
143
|
-
|
|
150
|
+
By extending the GraphQL Fragments and Models of drop-ins, you can leverage the
|
|
151
|
+
drop-in's existing GraphQL operations and add extra fields needed to meet your
|
|
152
|
+
specific business requirements. This approach enhances the user experience while
|
|
153
|
+
maintaining code simplicity and performance efficiency since all modifications
|
|
154
|
+
are integrated into the storefront's development build-time pipeline.
|
|
144
155
|
|
|
145
156
|
## Extend Drop-in's Fragments and Models
|
|
146
157
|
|
|
@@ -148,33 +159,43 @@ Follow these steps to extend the GraphQL Fragment and Model in your Drop-in:
|
|
|
148
159
|
|
|
149
160
|
### Step 1: Extend the GraphQL Fragment
|
|
150
161
|
|
|
151
|
-
Use the `overrideGQLOperations` function to extend the existing GraphQL
|
|
162
|
+
Use the `overrideGQLOperations` function to extend the existing GraphQL
|
|
163
|
+
Fragment, allowing you to add fields to the fragment as needed.
|
|
152
164
|
|
|
153
|
-
The `overrideGQLOperations` functions accept an array of configuration objects
|
|
165
|
+
The `overrideGQLOperations` functions accept an array of configuration objects
|
|
166
|
+
where you must specify:
|
|
154
167
|
|
|
155
168
|
#### npm: string
|
|
156
169
|
|
|
157
170
|
The node module name of the drop-in. i.e. "@dropins/my-dropin".
|
|
158
171
|
|
|
159
|
-
#### operations: string[]
|
|
172
|
+
#### operations: string[]
|
|
160
173
|
|
|
161
|
-
An array of string or template literal with operations.
|
|
174
|
+
An array of string or template literal with operations.
|
|
162
175
|
|
|
163
176
|
- Only one definition can be provided in the operation.
|
|
164
|
-
- These must match the operation name as provided by the drop-in. i.e.
|
|
165
|
-
|
|
166
|
-
-
|
|
177
|
+
- These must match the operation name as provided by the drop-in. i.e.
|
|
178
|
+
`MY_FRAGMENT`.
|
|
179
|
+
- The operations must be valid GraphQL operations, such as Fragment. i.e.
|
|
180
|
+
`fragment MY_FRAGMENT on FragmentInterface { ... }`.
|
|
181
|
+
- In the case of a Fragment, the fragment name must match the same interface as
|
|
182
|
+
the drop-in. i.e. `FragmentInterface`.
|
|
167
183
|
- If an existing field that has variables is used:
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
184
|
+
- If not variables are provided, the existing variables will be used. i.e.
|
|
185
|
+
`favorites(page: 1) { ... }`.
|
|
186
|
+
- If new variables are provided, the new variable will be added. i.e.
|
|
187
|
+
`favorites(page: 1, offset: 5) { ... }`.
|
|
188
|
+
- If the existing variables are changed, the new variables will be used. i.e.
|
|
189
|
+
`favorites(page: 2) { ... }`.
|
|
171
190
|
|
|
172
191
|
#### skipFragments: string[]
|
|
173
192
|
|
|
174
|
-
An array of fragment names to remove from the drop-in's exported fragments file.
|
|
193
|
+
An array of fragment names to remove from the drop-in's exported fragments file.
|
|
194
|
+
When a fragment name is listed in `skipFragments`:
|
|
175
195
|
|
|
176
196
|
- The fragment definition is removed from its exported variable.
|
|
177
|
-
- All references (fragment spreads) to the skipped fragment are also removed
|
|
197
|
+
- All references (fragment spreads) to the skipped fragment are also removed
|
|
198
|
+
from other operations in the same file.
|
|
178
199
|
|
|
179
200
|
```js
|
|
180
201
|
import { overrideGQLOperations } from '@dropins/build-tools/gql-extend.js';
|
|
@@ -189,10 +210,12 @@ overrideGQLOperations([
|
|
|
189
210
|
|
|
190
211
|
#### Using `skipFragments` and `operations` together
|
|
191
212
|
|
|
192
|
-
When both `skipFragments` and `operations` are provided for the same fragment
|
|
213
|
+
When both `skipFragments` and `operations` are provided for the same fragment
|
|
214
|
+
name, the fragment is **fully replaced** rather than merged:
|
|
193
215
|
|
|
194
216
|
1. `skipFragments` removes the original fragment definition entirely.
|
|
195
|
-
2. `operations` writes the new fragment definition directly, without merging it
|
|
217
|
+
2. `operations` writes the new fragment definition directly, without merging it
|
|
218
|
+
with the (now-removed) original.
|
|
196
219
|
|
|
197
220
|
```js
|
|
198
221
|
import { overrideGQLOperations } from '@dropins/build-tools/gql-extend.js';
|
|
@@ -201,18 +224,25 @@ overrideGQLOperations([
|
|
|
201
224
|
{
|
|
202
225
|
npm: '@dropins/my-dropin',
|
|
203
226
|
skipFragments: ['MY_FRAGMENT'],
|
|
204
|
-
operations: [
|
|
227
|
+
operations: [
|
|
228
|
+
`
|
|
205
229
|
fragment MY_FRAGMENT on FragmentInterface {
|
|
206
230
|
fragmentName
|
|
207
231
|
}
|
|
208
|
-
|
|
232
|
+
`,
|
|
233
|
+
],
|
|
209
234
|
},
|
|
210
235
|
]);
|
|
211
236
|
```
|
|
212
237
|
|
|
213
|
-
In the example above, the original `MY_FRAGMENT` is fully removed by
|
|
238
|
+
In the example above, the original `MY_FRAGMENT` is fully removed by
|
|
239
|
+
`skipFragments` and then replaced by the new definition containing only
|
|
240
|
+
`fragmentName`.
|
|
214
241
|
|
|
215
|
-
> **Note:** If `skipFragments` is used without a matching `operations` entry,
|
|
242
|
+
> **Note:** If `skipFragments` is used without a matching `operations` entry,
|
|
243
|
+
> the fragment is simply removed (emptied). If `operations` is used without
|
|
244
|
+
> `skipFragments`, the new fields are **merged** into the existing fragment
|
|
245
|
+
> definition.
|
|
216
246
|
|
|
217
247
|
```js
|
|
218
248
|
import overrideGQLOperations from '@dropins/build-tools/gql-extend.js';
|
|
@@ -220,7 +250,8 @@ import overrideGQLOperations from '@dropins/build-tools/gql-extend.js';
|
|
|
220
250
|
overrideGQLOperations([
|
|
221
251
|
{
|
|
222
252
|
npm: '@dropins/my-dropin',
|
|
223
|
-
operations: [
|
|
253
|
+
operations: [
|
|
254
|
+
`
|
|
224
255
|
fragment MY_FRAGMENT on FragmentInterface {
|
|
225
256
|
age
|
|
226
257
|
|
|
@@ -228,14 +259,17 @@ overrideGQLOperations([
|
|
|
228
259
|
quantity
|
|
229
260
|
}
|
|
230
261
|
}
|
|
231
|
-
|
|
262
|
+
`,
|
|
263
|
+
],
|
|
232
264
|
},
|
|
233
265
|
]);
|
|
234
266
|
```
|
|
235
267
|
|
|
236
268
|
### Step 2: Extend the Data Model
|
|
237
269
|
|
|
238
|
-
Next, update the data models to include the new fields added to the fragment,
|
|
270
|
+
Next, update the data models to include the new fields added to the fragment,
|
|
271
|
+
ensuring that the additional data is correctly processed and available for use
|
|
272
|
+
in the drop-in. i.e., Slots, Event Bus, etc.
|
|
239
273
|
|
|
240
274
|
```js
|
|
241
275
|
import * as api from '@dropins/storefront-cart/api.js';
|
|
@@ -245,14 +279,13 @@ initializers.register(api.initialize, {
|
|
|
245
279
|
MyModel: {
|
|
246
280
|
transformer: (data) => ({
|
|
247
281
|
age: data?.age,
|
|
248
|
-
favorites: data.favorites.map((favorite) => ({
|
|
282
|
+
favorites: data.favorites.map((favorite) => ({
|
|
249
283
|
quantity: favorite.quantity,
|
|
250
284
|
})),
|
|
251
285
|
}),
|
|
252
286
|
},
|
|
253
287
|
},
|
|
254
288
|
});
|
|
255
|
-
|
|
256
289
|
```
|
|
257
290
|
|
|
258
291
|
</Unstyled>
|
|
@@ -45,30 +45,42 @@ window.addEventListener('load', initializers.mount);
|
|
|
45
45
|
|
|
46
46
|
## `setImageParamKeys(params)`
|
|
47
47
|
|
|
48
|
-
The `setImageParamKeys` method is part of the initializers module in the
|
|
49
|
-
It allows you to set image parameters globally for all
|
|
48
|
+
The `setImageParamKeys` method is part of the initializers module in the
|
|
49
|
+
`@dropins/tools` package. It allows you to set image parameters globally for all
|
|
50
|
+
drop-ins that use the Image component.
|
|
50
51
|
|
|
51
52
|
### Default Behavior
|
|
52
53
|
|
|
53
|
-
By default, Fastly parameters are used if `setImageParamKeys` is not called or
|
|
54
|
+
By default, Fastly parameters are used if `setImageParamKeys` is not called or
|
|
55
|
+
if no parameters are provided.
|
|
54
56
|
|
|
55
57
|
### Parameters
|
|
56
58
|
|
|
57
59
|
- `params` - `{ [key: string]: string | ((data: any) => [string, string]) }`
|
|
58
|
-
- An object of key-value pairs to map image parameters to their respective
|
|
59
|
-
|
|
60
|
+
- An object of key-value pairs to map image parameters to their respective
|
|
61
|
+
keys in the URL.
|
|
62
|
+
- The value can be a string or a function that takes the parameter value as an
|
|
63
|
+
argument and returns a tuple of the new key and transformed value.
|
|
60
64
|
|
|
61
65
|
### Functionality
|
|
62
66
|
|
|
63
|
-
- If a parameter key is provided via `setImageParamKeys`, it is used in
|
|
64
|
-
|
|
65
|
-
- If a
|
|
66
|
-
|
|
67
|
-
- If a
|
|
67
|
+
- If a parameter key is provided via `setImageParamKeys`, it is used in
|
|
68
|
+
generating image URLs instead of the default Fastly parameters.
|
|
69
|
+
- If a parameter key is not provided via `setImageParamKeys`, it is omitted from
|
|
70
|
+
the generated image URLs.
|
|
71
|
+
- If a mapped key is a function and it is not specified as a parameter in the
|
|
72
|
+
Image component, it is called with `null`. It should return a tuple of the key
|
|
73
|
+
and value.
|
|
74
|
+
- If a mapping callback is provided, the callback is called with the parameter
|
|
75
|
+
value (if it exists) and should return a tuple of the new key and transformed
|
|
76
|
+
value.
|
|
77
|
+
- If a mapping callback returns `null`, the parameter is omitted from the
|
|
78
|
+
generated image URLs.
|
|
68
79
|
|
|
69
80
|
### Usage
|
|
70
81
|
|
|
71
|
-
Call the setImageParamKeys() function before the register() and mount()
|
|
82
|
+
Call the setImageParamKeys() function before the register() and mount()
|
|
83
|
+
functions in the application layer.
|
|
72
84
|
|
|
73
85
|
```javascript
|
|
74
86
|
// Set global image parameters
|
|
@@ -82,11 +94,12 @@ initializers.setImageParamKeys({
|
|
|
82
94
|
});
|
|
83
95
|
|
|
84
96
|
initializers.mountImmediately(pkg.initialize, {
|
|
85
|
-
langDefinitions
|
|
97
|
+
langDefinitions,
|
|
86
98
|
});
|
|
87
99
|
```
|
|
88
100
|
|
|
89
|
-
Now, when a dropin uses the Image component to render an image with a width of
|
|
101
|
+
Now, when a dropin uses the Image component to render an image with a width of
|
|
102
|
+
300 pixels and quality value of 0.8:
|
|
90
103
|
|
|
91
104
|
```jsx
|
|
92
105
|
<Image
|
|
@@ -105,37 +118,49 @@ It renders the following image element:
|
|
|
105
118
|
<img
|
|
106
119
|
loading="lazy"
|
|
107
120
|
src="https://example.com/image.jpg"
|
|
108
|
-
srcset="
|
|
121
|
+
srcset="
|
|
122
|
+
https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 768w,
|
|
123
|
+
https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1024w,
|
|
124
|
+
https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1366w,
|
|
125
|
+
https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1920w
|
|
126
|
+
"
|
|
109
127
|
alt="Example Image"
|
|
110
128
|
width="300"
|
|
111
129
|
height="300"
|
|
112
130
|
/>
|
|
113
131
|
```
|
|
114
132
|
|
|
115
|
-
In this example, the width parameter is mapped to imgWidth and the value of the
|
|
133
|
+
In this example, the width parameter is mapped to imgWidth and the value of the
|
|
134
|
+
quality parameter is modified and mapped to imgQuality.
|
|
116
135
|
|
|
117
136
|
## `setGlobalLocale(locale)`
|
|
118
137
|
|
|
119
|
-
The `setGlobalLocale` method is part of the initializers module in the
|
|
120
|
-
It allows you to set a global locale for all drop-ins
|
|
138
|
+
The `setGlobalLocale` method is part of the initializers module in the
|
|
139
|
+
`@dropins/tools` package. It allows you to set a global locale for all drop-ins
|
|
140
|
+
that use locale-sensitive components like the Price component.
|
|
121
141
|
|
|
122
142
|
### Default Behavior
|
|
123
143
|
|
|
124
|
-
By default, components use the browser's locale or fallback to 'en-US' if no
|
|
144
|
+
By default, components use the browser's locale or fallback to 'en-US' if no
|
|
145
|
+
global locale is set.
|
|
125
146
|
|
|
126
147
|
### Parameters
|
|
127
148
|
|
|
128
|
-
- `locale` - `string` - The locale string (e.g., 'en-US', 'es-MX', 'fr-FR',
|
|
149
|
+
- `locale` - `string` - The locale string (e.g., 'en-US', 'es-MX', 'fr-FR',
|
|
150
|
+
'de-DE').
|
|
129
151
|
|
|
130
152
|
### Functionality
|
|
131
153
|
|
|
132
|
-
- If a global locale is set via `setGlobalLocale`, it will be used by components
|
|
154
|
+
- If a global locale is set via `setGlobalLocale`, it will be used by components
|
|
155
|
+
that support locale configuration.
|
|
133
156
|
- Component-specific locale props will take precedence over the global locale.
|
|
134
|
-
- If no global locale is set, components will fall back to the browser's locale
|
|
157
|
+
- If no global locale is set, components will fall back to the browser's locale
|
|
158
|
+
or a default locale.
|
|
135
159
|
|
|
136
160
|
### Usage
|
|
137
161
|
|
|
138
|
-
Call the `setGlobalLocale()` function before the `mountImmediately()` function
|
|
162
|
+
Call the `setGlobalLocale()` function before the `mountImmediately()` function
|
|
163
|
+
in the application layer.
|
|
139
164
|
|
|
140
165
|
```javascript
|
|
141
166
|
// Set global locale for consistent formatting across all drop-ins
|
|
@@ -148,34 +173,32 @@ initializers.mountImmediately(pkg.initialize, {});
|
|
|
148
173
|
Now, when a dropin uses the Price component without specifying a locale prop:
|
|
149
174
|
|
|
150
175
|
```jsx
|
|
151
|
-
<Price
|
|
152
|
-
amount={100}
|
|
153
|
-
currency="EUR"
|
|
154
|
-
/>
|
|
176
|
+
<Price amount={100} currency="EUR" />
|
|
155
177
|
```
|
|
156
178
|
|
|
157
179
|
It will render with the global locale (fr-FR) formatting:
|
|
158
180
|
|
|
159
181
|
```html
|
|
160
|
-
<span
|
|
182
|
+
<span
|
|
183
|
+
class="dropin-price dropin-price--default dropin-price--small dropin-price--bold"
|
|
184
|
+
>
|
|
161
185
|
100,00 €
|
|
162
186
|
</span>
|
|
163
187
|
```
|
|
164
188
|
|
|
165
|
-
If the same component is used with a specific locale prop, that will take
|
|
189
|
+
If the same component is used with a specific locale prop, that will take
|
|
190
|
+
precedence:
|
|
166
191
|
|
|
167
192
|
```jsx
|
|
168
|
-
<Price
|
|
169
|
-
amount={100}
|
|
170
|
-
currency="EUR"
|
|
171
|
-
locale="en-US"
|
|
172
|
-
/>
|
|
193
|
+
<Price amount={100} currency="EUR" locale="en-US" />
|
|
173
194
|
```
|
|
174
195
|
|
|
175
196
|
It will render with the specified locale (en-US) formatting:
|
|
176
197
|
|
|
177
198
|
```html
|
|
178
|
-
<span
|
|
199
|
+
<span
|
|
200
|
+
class="dropin-price dropin-price--default dropin-price--small dropin-price--bold"
|
|
201
|
+
>
|
|
179
202
|
€100.00
|
|
180
203
|
</span>
|
|
181
|
-
```
|
|
204
|
+
```
|