@vtex/ads-stories 0.4.1 → 0.7.0

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 (60) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/README.md +44 -88
  3. package/dist/cdn/vtex-ads-stories.js +1313 -74
  4. package/dist/cdn/vtex-ads-stories.js.map +1 -1
  5. package/dist/cjs/index.cjs +3744 -513
  6. package/dist/cjs/index.cjs.map +1 -1
  7. package/dist/cjs/index.d.cts +46 -15
  8. package/dist/cjs/react.cjs.map +1 -1
  9. package/dist/cjs/react.d.cts +51 -5
  10. package/dist/cjs/story-DAiAN9v-.d.cts +260 -0
  11. package/dist/esm/index.d.ts +46 -15
  12. package/dist/esm/index.js +3348 -217
  13. package/dist/esm/index.js.map +1 -1
  14. package/dist/esm/react.d.ts +51 -5
  15. package/dist/esm/story-DAiAN9v-.d.ts +260 -0
  16. package/package.json +18 -4
  17. package/src/cdn.ts +7 -3
  18. package/src/commerce-events.ts +93 -0
  19. package/src/components/card/card.ts +79 -14
  20. package/src/components/carousel/carousel-skeleton.ts +113 -0
  21. package/src/components/carousel/carousel.ts +715 -0
  22. package/src/components/carousel/index.ts +22 -0
  23. package/src/components/events/events-controller.ts +222 -0
  24. package/src/components/events/index.ts +6 -0
  25. package/src/components/icons/assets/caret-left-bold.svg +1 -0
  26. package/src/components/icons/assets/caret-right-bold.svg +1 -0
  27. package/src/components/icons/assets/caret-up-bold.svg +1 -0
  28. package/src/components/icons/assets/minus.svg +1 -0
  29. package/src/components/icons/assets/plus.svg +1 -0
  30. package/src/components/icons/assets/trash.svg +1 -0
  31. package/src/components/icons/assets/warning-circle-fill.svg +1 -0
  32. package/src/components/icons/index.ts +14 -0
  33. package/src/components/media/index.ts +8 -1
  34. package/src/components/media/media.styles.ts +113 -0
  35. package/src/components/media/media.ts +124 -23
  36. package/src/components/media/video-controller.ts +127 -6
  37. package/src/components/player/index.ts +6 -2
  38. package/src/components/player/player.ts +824 -50
  39. package/src/components/product/cta.ts +56 -0
  40. package/src/components/product/index.ts +22 -0
  41. package/src/components/product/price.ts +86 -0
  42. package/src/components/product/product.styles.ts +426 -0
  43. package/src/components/product/product.ts +336 -0
  44. package/src/index.ts +17 -1
  45. package/src/locales/en.ts +39 -0
  46. package/src/locales/es.ts +40 -0
  47. package/src/locales/index.ts +36 -0
  48. package/src/locales/pt.ts +39 -0
  49. package/src/locales/types.ts +44 -0
  50. package/src/react.ts +55 -7
  51. package/src/story/index.ts +5 -1
  52. package/src/story/story.ts +679 -49
  53. package/src/tag-name.ts +1 -0
  54. package/src/types.ts +8 -12
  55. package/src/utils/fetch-story.ts +113 -0
  56. package/src/utils/hydrate-products.ts +112 -0
  57. package/src/utils/media-ready.ts +58 -0
  58. package/src/utils/safe-url.ts +36 -0
  59. package/src/utils/send-event.ts +71 -0
  60. package/src/utils/with-timeout.ts +43 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,92 @@
