@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
@@ -9,11 +9,9 @@ This function takes in an object and a key and returns the value of the key.
9
9
 
10
10
  ## Params
11
11
 
12
- `obj`
13
- : The object to get the value from
12
+ `obj` : The object to get the value from
14
13
 
15
- `key`
16
- : The key to get the value from (supports dot notation)
14
+ `key` : The key to get the value from (supports dot notation)
17
15
 
18
16
  ## Returns
19
17
 
@@ -5,29 +5,36 @@ import { Meta, Unstyled } from '@storybook/addon-docs/blocks';
5
5
 
6
6
  # Adding Links using the route pattern
7
7
 
8
- Whenever possible, avoid placing `onClick` handlers directly on anchor elements (`<a>`) in drop-in components, such as product or category pages, as this results in accessibility issues and broken browser behavior. Problems include:
8
+ Whenever possible, avoid placing `onClick` handlers directly on anchor elements
9
+ (`<a>`) in drop-in components, such as product or category pages, as this
10
+ results in accessibility issues and broken browser behavior. Problems include:
9
11
 
10
12
  - Right-click > Open in New Tab results in blank pages.
11
13
  - Middle-click (open in background tab) won't work as expected.
12
14
  - Keyboard navigation and screen readers may not trigger the link correctly.
13
15
 
14
- Instead, follow the route pattern to provide composable and accessible navigation.
16
+ Instead, follow the route pattern to provide composable and accessible
17
+ navigation.
15
18
 
16
19
  ## How it works
17
20
 
18
- Components accept a `routeX` function as a prop. The function receives a data model (a product, for example) and returns a URL. Internally, it's used like this:
21
+ Components accept a `routeX` function as a prop. The function receives a data
22
+ model (a product, for example) and returns a URL. Internally, it's used like
23
+ this:
19
24
 
20
25
  ```tsx
21
26
  <a href={routeProduct?.(product) ?? '#'}>...</a>
22
27
  ```
23
28
 
24
- This lets developers customize routing logic per storefront while preserving link semantics.
29
+ This lets developers customize routing logic per storefront while preserving
30
+ link semantics.
25
31
 
26
32
  ## Example — Component-Side
27
33
 
28
34
  In your component (a PLP item, for example):
29
35
 
30
- The `routeProduct` prop must be optional and default to a # or an non-functional element like a `div` if not provided.
36
+ The `routeProduct` prop must be optional and default to a # or an non-functional
37
+ element like a `div` if not provided.
31
38
 
32
39
  ```tsx
33
40
  type Props = {
@@ -45,13 +52,15 @@ function ProductCard({ product, routeProduct }: Props) {
45
52
 
46
53
  ## Example — Storefront-Side
47
54
 
48
- In the storefront integration (`commerce-cart.js` or `commerce-plp.js`, for example):
55
+ In the storefront integration (`commerce-cart.js` or `commerce-plp.js`, for
56
+ example):
49
57
 
50
58
  ```js
51
59
  import { rootLink } from '@adobe/commerce-url-utils';
52
60
 
53
61
  provider.render(ProductList, {
54
- routeProduct: (product) => rootLink(`/products/${product.url.urlKey}/${product.topLevelSku}`),
62
+ routeProduct: (product) =>
63
+ rootLink(`/products/${product.url.urlKey}/${product.topLevelSku}`),
55
64
  });
56
65
  ```
57
66
 
@@ -13,8 +13,9 @@ npx elsie --help
13
13
 
14
14
  ## `gql`
15
15
 
16
- The `gql` command can generate types and mocks for your GraphQL API and Operations. Files will
17
- be generated in `<domain package root>/src/__generated__/`.
16
+ The `gql` command can generate types and mocks for your GraphQL API and
17
+ Operations. Files will be generated in
18
+ `<domain package root>/src/__generated__/`.
18
19
 
19
20
  To use it, you must first configure your `.elsie.cjs` with the necessary values:
20
21
 
@@ -61,7 +62,11 @@ npx elsie gql types
61
62
  npx elsie gql mocks
62
63
  ```
63
64
 
