@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.
Files changed (249) hide show
  1. package/.elsie.js +3 -3
  2. package/CHANGELOG.md +385 -112
  3. package/LICENSE.md +257 -157
  4. package/README.md +4 -2
  5. package/__mocks__/svg.js +3 -3
  6. package/bin/builders/build/index.js +2 -1
  7. package/bin/builders/changeset/index.js +1 -1
  8. package/bin/builders/concurrently/index.js +1 -1
  9. package/bin/builders/generate/api/index.js +7 -7
  10. package/bin/builders/generate/component/index.js +8 -8
  11. package/bin/builders/generate/config/index.js +5 -5
  12. package/bin/builders/generate/config/templates/elsie.js +1 -1
  13. package/bin/builders/generate/container/index.js +7 -7
  14. package/bin/builders/generate/index.js +36 -36
  15. package/bin/builders/gql/index.js +28 -28
  16. package/bin/builders/gql/validate.js +116 -105
  17. package/bin/builders/lint/index.js +1 -1
  18. package/bin/builders/serve/index.js +1 -1
  19. package/bin/builders/storybook/index.js +9 -1
  20. package/bin/builders/types/index.js +1 -2
  21. package/bin/builders/types/validate-tsconfig.js +5 -5
  22. package/bin/index.js +12 -6
  23. package/bin/lib/cli.js +9 -8
  24. package/bin/lib/resolve-bin.js +9 -0
  25. package/bin/lib/validate-typeof.js +3 -3
  26. package/bin/lib/write-file.js +3 -3
  27. package/bin/lib/write-parent-index.js +4 -4
  28. package/config/eslint.mjs +2 -1
  29. package/config/jest.mjs +7 -2
  30. package/config/plugins/dts-normalize-relative-replacer.cjs +1 -1
  31. package/config/plugins/dts.mjs +4 -3
  32. package/config/prettier.json +25 -3
  33. package/config/setEnvVars.mjs +2 -2
  34. package/config/storybook/addon.js +5 -5
  35. package/config/storybook/components/FileTree/FileTree.jsx +4 -4
  36. package/config/storybook/components/FileTree/index.js +4 -4
  37. package/config/storybook/components/Flex/Flex.jsx +3 -3
  38. package/config/storybook/components/Flex/index.js +3 -3
  39. package/config/storybook/components/OptionsTable/OptionsTable.jsx +3 -3
  40. package/config/storybook/components/OptionsTable/index.js +4 -4
  41. package/config/storybook/components/Panel/Panel.tsx +7 -7
  42. package/config/storybook/components/Panel/index.ts +3 -3
  43. package/config/storybook/components/Screenshot/Screenshot.jsx +3 -3
  44. package/config/storybook/components/Screenshot/index.js +4 -4
  45. package/config/storybook/components/Steps/Steps.jsx +3 -3
  46. package/config/storybook/components/Steps/index.js +4 -4
  47. package/config/storybook/components/StoryWrapper/StoryWrapper.jsx +3 -3
  48. package/config/storybook/components/StoryWrapper/index.js +3 -3
  49. package/config/storybook/components/Summary/Summary.jsx +3 -3
  50. package/config/storybook/components/Summary/index.js +3 -3
  51. package/config/storybook/components/Variants/Variants.jsx +11 -7
  52. package/config/storybook/components/Variants/index.js +3 -3
  53. package/config/storybook/manager.js +3 -3
  54. package/config/storybook/preview.jsx +3 -3
  55. package/config/storybook/theming/fonts.css +12 -4
  56. package/config/storybook/theming/preview.css +3 -1
  57. package/config/storybook/theming/theme.js +3 -3
  58. package/config/vite.mjs +53 -26
  59. package/package.json +36 -34
  60. package/src/components/Accordion/Accordion.css +1 -1
  61. package/src/components/Accordion/Accordion.stories.tsx +18 -18
  62. package/src/components/Accordion/Accordion.tsx +12 -8
  63. package/src/components/Accordion/index.ts +3 -3
  64. package/src/components/ActionButton/ActionButton.stories.tsx +8 -8
  65. package/src/components/ActionButton/ActionButton.tsx +7 -5
  66. package/src/components/ActionButton/index.ts +3 -3
  67. package/src/components/ActionButtonGroup/ActionButtonGroup.stories.tsx +3 -3
  68. package/src/components/ActionButtonGroup/ActionButtonGroup.tsx +2 -2
  69. package/src/components/ActionButtonGroup/index.ts +3 -3
  70. package/src/components/AlertBanner/AlertBanner.stories.tsx +6 -6
  71. package/src/components/AlertBanner/AlertBanner.tsx +12 -10
  72. package/src/components/AlertBanner/index.ts +3 -3
  73. package/src/components/Breadcrumbs/Breadcrumbs.stories.tsx +14 -14
  74. package/src/components/Breadcrumbs/Breadcrumbs.tsx +3 -3
  75. package/src/components/Breadcrumbs/index.ts +3 -3
  76. package/src/components/Button/Button.mdx +24 -11
  77. package/src/components/Button/Button.stories.tsx +6 -6
  78. package/src/components/Button/Button.tsx +7 -8
  79. package/src/components/Button/index.ts +3 -3
  80. package/src/components/Card/Card.stories.tsx +6 -6
  81. package/src/components/Card/Card.tsx +3 -3
  82. package/src/components/Card/index.ts +3 -3
  83. package/src/components/CartItem/CartItem.stories.tsx +12 -12
  84. package/src/components/CartItem/CartItem.tsx +4 -2
  85. package/src/components/CartItem/CartItemSkeleton.tsx +3 -3
  86. package/src/components/CartItem/index.ts +3 -3
  87. package/src/components/CartList/CartList.tsx +3 -3
  88. package/src/components/CartList/index.ts +3 -3
  89. package/src/components/Checkbox/Checkbox.stories.tsx +17 -14
  90. package/src/components/Checkbox/Checkbox.tsx +8 -6
  91. package/src/components/Checkbox/index.ts +3 -3
  92. package/src/components/ColorSwatch/ColorSwatch.css +8 -4
  93. package/src/components/ColorSwatch/ColorSwatch.stories.tsx +6 -6
  94. package/src/components/ColorSwatch/ColorSwatch.tsx +8 -6
  95. package/src/components/ColorSwatch/index.ts +3 -3
  96. package/src/components/ContentGrid/ContentGrid.css +15 -15
  97. package/src/components/ContentGrid/ContentGrid.stories.tsx +4 -4
  98. package/src/components/ContentGrid/ContentGrid.tsx +3 -3
  99. package/src/components/ContentGrid/index.ts +3 -3
  100. package/src/components/Divider/Divider.stories.tsx +7 -4
  101. package/src/components/Divider/Divider.tsx +3 -3
  102. package/src/components/Divider/index.ts +4 -4
  103. package/src/components/Field/Field.stories.tsx +7 -7
  104. package/src/components/Field/Field.tsx +4 -2
  105. package/src/components/Field/index.ts +3 -3
  106. package/src/components/Header/Header.stories.tsx +9 -10
  107. package/src/components/Header/Header.tsx +11 -7
  108. package/src/components/Header/index.ts +3 -3
  109. package/src/components/Icon/Icon.stories.helpers.jsx +4 -4
  110. package/src/components/Icon/Icon.stories.tsx +74 -60
  111. package/src/components/Icon/Icon.tsx +77 -44
  112. package/src/components/Icon/index.ts +3 -3
  113. package/src/components/IllustratedMessage/IllustratedMessage.stories.tsx +8 -8
  114. package/src/components/IllustratedMessage/IllustratedMessage.tsx +7 -5
  115. package/src/components/IllustratedMessage/index.ts +3 -3
  116. package/src/components/Image/Image.stories.tsx +3 -3
  117. package/src/components/Image/Image.tsx +4 -4
  118. package/src/components/Image/index.ts +3 -3
  119. package/src/components/ImageSwatch/ImageSwatch.css +8 -4
  120. package/src/components/ImageSwatch/ImageSwatch.stories.tsx +10 -10
  121. package/src/components/ImageSwatch/ImageSwatch.tsx +25 -23
  122. package/src/components/ImageSwatch/index.ts +3 -3
  123. package/src/components/InLineAlert/InLineAlert.stories.tsx +12 -7
  124. package/src/components/InLineAlert/InLineAlert.tsx +4 -2
  125. package/src/components/InLineAlert/index.ts +3 -3
  126. package/src/components/Incrementer/Incrementer.stories.tsx +9 -9
  127. package/src/components/Incrementer/Incrementer.tsx +75 -37
  128. package/src/components/Incrementer/index.ts +3 -3
  129. package/src/components/Input/Input.css +4 -1
  130. package/src/components/Input/Input.stories.tsx +5 -5
  131. package/src/components/Input/Input.tsx +5 -3
  132. package/src/components/Input/index.ts +3 -3
  133. package/src/components/InputDate/InputDate.tsx +3 -3
  134. package/src/components/InputDate/index.ts +3 -3
  135. package/src/components/InputFile/InputFile.css +16 -16
  136. package/src/components/InputFile/InputFile.stories.tsx +21 -16
  137. package/src/components/InputFile/InputFile.tsx +8 -6
  138. package/src/components/InputFile/index.ts +5 -5
  139. package/src/components/InputPassword/InputPassword.stories.tsx +4 -4
  140. package/src/components/InputPassword/InputPassword.tsx +5 -4
  141. package/src/components/InputPassword/PasswordStatusIndicator/PasswordStatusIndicator.tsx +1 -1
  142. package/src/components/InputPassword/PasswordStatusIndicator/index.ts +3 -3
  143. package/src/components/InputPassword/index.ts +3 -3
  144. package/src/components/Modal/Modal.stories.tsx +27 -16
  145. package/src/components/Modal/Modal.tsx +10 -11
  146. package/src/components/Modal/index.ts +3 -3
  147. package/src/components/MultiSelect/MultiSelect.stories.tsx +15 -15
  148. package/src/components/MultiSelect/MultiSelect.tsx +15 -15
  149. package/src/components/Pagination/Pagination.css +1 -1
  150. package/src/components/Pagination/Pagination.stories.tsx +0 -1
  151. package/src/components/Pagination/Pagination.tsx +17 -12
  152. package/src/components/Pagination/PaginationButton.tsx +2 -3
  153. package/src/components/Pagination/index.ts +3 -3
  154. package/src/components/Picker/Picker.css +3 -1
  155. package/src/components/Picker/Picker.stories.tsx +1 -1
  156. package/src/components/Picker/Picker.tsx +8 -6
  157. package/src/components/Picker/index.ts +3 -3
  158. package/src/components/Portal/Portal.stories.tsx +50 -44
  159. package/src/components/Portal/Portal.tsx +4 -4
  160. package/src/components/Price/Price.stories.tsx +3 -3
  161. package/src/components/Price/Price.tsx +4 -2
  162. package/src/components/Price/index.ts +3 -3
  163. package/src/components/PriceRange/PriceRange.stories.tsx +3 -3
  164. package/src/components/PriceRange/PriceRange.tsx +8 -6
  165. package/src/components/PriceRange/index.ts +3 -3
  166. package/src/components/ProductItemCard/ProductItemCard.tsx +4 -2
  167. package/src/components/ProductItemCard/ProductItemCardSkeleton.tsx +16 -16
  168. package/src/components/ProductItemCard/index.ts +4 -4
  169. package/src/components/ProgressSpinner/ProgressSpinner.stories.tsx +8 -8
  170. package/src/components/ProgressSpinner/ProgressSpinner.tsx +7 -5
  171. package/src/components/ProgressSpinner/index.ts +3 -3
  172. package/src/components/RadioButton/RadioButton.stories.tsx +1 -1
  173. package/src/components/RadioButton/RadioButton.tsx +4 -2
  174. package/src/components/Skeleton/Skeleton.stories.tsx +4 -4
  175. package/src/components/Skeleton/Skeleton.tsx +11 -7
  176. package/src/components/Skeleton/index.ts +3 -3
  177. package/src/components/Table/Table.css +106 -99
  178. package/src/components/Table/Table.stories.tsx +404 -227
  179. package/src/components/Table/Table.tsx +11 -7
  180. package/src/components/Table/index.ts +4 -4
  181. package/src/components/Tag/Tag.stories.tsx +6 -6
  182. package/src/components/Tag/Tag.tsx +7 -5
  183. package/src/components/Tag/index.ts +3 -3
  184. package/src/components/TextArea/TextArea.css +3 -1
  185. package/src/components/TextArea/TextArea.stories.tsx +9 -6
  186. package/src/components/TextArea/TextArea.tsx +3 -3
  187. package/src/components/TextArea/index.ts +3 -3
  188. package/src/components/TextSwatch/TextSwatch.css +4 -2
  189. package/src/components/TextSwatch/TextSwatch.stories.tsx +8 -8
  190. package/src/components/TextSwatch/TextSwatch.tsx +12 -7
  191. package/src/components/TextSwatch/index.ts +3 -3
  192. package/src/components/ToggleButton/ToggleButton.css +6 -2
  193. package/src/components/ToggleButton/ToggleButton.stories.tsx +10 -6
  194. package/src/components/ToggleButton/ToggleButton.tsx +8 -3
  195. package/src/components/ToggleButton/index.ts +3 -3
  196. package/src/components/UIProvider/UIProvider.css +3 -2
  197. package/src/components/UIProvider/UIProvider.tsx +11 -7
  198. package/src/components/UIProvider/debugger.css +5 -6
  199. package/src/components/UIProvider/index.ts +3 -3
  200. package/src/docs/API/event-bus.mdx +64 -37
  201. package/src/docs/API/graphql.mdx +69 -36
  202. package/src/docs/API/initializer.mdx +58 -35
  203. package/src/docs/API/render.mdx +45 -32
  204. package/src/docs/Design/colors.mdx +10 -12
  205. package/src/docs/Design/grid.mdx +41 -14
  206. package/src/docs/Design/overview.mdx +20 -4
  207. package/src/docs/Design/shapes.mdx +8 -7
  208. package/src/docs/Design/spacing.mdx +3 -1
  209. package/src/docs/Design/typography.mdx +3 -2
  210. package/src/docs/Utilities/VComponent.mdx +27 -10
  211. package/src/docs/Utilities/classList.mdx +7 -5
  212. package/src/docs/Utilities/debounce.mdx +6 -7
  213. package/src/docs/Utilities/getCookie.mdx +1 -2
  214. package/src/docs/Utilities/getFormErrors.mdx +1 -2
  215. package/src/docs/Utilities/getFormValues.mdx +1 -2
  216. package/src/docs/Utilities/getPathValue.mdx +2 -4
  217. package/src/docs/Utilities/links.mdx +16 -7
  218. package/src/docs/cli-usage.mdx +8 -3
  219. package/src/docs/components/overview.mdx +14 -4
  220. package/src/docs/quick-start.mdx +69 -22
  221. package/src/docs/slots.mdx +74 -37
  222. package/src/docs/welcome.mdx +13 -4
  223. package/src/i18n/index.ts +3 -3
  224. package/src/lib/aem/assets.ts +9 -9
  225. package/src/lib/aem/configs.ts +16 -8
  226. package/src/lib/classes.ts +4 -4
  227. package/src/lib/config.ts +3 -3
  228. package/src/lib/debounce.ts +3 -3
  229. package/src/lib/deepmerge.ts +6 -13
  230. package/src/lib/deviceUtils.ts +3 -3
  231. package/src/lib/form-values.ts +3 -3
  232. package/src/lib/get-price-formatter.ts +8 -3
  233. package/src/lib/i18n.ts +3 -3
  234. package/src/lib/image-params-keymap.ts +4 -5
  235. package/src/lib/initializer.ts +11 -12
  236. package/src/lib/is-number.ts +3 -3
  237. package/src/lib/locale-config.ts +4 -4
  238. package/src/lib/render.tsx +14 -8
  239. package/src/lib/resolve-image.ts +19 -16
  240. package/src/lib/signals.ts +4 -4
  241. package/src/lib/slot.tsx +34 -27
  242. package/src/lib/tests.tsx +6 -8
  243. package/src/lib/types.ts +3 -3
  244. package/src/lib/vcomponent.tsx +3 -3
  245. package/src/shims/importmap.js +3107 -20
  246. package/static/assets/images/index.ts +3 -3
  247. package/storybook-stories.js +3 -3
  248. package/tests/__mocks__/browserMocks.ts +3 -3
  249. 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 application to exchange messages and stay synchronized. It enables event-driven architecture for drop-ins, allowing Containers to react to changes from other Containers and communicate data changes to the storefront.
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 subscribing. This is useful for getting the current state without waiting for the next event.
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('cart/data', (cartData) => {
116
- console.log('Cart data received:', cartData);
117
- }, { eager: true });
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 application.
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('data/update', (data) => {
132
- console.log('Scoped data received:', data);
133
- }, { scope: 'feature-a' });
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', { scope: 'feature-a' });
156
+ const lastScopedData = events.lastPayload('data/update', {
157
+ scope: 'feature-a',
158
+ });
140
159
  ```
141
160
 
142
- **Scoped Event Names:**
143
- When using scopes, the actual event name becomes `scope/event`. For example:
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('locale', (locale) => {
159
- console.log('Current locale:', locale);
160
- }, {
161
- eager: true,
162
- scope: 'user-preferences'
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 coupling between components and seamless communication across the application.
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 interactions without direct dependencies.
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 integration with the host application.
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 leaks
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
@@ -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 operations used by a Drop-in to meet additional data requirements without increasing code complexity or negatively impacting performance.
9
- This API provides a flexible and efficient way to customize GraphQL Fragments by integrating build-time modifications into the storefront's development pipeline.
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 steps:
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 expose.
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 used in our Drop-ins.
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 `./src/api/initialize/initialize.ts`.
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 deep merging the existing data transformation with the new configuration.
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 drop-in's existing GraphQL operations and add extra fields needed to meet your specific business requirements.
143
- This approach enhances the user experience while maintaining code simplicity and performance efficiency since all modifications are integrated into the storefront's development build-time pipeline.
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 Fragment, allowing you to add fields to the fragment as needed.
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 where you must specify:
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. `MY_FRAGMENT`.
165
- - The operations must be valid GraphQL operations, such as Fragment. i.e. `fragment MY_FRAGMENT on FragmentInterface { ... }`.
166
- - In the case of a Fragment, the fragment name must match the same interface as the drop-in. i.e. `FragmentInterface`.
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
- - If not variables are provided, the existing variables will be used. i.e. `favorites(page: 1) { ... }`.
169
- - If new variables are provided, the new variable will be added. i.e. `favorites(page: 1, offset: 5) { ... }`.
170
- - If the existing variables are changed, the new variables will be used. i.e. `favorites(page: 2) { ... }`.
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. When a fragment name is listed in `skipFragments`:
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 from other operations in the same file.
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 name, the fragment is **fully replaced** rather than merged:
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 with the (now-removed) original.
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 `skipFragments` and then replaced by the new definition containing only `fragmentName`.
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, the fragment is simply removed (emptied). If `operations` is used without `skipFragments`, the new fields are **merged** into the existing fragment definition.
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, ensuring that the additional data is correctly processed and available for use in the drop-in. i.e., Slots, Event Bus, etc.
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 `@dropins/tools` package.
49
- It allows you to set image parameters globally for all drop-ins that use the Image component.
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 if no parameters are provided.
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 keys in the URL.
59
- - The value can be a string or a function that takes the parameter value as an argument and returns a tuple of the new key and transformed value.
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 generating image URLs instead of the default Fastly parameters.
64
- - If a parameter key is not provided via `setImageParamKeys`, it is omitted from the generated image URLs.
65
- - If a mapped key is a function and it is not specified as a parameter in the Image component, it is called with `null`. It should return a tuple of the key and value.
66
- - If a mapping callback is provided, the callback is called with the parameter value (if it exists) and should return a tuple of the new key and transformed value.
67
- - If a mapping callback returns `null`, the parameter is omitted from the generated image URLs.
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() functions in the application layer.
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 300 pixels and quality value of 0.8:
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="https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 768w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1024w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1366w, https://example.com/image.jpg?imgWidth=300&imgQuality=80&extraParam=extraValue 1920w"
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 quality parameter is modified and mapped to imgQuality.
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 `@dropins/tools` package.
120
- It allows you to set a global locale for all drop-ins that use locale-sensitive components like the Price component.
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 global locale is set.
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', 'de-DE').
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 that support locale configuration.
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 or a default 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 in the application layer.
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 class="dropin-price dropin-price--default dropin-price--small dropin-price--bold">
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 precedence:
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 class="dropin-price dropin-price--default dropin-price--small dropin-price--bold">
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
+ ```