1
1
  # @vtex/ads-stories
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Minor Changes
6
+
7
+ - a0cf1b9: Add to cart in the player dispatches `vtex-ads-story:add-to-cart` from the element, with `{ sku, seller, quantity }` (the product's `product_sku`, its `seller_id` when the ad API sends one, and `1`). The event bubbles and is composed, has no default action, and leaves the player open. A product without a SKU has no add to cart. `ADD_TO_CART_EVENT`, `StoryAddToCartDetail` and `StoryAddToCartEvent` are exported.
8
+ - a0cf1b9: Once a product is added from the player, a stepper takes add to cart's place: minus (a trash with one left), the quantity and plus. Plus dispatches `vtex-ads-story:add-to-cart`, and minus the new `vtex-ads-story:remove-from-cart`, with the same `{ sku, seller, quantity }` detail (`quantity` is how many to remove, always 1). The quantity counts what was added and removed, for each SKU and seller, since the player opened; it doesn't read the store's cart, and opening the player again starts it over. `REMOVE_FROM_CART_EVENT`, `StoryRemoveFromCartDetail` and `StoryRemoveFromCartEvent` are exported.
9
+ - 8b3f105: `--vtex-ads-story-radius` now also shapes the product and call to action pills, the covers beside the expanded video, the product panel's buttons (add to cart, its stepper, view product) and the video's **Tentar de novo**, not only the cards. The product image follows it 8px in, so its corners stay parallel to the pill's. Unset, each keeps its current corners. The round icon buttons on the video stay round.
10
+
11
+ From about `38px` up, the 60px product image becomes a circle. Use `0px`, not `0`, for square corners.
12
+
13
+ - cb5a966: A Story's `destination_url` can be a path on the store (`/product/p`) as well as an absolute http(s) URL, for both the product card and the call to action. Paths that would lead to another host (`//host`, `/\host`) are ignored.
14
+ - 80d967a: New `slide-duration` attribute, also in the React JSX types: with more than one Story, how long each one stays highlighted before the carousel moves to the next, in milliseconds (default `5000`). `0` turns the automatic advance off, so the highlight moves only with the arrows, swipes and clicks. Other values are limited to between `2000` and `120000`. A negative value or one that isn't a number uses the default. Changing it doesn't request the Stories again: the highlighted Story's time starts over with the new duration.
15
+ - cb5a966: A product that can't be bought keeps showing its price (fetched, or the ad server's from `product_metadata`) on the card and in the player; **Esgotado** only shows in its place when there is no price. Add to cart is still the disabled **Produto indisponível**. Screen readers hear that it's sold out either way: the product button's label ends with **Esgotado**, after the price when there is one.
16
+ - cb5a966: A video that can't load no longer leaves only its cover: the card shows a **Video unavailable** notice over it, and the player shows **Couldn't load the video** with a **Try again** button. Retrying shows a spinner with **Loading video** until the video loads, then plays it with the sound on, or shows the notice again if it fails. `StoryLabels` gets `videoUnavailable`, `videoFailed`, `videoLoading` and `retry`, in Portuguese, Spanish and English.
17
+
18
+ ### Patch Changes
19
+
20
+ - cb5a966: A hydration strategy whose `price()` returns no amount, `NaN`, a string or a negative amount no longer shows "R$ NaN": the ad server's price shows instead. A `listPrice` that isn't an amount above the price is dropped.
21
+ - 80d967a: Opening a Story in the player now plays its video with the sound on, since the shopper chose to watch it. If the browser blocks playing with sound, the video plays muted and the sound button offers to turn it on.
22
+ - 80d967a: With `prefers-reduced-motion: reduce`, the carousel no longer moves the highlight on its own: it stays on the cards' covers and moves only with the arrows, swipes and clicks, whatever `slide-duration` says. The player still plays the video once the shopper opens it.
23
+
24
+ ## 0.6.0
25
+
26
+ ### Minor Changes
27
+
28
+ - 563672a: Show a skeleton of the carousel while the ad request is pending and then while the first Story's cover loads, and fade it out once the cards are ready, so the first card doesn't appear piece by piece. The cards show anyway 3 seconds after the Stories arrive, and a broken cover doesn't hold them. Without a required attribute, or when the request fails or the placement has no Story, the element still renders nothing. The Stories' views start counting only once the cards are visible.
29
+
30
+ ## 0.5.0
31
+
32
+ ### Minor Changes
33
+
34
+ - 6495795: Add the `timeout` attribute: the time limit for the ad request, in milliseconds (default `2000`). Without a Story by then, the element renders nothing. The element also cancels its pending request when an attribute changes or it leaves the page, and requests again if moved while the request was pending.
35
+ - 2952cb3: Send each Story's impression, view and click to the event URLs from the ad response, at most once per Story and session. The impression goes out when the carousel renders the Stories; the view when a card, or the open player's video, stays at least 50% on screen for 2 continuous seconds; the click on the first touch on a card, or on the product or call to action in the player. Events are posted as JSON (`session_id`, `user_id`) with `navigator.sendBeacon`, falling back to a `keepalive` fetch.
36
+ - 6495795: Request the Story from the ad API with `@vtex/ads-core` instead of rendering a fixed test Story. The element takes the `publisher-id`, `session-id` and `placement` attributes (required) and `user-id`, `account-name` and `channel` (optional), and renders nothing while loading, without a required attribute, on error or when the placement has no Story.
37
+
38
+ A failed request (other than one cancelled or past its time limit) is logged with `console.error`, so a failing request can be told apart from a placement with no Story.
39
+
40
+ The React JSX types (`@vtex/ads-stories/react`) now include these attributes, with `publisher-id`, `session-id` and `placement` required.
41
+
42
+ - e36dc60: Stories whose destination is a link (no product) show a call to action at the bottom of the card and the video: a glass pill with the text set in the campaign (the ad's `call_to_action`) and a caret, which opens the link in a new tab. On a card without the highlight, it moves the highlight, as the card does. A Story without the text shows no button.
43
+ - 17603aa: The element is now `<vtex-ads-story-carousel>` instead of `<vtex-ads-story>`, also in the React JSX types and in `document.createElement` and `querySelector` types. `<vtex-ads-story>` is no longer registered: replace the tag in the page, and in any CSS selector that targets it. The CSS variables keep their `--vtex-ads-story-` names, and the console messages now start with `[vtex-ads-story-carousel]`.
44
+
45
+ The exports follow the new name: `VtexAdsStoryElement` is now `VtexAdsStoryCarouselElement`, `defineVtexAdsStories()` is now `defineVtexAdsStoryCarousel()`, and the React types `VtexAdsStoryProps` and `VtexAdsStoryAttributes` are now `VtexAdsStoryCarouselProps` and `VtexAdsStoryCarouselAttributes`. The CDN script's global stays `window.VtexAdsStories`, with the renamed members.
46
+
47
+ - fc54bdd: Show the placement's Stories in a carousel, in a 500px tall band as wide as the element's parent. The layout depends on how many Stories come back:
48
+ - **One**: the card is centered over a background, with 24px around it (the card shrinks to 452px tall) and a soft shadow. On screens 576px wide or less, the card shows alone at its full 500px height, without the background.
49
+ - **Two**: both cards side by side. The highlighted card is full size and the other smaller and dimmed.
50
+ - **Three or more**: the highlighted card in the middle and the others on each side, smaller and dimmed, up to two per side. Every card moves one place per step. With four, the Story opposite the highlighted one shows at both ends. On screens 576px wide or less, two Stories also show this way, with the other one on both sides.
51
+
52
+ With more than one Story, the highlight moves to the next card every 5 seconds, except while the pointer is over the carousel, the keyboard focus is in it, or the player is open. It also moves with the previous and next arrows, a swipe, or a click on a dimmed card. Clicking the highlighted card opens it in the player. If the highlighted card's sound is on, the next highlighted card plays with sound too (muted instead, if the browser blocks it). With more than one Story, the mini player has previous and next buttons above its top left: they change the video in the player, and the carousel highlight follows. With the focus in the player, the left and right arrow keys do the same (not with a modifier key held); elsewhere on the page they keep working as usual. The expanded player shows the other Stories' covers beside the video, up to two per side (clicking one plays it), with previous and next beside it, and moves on to the next Story when the video ends instead of looping. With two Stories, the video moves off center with the other cover beside it. Each step animates: the video grows from the cover of the Story it now shows and the covers slide to their new places (not with reduced motion). On screens 576px wide or less, it fills the screen without the covers, with previous and next inside the video's edges.
53
+
54
+ New attributes, also in the React JSX types:
55
+ - `quantity`: how many Stories to request, the carousel positions (default `8`). A value below `1` or not a number uses the default. Changing it requests the Stories again.
56
+ - `inactive-autoplay` (off by default): off, only the highlighted card plays its video and the others show their cover. On, the visible cards without the highlight also play, muted.
57
+
58
+ New CSS variable: `--vtex-ads-story-color-surface` sets the background behind a single Story (default `#fafafa`). `--vtex-ads-story-radius` now rounds that background's corners as well as the card's.
59
+
60
+ - 17603aa: The element's texts follow its language: the buttons, "Esgotado" and the names screen readers read out come in Portuguese, Spanish and English, picked from the closest `lang` attribute like the prices (`es-AR` gets Spanish). Without a `lang`, or with another language, they stay in Portuguese.
61
+
62
+ New attributes, also in the React JSX types: `label-add-to-cart` and `label-view-product` replace the product panel's button texts in any language. Missing or blank, the language's default shows. Changing them doesn't request the Stories again.
63
+
64
+ - b4350e7: The hydration strategy takes an optional `available(product, offer)`, and the Intelligent Search one reads `AvailableQuantity`. A product that can't be bought shows **Esgotado** in place of the price, on the card and in the player, and add to cart becomes a disabled **Produto indisponível**; **Ver produto** still works and the Story keeps playing. `StoryProductDetails` gets `available`.
65
+ - bff14ea: Show the Story's product on its card: a pill at the bottom with the product image, its name (up to two lines) and its price, with the "from" price struck through when on sale. Clicking it does the same as clicking the card. The ad API doesn't send prices yet, so the card reads them from the product's `product_metadata` (`price`, and `promotional_price` when on sale) and shows only the name without them. Stories without a product (a link destination) show no pill.
66
+
67
+ The mini and expanded player show the same pill at the bottom of the video, a bit larger (72px image, 56px in the mini player on screens 576px wide or less). Clicking it opens a panel below it, as in the prototype: the pill turns white and shows an add to cart button and a view product link, which opens the product page in a new tab. Adding to the cart does nothing yet. Clicking the product on the highlighted card opens the player with the panel already open. Clicking the video closes the panel without pausing, and moving to another Story or opening the player again starts with it closed. On devices with a mouse, the closed pill lifts and darkens on hover, on the card and in the player.
68
+
69
+ Prices are formatted in the language of the closest element with a `lang` attribute, the element itself included, so a store can set one for the widget alone (`<vtex-ads-story-carousel lang="es-AR">`). Without a `lang`, or with one the browser doesn't know, they use `pt-BR`.
70
+
71
+ New attribute, also in the React JSX types: `currency`, the currency of the prices as an ISO 4217 code (`BRL`). Default `BRL`, also for a code the browser doesn't know.
72
+
73
+ New CSS variables for the open product panel: `--vtex-ads-story-color-accent` colors its buttons (default `#1b75a8`) and `--vtex-ads-story-color-accent-contrast` the text on the add to cart button (default `#fff`); `--vtex-ads-story-color-surface` is its background and the view product button's (default `#fff`); `--vtex-ads-story-color-muted` is the "from" price and the disabled add to cart (default `#6b6b6b`); `--vtex-ads-story-color-text` now also colors its text (default `#242424` there).
74
+
75
+ - 3261876: The element hydrates its products once the carousel shows, in one request, and shows their fetched prices, with a hydration strategy: the new `hydration` property (`{ fetcher, matcher, price }`), or Intelligent Search by default when `account-name` is set. `hydration="none"` turns it off, and `hydration-timeout` sets its time limit (default 5000 ms). While it runs, the price and add to cart show placeholders; the fetched price then replaces the ad server's. Without one (no strategy, failure, time limit, product not found or without a price), the ad server's price shows, as before. New types `StoryHydration` and `StoryProductDetails`.
76
+
77
+ ### Patch Changes
78
+
79
+ - Updated dependencies [6495795]
80
+ - Updated dependencies [6495795]
81
+ - Updated dependencies [3261876]
82
+ - Updated dependencies [3261876]
83
+ - Updated dependencies [b4350e7]
84
+ - Updated dependencies [3261876]
85
+ - Updated dependencies [3261876]
86
+ - Updated dependencies [6495795]
87
+ - Updated dependencies [e36dc60]
88
+ - @vtex/ads-core@0.6.0
89
+
3
90
  ## 0.4.1
4
91
 
5
92
  ### Patch Changes
package/README.md CHANGED
@@ -3,8 +3,10 @@
3
3
  VTEX Ads Stories web component. Framework-agnostic: works on any HTML5 page,
4
4
  including VTEX IO, FastStore and non-VTEX storefronts.
5
5
 
6
- > Work in progress. Currently renders one fixed test Story, which opens in a
7
- > player at the bottom right. The carousel, fed by the ad API, comes next.
6
+ > Work in progress. Currently requests the placement's Stories from the ad
7
+ > API, shows them in a carousel, whose cards open in a player at the bottom
8
+ > right, sends their impression, view and click events, and tells the store
9
+ > when a product is added to or removed from the cart.
8
10
 
9
11
  ## npm
10
12
 
@@ -15,108 +17,62 @@ npm install @vtex/ads-stories
15
17
  Register the element once, on the client:
16
18
 
17
19
  ```javascript
18
- import { defineVtexAdsStories } from "@vtex/ads-stories";
20
+ import { defineVtexAdsStoryCarousel } from "@vtex/ads-stories";
19
21
 
20
- defineVtexAdsStories();
22
+ defineVtexAdsStoryCarousel();
21
23
  ```
22
24
 
23
25
  ```html
24
- <vtex-ads-story></vtex-ads-story>
26
+ <vtex-ads-story-carousel
27
+ publisher-id="your-publisher-id"
28
+ session-id="the-store-session-id"
29
+ placement="home_stories"
30
+ ></vtex-ads-story-carousel>
25
31
  ```
26
32
 
27
- Importing the package registers nothing: the element is only registered when
28
- `defineVtexAdsStories()` is called. Both ESM (`import`) and CommonJS
29
- (`require`) builds are published, with type declarations.
30
-
31
- The package can be imported during server-side rendering (for example in
32
- FastStore, which is Next.js). The element is built with
33
- [Lit](https://lit.dev), and in Node Lit installs a minimal DOM shim, so after
34
- the import `globalThis.customElements` is defined on the server too. Don't use
35
- `typeof customElements` to tell the server from the browser; use
36
- `typeof window` instead. Calling `defineVtexAdsStories()` on the server is
37
- safe: it registers the element in Lit's server-side registry and renders
38
- nothing.
39
-
40
- ### TypeScript and React
41
-
42
- `document.createElement("vtex-ads-story")` and
43
- `document.querySelector("vtex-ads-story")` are typed as `VtexAdsStoryElement`
44
- out of the box.
45
-
46
- To use `<vtex-ads-story>` in `.tsx` files, enable its JSX types once in your
47
- project (requires `@types/react` 18.2.6 or newer, including 19):
48
-
49
- ```tsx
50
- // e.g. in your app's entry file or a .d.ts file
51
- import type {} from "@vtex/ads-stories/react";
52
-
53
- export const Ad = () => <vtex-ads-story />;
54
- ```
55
-
56
- Or add `"@vtex/ads-stories/react"` to `compilerOptions.types` in `tsconfig.json`.
57
- Without it, TypeScript reports
58
- `Property 'vtex-ads-story' does not exist on type 'JSX.IntrinsicElements'`.
59
- The types are opt-in so projects without React don't need `@types/react`.
60
-
61
33
  ## CDN
62
34
 
63
35
  The same build is available as a standalone script from
64
36
  [unpkg](https://unpkg.com) and [jsDelivr](https://www.jsdelivr.com). It
65
- registers `<vtex-ads-story>` when it loads, so no JavaScript is needed in the
66
- page. Always pin an exact version: a pinned URL never changes.
37
+ registers `<vtex-ads-story-carousel>` when it loads, so no JavaScript is
38
+ needed in the page. Always pin an exact version: replace `<version>` below
39
+ with a version published on
40
+ [npm](https://www.npmjs.com/package/@vtex/ads-stories?activeTab=versions).
67
41
 
68
42
  ```html
69
43
  <script
70
- src="https://unpkg.com/@vtex/ads-stories@0.2.0"
44
+ src="https://unpkg.com/@vtex/ads-stories@<version>"
71
45
  integrity="sha384-<hash>"
72
46
  crossorigin="anonymous"
73
47
  ></script>
74
48
 
75
- <vtex-ads-story></vtex-ads-story>
76
- ```
77
-
78
- - The full file URL works too:
79
- `https://unpkg.com/@vtex/ads-stories@<version>/dist/cdn/vtex-ads-stories.js`.
80
- - jsDelivr serves the same file:
81
- `https://cdn.jsdelivr.net/npm/@vtex/ads-stories@<version>`.
82
- - `integrity` is optional. With it, the browser refuses the file if its content
83
- is not exactly the published one. Get the hash for a version with:
84
-
85
- ```bash
86
- curl -fsSLo vtex-ads-stories.js https://unpkg.com/@vtex/ads-stories@<version>/dist/cdn/vtex-ads-stories.js \
87
- && openssl dgst -sha384 -binary vtex-ads-stories.js | openssl base64 -A
88
- ```
89
-
90
- The hash is only printed if the download succeeded, so a wrong version
91
- shows an error instead of a hash of an error page.
92
-
93
- - Stores with a Content-Security-Policy must allow the CDN host in
94
- `script-src` (`https://unpkg.com` or `https://cdn.jsdelivr.net`).
95
- - The script also exposes `window.VtexAdsStories` with the same API as the npm
96
- package.
97
-
98
- ## Customization
99
-
100
- ```css
101
- vtex-ads-story {
102
- --vtex-ads-story-font-family: "Inter", sans-serif;
103
- --vtex-ads-story-color-text: #1f1f1f;
104
- --vtex-ads-story-radius: 20px;
105
- }
106
- ```
107
-
108
- | Variable | Default | Used for |
109
- | ------------------------------ | --------- | ------------ |
110
- | `--vtex-ads-story-font-family` | inherited | All text |
111
- | `--vtex-ads-story-color-text` | inherited | All text |
112
- | `--vtex-ads-story-radius` | `20px` | Card corners |
113
-
114
- ## Development
115
-
116
- Run from the repository root:
117
-
118
- ```bash
119
- pnpm stories:dev
49
+ <vtex-ads-story-carousel
50
+ publisher-id="your-publisher-id"
51
+ session-id="the-store-session-id"
52
+ placement="home_stories"
53
+ ></vtex-ads-story-carousel>
120
54
  ```
121
55
 
122
- This starts a dev server with `index.html`, reloading on save.
56
+ ## Documentation
57
+
58
+ The full guide is on the
59
+ [VTEX Ads JS SDK documentation](https://vtex.github.io/ads-js/docs/ads-stories/quickstart):
60
+
61
+ - [Quickstart](https://vtex.github.io/ads-js/docs/ads-stories/quickstart):
62
+ npm and CDN (integrity hash, Content-Security-Policy), server-side
63
+ rendering, TypeScript and React.
64
+ - [Configuration](https://vtex.github.io/ads-js/docs/ads-stories/configuration):
65
+ attributes, language and labels, CSS variables.
66
+ - [Layout and player](https://vtex.github.io/ads-js/docs/ads-stories/layout-and-player):
67
+ the carousel, the product and its cart stepper, the call to action, the
68
+ player and video errors.
69
+ - [Product hydration](https://vtex.github.io/ads-js/docs/ads-stories/product-hydration):
70
+ where prices and availability come from, and custom strategies.
71
+ - [Events](https://vtex.github.io/ads-js/docs/ads-stories/events): the add
72
+ and remove from cart events for the store, and the ad events the element
73
+ sends.
74
+
75
+ ## Contributing
76
+
77
+ To run the element locally or contribute a change, see
78
+ [CONTRIBUTING.md](https://github.com/vtex/ads-js/blob/main/CONTRIBUTING.md).