64
- **Note**: In order to generate types for your _client_ operations you **must** have your operations in files using the \*.graphql.ts extension, and you **must** prepend the query string with `/\* graphql \*/` (the [magic comment](https://the-guild.dev/graphql/codegen/docs/config-reference/documents-field#graphql-tag-pluck) is case insensitive).
65
+ **Note**: In order to generate types for your _client_ operations you **must**
66
+ have your operations in files using the \*.graphql.ts extension, and you
67
+ **must** prepend the query string with `/\* graphql \*/` (the
68
+ [magic comment](https://the-guild.dev/graphql/codegen/docs/config-reference/documents-field#graphql-tag-pluck)
69
+ is case insensitive).
65
70
 
66
71
  Example:
67
72
 
@@ -18,11 +18,12 @@ import {
18
18
 
19
19
  # Drop-in component library
20
20
 
21
- The component library provides a flexible set of interactive building blocks, such as actions, containment,
22
- navigation, text, and selection elements, thought to create unique tailored
23
- commerce user interfaces.
21
+ The component library provides a flexible set of interactive building blocks,
22
+ such as actions, containment, navigation, text, and selection elements, thought
23
+ to create unique tailored commerce user interfaces.
24
24
 
25
- **NOTE**: Not all components are listed below. Refer to the left-side navigation for a complete list of components.
25
+ **NOTE**: Not all components are listed below. Refer to the left-side navigation
26
+ for a complete list of components.
26
27
 
27
28
  ## Actions
28
29
 
@@ -33,6 +34,7 @@ commerce user interfaces.
33
34
  Action buttons allow users to perform an action or mark a selection in task-based options, and are ideal for buttons that aren't meant to draw a lot of attention.
34
35
 
35
36
  [Learn more](/docs/components-actionbutton--overview)
37
+
36
38
  </Panel>
37
39
 
38
40
  <Panel header footer>
@@ -41,6 +43,7 @@ Action buttons allow users to perform an action or mark a selection in task-base
41
43
  Buttons allow users to perform actions or to navigate to another page. They have multiple styles for each need, and call user attention to move forward in a flow.
42
44
 
43
45
  [Learn more](/docs/components-button--overview)
46
+
44
47
  </Panel>
45
48
  </Flex>
46
49
 
@@ -58,6 +61,7 @@ Buttons allow users to perform actions or to navigate to another page. They have
58
61
  Card is a general purpose container with different combination of semantics that can be used to hold and create related groups of information and actions.
59
62
 
60
63
  [Learn more](/docs/components-card--overview)
64
+
61
65
  </Panel>
62
66
 
63
67
  <Panel header footer>
@@ -68,6 +72,7 @@ Card is a general purpose container with different combination of semantics that
68
72
  Dividers bring clarity to a layout by grouping and dividing content by proximity, establish rhythm, and creating hierarchy.
69
73
 
70
74
  [Learn more](/docs/components-divider--overview)
75
+
71
76
  </Panel>
72
77
  </Flex>
73
78
 
@@ -80,6 +85,7 @@ Dividers bring clarity to a layout by grouping and dividing content by proximity
80
85
  Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
81
86
 
82
87
  [Learn more](/docs/components-checkbox--overview)
88
+
83
89
  </Panel>
84
90
 
85
91
  <Panel header footer>
@@ -90,6 +96,7 @@ Checkboxes allow users to select multiple items from a list of individual items,
90
96
  Form fields allow users to combine input entries with various displayed options to communicate field requirements.
91
97
 
92
98
  [Learn more](/docs/components-field--overview)
99
+
93
100
  </Panel>
94
101
 
95
102
  <Panel header footer>
@@ -98,6 +105,7 @@ Form fields allow users to combine input entries with various displayed options
98
105
  Incrementer enable users to make selections for numerical values in a specific range by clicking on the component or by typing a value.
99
106
 
100
107
  [Learn more](/docs/components-incrementer--overview)
108
+
101
109
  </Panel>
102
110
 
103
111
  <Panel header footer>
@@ -106,6 +114,7 @@ Incrementer enable users to make selections for numerical values in a specific r
106
114
  Pickers, also known as "dropdowns" or "selects", allow users to choose from a list of options in a limited space. The list of options can change based on the context.
107
115
 
108
116
  [Learn more](/docs/components-picker--overview)
117
+
109
118
  </Panel>
110
119
  </Flex>
111
120
 
@@ -118,6 +127,7 @@ Pickers, also known as "dropdowns" or "selects", allow users to choose from a li
118
127
  Text fields allow users to input custom text entries with a keyboard.
119
128
 
120
129
  [Learn more](/docs/components-input--overview)
130
+
121
131
  </Panel>
122
132
  </Flex>
123
133
 
@@ -15,13 +15,21 @@ Use the steps below to build your first composable drop-in using this SDK.
15
15
 
16
16
  ### Create your composable drop-in project
17
17
 
18
- The first step is visiting our GitHub Enterprise drop-in project template. You must be logged into Adobe's VPN for this link to work: [Commerce-Storefront/my-dropin](https://git.corp.adobe.com/Commerce-Storefront/my-dropin).
18
+ The first step is visiting our GitHub Enterprise drop-in project template. You
19
+ must be logged into Adobe's VPN for this link to work:
20
+ [Commerce-Storefront/my-dropin](https://git.corp.adobe.com/Commerce-Storefront/my-dropin).
19
21
 
20
- From the GitHub page, click the **Use this template** button. You can name your new drop-in repo whatever you want, but we recommend naming it to reflect the drop-in you want to build. For example, if you want to build a drop-in to show a customer's purchase history, naming your drop-in project/repo `purchase-history` would be reasonable.
22
+ From the GitHub page, click the **Use this template** button. You can name your
23
+ new drop-in repo whatever you want, but we recommend naming it to reflect the
24
+ drop-in you want to build. For example, if you want to build a drop-in to show a
25
+ customer's purchase history, naming your drop-in project/repo `purchase-history`
26
+ would be reasonable.
21
27
 
22
28
  ### Clone your new project
23
29
 
24
- Follow the standard process: Click your repo's **Code** button, copy the SSH link, open your terminal, change directories to where you want it on your workstation, and run:
30
+ Follow the standard process: Click your repo's **Code** button, copy the SSH
31
+ link, open your terminal, change directories to where you want it on your
32
+ workstation, and run:
25
33
 
26
34
  ```bash
27
35
  git clone <your-repository-ssh-url>
@@ -39,13 +47,18 @@ pnpm install
39
47
 
40
48
  ### Generate the project config file
41
49
 
42
- Before you can start developing, you need to generate the `.elsie.cjs` config file. The elsie CLI uses this file to generate new components, containers, and API functions to specified directories within your projects. Run the following command, replacing `<your-dropin-name>` with the name of your drop-in component. For example, `npx elsie generate config --name purchase-history`.
50
+ Before you can start developing, you need to generate the `.elsie.cjs` config
51
+ file. The elsie CLI uses this file to generate new components, containers, and
52
+ API functions to specified directories within your projects. Run the following
53
+ command, replacing `<your-dropin-name>` with the name of your drop-in component.
54
+ For example, `npx elsie generate config --name purchase-history`.
43
55
 
44
56
  ```bash
45
57
  npx elsie generate config --name <your-dropin-name>
46
58
  ```
47
59
 
48
- After generating the `.elsie.cjs` config, open it and take a look. Below is an annotated version describing the main properties:
60
+ After generating the `.elsie.cjs` config, open it and take a look. Below is an
61
+ annotated version describing the main properties:
49
62
 
50
63
  ```js
51
64
  module.exports = {
@@ -72,7 +85,8 @@ module.exports = {
72
85
 
73
86
  ### Explore the project structure
74
87
 
75
- In future versions of the docs, we will provide a detailed explanation of each folder and file in the project structure. For now, these are the highlights:
88
+ In future versions of the docs, we will provide a detailed explanation of each
89
+ folder and file in the project structure. For now, these are the highlights:
76
90
 
77
91
  <FileTree>
78
92
  <FileTree.Folder
@@ -145,7 +159,9 @@ In future versions of the docs, we will provide a detailed explanation of each f
145
159
 
146
160
  ### Update the mesh endpoint
147
161
 
148
- By default, the drop-in project is configured to use a development-only mesh endpoint. This endpoint is only available when running the project locally. To use a different mesh endpoint, update the following file:
162
+ By default, the drop-in project is configured to use a development-only mesh
163
+ endpoint. This endpoint is only available when running the project locally. To
164
+ use a different mesh endpoint, update the following file:
149
165
 
150
166
  ```bash
151
167
  .env.local
@@ -153,7 +169,8 @@ By default, the drop-in project is configured to use a development-only mesh end
153
169
 
154
170
  ### Launch development environment
155
171
 
156
- Let's take it for a spin! Run the following command to launch your project's development environment in its default state:
172
+ Let's take it for a spin! Run the following command to launch your project's
173
+ development environment in its default state:
157
174
 
158
175
  ```bash
159
176
  yarn dev
@@ -161,15 +178,28 @@ npm run dev
161
178
  pnpm run dev
162
179
  ```
163
180
 
164
- Congrats! You just launched your first composable drop-in! Actually, no... What you're seeing is our drop-in development environment. It's a preconfigured HTML page (`examples > html-host > index.html`) that loads your drop-in for testing during development.
181
+ Congrats! You just launched your first composable drop-in! Actually, no... What
182
+ you're seeing is our drop-in development environment. It's a preconfigured HTML
183
+ page (`examples > html-host > index.html`) that loads your drop-in for testing
184
+ during development.
165
185
 
166
186
  <Screenshot src={dropinDevEnv} alt={'Drop-in development environment'} />
167
187
 
168
- Now we're ready to start building a composable drop-in. Stop the server with `ctrl + c` and let's get started.
188
+ Now we're ready to start building a composable drop-in. Stop the server with
189
+ `ctrl + c` and let's get started.
169
190
 
170
191
  ### Generate a new UI Component
171
192
 
172
- Start by executing the following command, replacing `<MyUiComponent>` with the name of the component you want to add. For example, if you were building a drop-in for a customer's purchase history, you might want a part of the drop-in to show a list of date ranges to filter their product purchases. In that case, you might generate something like this: `npx elsie generate component --pathname DateFilter` to create the scaffolding for a component called `DateFilter`, in which you would implement the UI component as a list of buttons representing data-range filters that would filter a customer's product purchases when clicked: last month, last three months, last year, and so on.
193
+ Start by executing the following command, replacing `<MyUiComponent>` with the
194
+ name of the component you want to add. For example, if you were building a
195
+ drop-in for a customer's purchase history, you might want a part of the drop-in
196
+ to show a list of date ranges to filter their product purchases. In that case,
197
+ you might generate something like this:
198
+ `npx elsie generate component --pathname DateFilter` to create the scaffolding
199
+ for a component called `DateFilter`, in which you would implement the UI
200
+ component as a list of buttons representing data-range filters that would filter
201
+ a customer's product purchases when clicked: last month, last three months, last
202
+ year, and so on.
173
203
 
174
204
  ```bash
175
205
  npx elsie generate component --pathname <MyUiComponent>
@@ -187,42 +217,57 @@ After running this command, the drop-in CLI generates the following files:
187
217
  ~/purchase-history [main] »
188
218
  ```
189
219
 
190
- These files are not only generated with the appropriate names, but they are completely preconfigured to work together as a unit. For example, the `DateFilter` component is automatically imported into `src/components/index.ts` so you can start referencing the component throughout your project.
220
+ These files are not only generated with the appropriate names, but they are
221
+ completely preconfigured to work together as a unit. For example, the
222
+ `DateFilter` component is automatically imported into `src/components/index.ts`
223
+ so you can start referencing the component throughout your project.
191
224
 
192
- And if you run `npm run dev` again, you'll see your new component in the Storybook UI, configured with an example and best practices to help you get started with Storybook.
225
+ And if you run `npm run dev` again, you'll see your new component in the
226
+ Storybook UI, configured with an example and best practices to help you get
227
+ started with Storybook.
193
228
 
194
229
  ### Generate a new API Function
195
230
 
196
- Start by executing the following command, replacing `<myApiFunction>` with the name of the API function you want to add:
231
+ Start by executing the following command, replacing `<myApiFunction>` with the
232
+ name of the API function you want to add:
197
233
 
198
234
  ```bash
199
235
  npx elsie generate api --pathname <myApiFunction>
200
236
  ```
201
237
 
202
- For the `purchase-history` example drop-in, you might want to add a filter function that handles filtering the purchase history by date-ranges, such as `filterByDateRange`. In this case, you would run the following command:
203
-
238
+ For the `purchase-history` example drop-in, you might want to add a filter
239
+ function that handles filtering the purchase history by date-ranges, such as
240
+ `filterByDateRange`. In this case, you would run the following command:
204
241
 
205
242
  ```bash
206
243
  npx elsie generate api --pathname filterByDateRange
207
244
  ```
208
245
 
209
- This generates a new API function in the `src/api` directory, preconfigured with a test file and a default implementation. Full details about API function development will be documented as soon as possible.
246
+ This generates a new API function in the `src/api` directory, preconfigured with
247
+ a test file and a default implementation. Full details about API function
248
+ development will be documented as soon as possible.
210
249
 
211
250
  ### Generate a drop-in Container
212
251
 
213
- Start by executing the following command, replacing `<MyDropinContainer>` with the name of the container you want to add:
252
+ Start by executing the following command, replacing `<MyDropinContainer>` with
253
+ the name of the container you want to add:
214
254
 
215
255
  ```bash
216
256
  npx elsie generate container --pathname <MyDropinContainer>
217
257
  ```
218
258
 
219
- For the `purchase-history` example drop-in, the command used to generate its container could be: `npx elsie generate container --pathname PurchaseHistoryContainer`.
259
+ For the `purchase-history` example drop-in, the command used to generate its
260
+ container could be:
261
+ `npx elsie generate container --pathname PurchaseHistoryContainer`.
220
262
 
221
- This generates a new Container in the `src/containers` directory, preconfigured with a test file and a default implementation. Full details about container development will be documented as soon as possible.
263
+ This generates a new Container in the `src/containers` directory, preconfigured
264
+ with a test file and a default implementation. Full details about container
265
+ development will be documented as soon as possible.
222
266
 
223
267
  ### Run unit tests
224
268
 
225
- Unit tests are also preconfigured for you. Run the following command to execute the basic default tests, and add to them as you build your frontend.
269
+ Unit tests are also preconfigured for you. Run the following command to execute
270
+ the basic default tests, and add to them as you build your frontend.
226
271
 
227
272
  ```bash
228
273
  yarn test
@@ -232,7 +277,9 @@ pnpm run test
232
277
 
233
278
  ### Build production bundles
234
279
 
235
- When you're ready to deploy your frontend, run the following command to build production bundles. Like everything else in the SDK, the basic process is configured for you, but you can customize it as you develop.
280
+ When you're ready to deploy your frontend, run the following command to build
281
+ production bundles. Like everything else in the SDK, the basic process is
282
+ configured for you, but you can customize it as you develop.
236
283
 
237
284
  ```bash
238
285
  yarn build
@@ -5,20 +5,27 @@ import { Meta, Unstyled } from '@storybook/addon-docs/blocks';
5
5
 
6
6
  # Slots
7
7
 
8
- A Slot is a high-level interface for developers to define and manage dynamic content insertion within drop-in components.
8
+ A Slot is a high-level interface for developers to define and manage dynamic
9
+ content insertion within drop-in components.
9
10
 
10
11
  ## Context
11
12
 
12
- The context is defined during implementation of a drop-in and can be used to pass data and functions to the slot.
13
+ The context is defined during implementation of a drop-in and can be used to
14
+ pass data and functions to the slot.
13
15
 
14
16
  ### Pre-built Methods
15
17
 
16
18
  - **dictionary**: The dictionary of the selected language.
17
- - **replaceWith**: A function to replace the slot's content with a new HTML element.
18
- - **appendChild**: A function to append a new HTML element to the slot's content.
19
- - **prependChild**: A function to prepend a new HTML element to the slot's content.
20
- - **appendSibling**: A function to append a new HTML element after the slot's content.
21
- - **prependSibling**: A function to prepend a new HTML element **before** the slot's content.
19
+ - **replaceWith**: A function to replace the slot's content with a new HTML
20
+ element.
21
+ - **appendChild**: A function to append a new HTML element to the slot's
22
+ content.
23
+ - **prependChild**: A function to prepend a new HTML element to the slot's
24
+ content.
25
+ - **appendSibling**: A function to append a new HTML element after the slot's
26
+ content.
27
+ - **prependSibling**: A function to prepend a new HTML element **before** the
28
+ slot's content.
22
29
  - **remove**: A function to remove the slot element from the DOM.
23
30
  - **getSlotElement**: A function to get a slot element.
24
31
  - **onChange**: A function to listen to changes in the slot's context.
@@ -27,7 +34,8 @@ The context is defined during implementation of a drop-in and can be used to pas
27
34
 
28
35
  ## Implementing a new slot
29
36
 
30
- The `<Slot />` component is used to define a slot in a container. It receives a name and a slot object with the following properties:
37
+ The `<Slot />` component is used to define a slot in a container. It receives a
38
+ name and a slot object with the following properties:
31
39
 
32
40
  ### name
33
41
 
@@ -35,15 +43,23 @@ The name of the slot in _PascalCase_. `string` (required).
35
43
 
36
44
  ### lazy
37
45
 
38
- Controls whether the slot should be loaded immediately or deferred for later initialization. `boolean` (optional).
46
+ Controls whether the slot should be loaded immediately or deferred for later
47
+ initialization. `boolean` (optional).
39
48
 
40
- When `lazy={false}`, the slot is initialized as soon as the container mounts. When `lazy={true}`, the slot can be initialized later on when it is needed. This is useful for performance optimization, especially when the slot's content is not immediately required.
49
+ When `lazy={false}`, the slot is initialized as soon as the container mounts.
50
+ When `lazy={true}`, the slot can be initialized later on when it is needed. This
51
+ is useful for performance optimization, especially when the slot's content is
52
+ not immediately required.
41
53
 
42
54
  ### slotTag
43
55
 
44
- The HTML tag to use for the slot's wrapper element. This allows you to change the wrapper element from the default `div` to any valid HTML tag (e.g., 'span', 'p', 'a', etc.). When using specific tags like 'a', you can also provide their respective HTML attributes (e.g., 'href', 'target', etc.).
56
+ The HTML tag to use for the slot's wrapper element. This allows you to change
57
+ the wrapper element from the default `div` to any valid HTML tag (e.g., 'span',
58
+ 'p', 'a', etc.). When using specific tags like 'a', you can also provide their
59
+ respective HTML attributes (e.g., 'href', 'target', etc.).
45
60
 
46
61
  Example:
62
+
47
63
  ```tsx
48
64
  // Render with a span wrapper
49
65
  <Slot name="MySlot" slotTag="span">
@@ -58,13 +74,16 @@ Example:
58
74
 
59
75
  ### contentTag
60
76
 
61
- The HTML tag to use for wrapping dynamically inserted content within the slot. This is separate from the slot's wrapper tag and allows you to control how dynamic content is structured. Defaults to 'div'.
77
+ The HTML tag to use for wrapping dynamically inserted content within the slot.
78
+ This is separate from the slot's wrapper tag and allows you to control how
79
+ dynamic content is structured. Defaults to 'div'.
62
80
 
63
81
  Example:
82
+
64
83
  ```tsx
65
84
  <Slot
66
85
  name="MySlot"
67
- slotTag="article" // The outer wrapper will be an article
86
+ slotTag="article" // The outer wrapper will be an article
68
87
  contentTag="section" // Dynamic content will be wrapped in sections
69
88
  slot={(ctx) => {
70
89
  const elem = document.createElement('div');
@@ -76,29 +95,40 @@ Example:
76
95
 
77
96
  ### slot (required)
78
97
 
79
- - `ctx`: An object representing the context of the slot, including methods for manipulating the slot's content.
98
+ - `ctx`: An object representing the context of the slot, including methods for
99
+ manipulating the slot's content.
80
100
 
81
- The slot property, which is implemented as a promise function, provides developers with the flexibility to dynamically generate and manipulate content within slots.
82
- However, it's important to note that this promise is render-blocking, meaning that the component will not render until the promise is resolved.
101
+ The slot property, which is implemented as a promise function, provides
102
+ developers with the flexibility to dynamically generate and manipulate content
103
+ within slots. However, it's important to note that this promise is
104
+ render-blocking, meaning that the component will not render until the promise is
105
+ resolved.
83
106
 
84
107
  ### context
85
108
 
86
- The context property in the Slot component lets developers pass extra information or functionality to customize how the slot
87
- behaves or interacts with the application. This information is accessible within the slot's rendering logic, allowing for
88
- tailored slot behavior based on specific needs or application states.
109
+ The context property in the Slot component lets developers pass extra
110
+ information or functionality to customize how the slot behaves or interacts with
111
+ the application. This information is accessible within the slot's rendering
112
+ logic, allowing for tailored slot behavior based on specific needs or
113
+ application states.
89
114
 
90
115
  ### render
91
116
 
92
- The render property in the Slot component lets developers define how the content within the slot should be displayed and should be used when developers
93
- need fine-grained control over what content appears within the slot.
94
- It's particularly useful when using custom slot methods (see Privates below) in scenarios where the content to be displayed within the slot is dynamic and may depend on
95
- properties passed to another component.
117
+ The render property in the Slot component lets developers define how the content
118
+ within the slot should be displayed and should be used when developers need
119
+ fine-grained control over what content appears within the slot. It's
120
+ particularly useful when using custom slot methods (see Privates below) in
121
+ scenarios where the content to be displayed within the slot is dynamic and may
122
+ depend on properties passed to another component.
96
123
 
97
124
  ### children
98
125
 
99
- The children property in the Slot component represents the content that is passed directly within the opening and closing tags of the Slot component.
100
- It allows developers to include static content directly within the slot, which will be rendered as part of the slot's contents.
101
- This property is useful for cases where the content within the slot is static or does not need to be dynamically generated by the slot.
126
+ The children property in the Slot component represents the content that is
127
+ passed directly within the opening and closing tags of the Slot component. It
128
+ allows developers to include static content directly within the slot, which will
129
+ be rendered as part of the slot's contents. This property is useful for cases
130
+ where the content within the slot is static or does not need to be dynamically
131
+ generated by the slot.
102
132
 
103
133
  ```tsx
104
134
  // MyContainer.tsx (Drop-in)
@@ -165,27 +195,34 @@ provider.render(MyContainer, {
165
195
 
166
196
  ## Privates
167
197
 
168
- The `<Slot />` component has a private interface that serves as a mechanism for managing internal
169
- complexity and promoting clean, modular design within the Slot component or related components.
198
+ The `<Slot />` component has a private interface that serves as a mechanism for
199
+ managing internal complexity and promoting clean, modular design within the Slot
200
+ component or related components.
170
201
 
171
202
  ### \_registerMethod
172
203
 
173
- The `_registerMethod` private function is used to register a method in the slot's context which is particularly helpful in scenarios
174
- where dynamic behavior or interactions need to be incorporated into the Slot component.
204
+ The `_registerMethod` private function is used to register a method in the
205
+ slot's context which is particularly helpful in scenarios where dynamic behavior
206
+ or interactions need to be incorporated into the Slot component.
175
207
 
176
- Slot Methods also include the ability to modify the slot's state or content based on external interactions or changes in application state.
208
+ Slot Methods also include the ability to modify the slot's state or content
209
+ based on external interactions or changes in application state.
177
210
 
178
211
  ### \_setProps
179
212
 
180
- The `_setProps` private function within the Slot component is responsible for dynamically updating the properties of the slot.
181
- It allows developers to modify the slot's state or content based on external interactions or changes in application state,
182
- triggering re-renders of the slot component with updated properties.
213
+ The `_setProps` private function within the Slot component is responsible for
214
+ dynamically updating the properties of the slot. It allows developers to modify
215
+ the slot's state or content based on external interactions or changes in
216
+ application state, triggering re-renders of the slot component with updated
217
+ properties.
183
218
 
184
219
  ### \_htmlElementToVNode
185
220
 
186
- The `_htmlElementToVNode` private function in the Slot component converts HTML elements into virtual DOM nodes (VNodes),
187
- enabling their integration into Preact components. This conversion facilitates the dynamic insertion of HTML content
188
- into slots while benefiting from Preact's virtual DOM reconciliation and rendering.
221
+ The `_htmlElementToVNode` private function in the Slot component converts HTML
222
+ elements into virtual DOM nodes (VNodes), enabling their integration into Preact
223
+ components. This conversion facilitates the dynamic insertion of HTML content
224
+ into slots while benefiting from Preact's virtual DOM reconciliation and
225
+ rendering.
189
226
 
190
227
  ```tsx
191
228
  // MyContainer.tsx (Drop-in)
@@ -11,17 +11,23 @@ import banner from './assets/DropinBanner.png';
11
11
  <Screenshot src={banner} alt="dropin SDK Banner" />
12
12
 
13
13
  <Summary>
14
- The **drop-in SDK** is deployed as a set of **npm packages** assembled into a completely pre-configured **starter template** to provide everything you need to build **composable** Commerce frontends.
14
+ The **drop-in SDK** is deployed as a set of **npm packages** assembled into a
15
+ completely pre-configured **starter template** to provide everything you need
16
+ to build **composable** Commerce frontends.
15
17
  </Summary>
16
18
 
17
- **For the frontend**, the drop-in SDK includes our design system, which provides the components and design tokens that make merchant rebranding quick and easy.
19
+ **For the frontend**, the drop-in SDK includes our design system, which provides
20
+ the components and design tokens that make merchant rebranding quick and easy.
18
21
 
19
- **For everything else**, the drop-in SDK provides a complete framework for mounting, rendering, eventing, testing, and hydrating drop-ins with data from the Commerce backend.
22
+ **For everything else**, the drop-in SDK provides a complete framework for
23
+ mounting, rendering, eventing, testing, and hydrating drop-ins with data from
24
+ the Commerce backend.
20
25
 
21
26
  ## Get started
22
27
 
23
28
  <Summary>
24
- Use our [Quick-Start tutorial](/docs/quick-start--overview) to create a fully-configured drop-in and render it in less than 10 minutes.
29
+ Use our [Quick-Start tutorial](/docs/quick-start--overview) to create a
30
+ fully-configured drop-in and render it in less than 10 minutes.
25
31
  </Summary>
26
32
 
27
33
  ## Get to know drop-ins
@@ -32,6 +38,7 @@ Use our [Quick-Start tutorial](/docs/quick-start--overview) to create a fully-co
32
38
  Follow the quick-start guide to start building a new Commerce drop-in.
33
39
 
34
40
  [Read more](/docs/quick-start--overview)
41
+
35
42
  </Panel>
36
43
 
37
44
  <Panel footer>
@@ -39,6 +46,7 @@ Follow the quick-start guide to start building a new Commerce drop-in.
39
46
  Explore the library of components available for your drop-in user interface.
40
47
 
41
48
  [Read more](/docs/components-overview--overview)
49
+
42
50
  </Panel>
43
51
 
44
52
  <Panel footer>
@@ -46,6 +54,7 @@ Explore the library of components available for your drop-in user interface.
46
54
  Learn how to rebrand your drop-ins using the drop-in design system.
47
55
 
48
56
  [Read more](/docs/design-overview--overview)
57
+
49
58
  </Panel>
50
59
  </Flex>
51
60
 
package/src/i18n/index.ts CHANGED
@@ -2,9 +2,9 @@
2
2
  * Copyright 2024 Adobe
3
3
  * All Rights Reserved.
4
4
  *
5
- * NOTICE: Adobe permits you to use, modify, and distribute this
6
- * file in accordance with the terms of the Adobe license agreement
7
- * accompanying it.
5
+ * NOTICE: Adobe permits you to use, modify, and distribute this
6
+ * file in accordance with the terms of the Adobe license agreement
7
+ * accompanying it.
8
8
  *******************************************************************/
9
9
 
10
10
  import { deepmerge } from '@adobe-commerce/elsie/lib';