@vtex/ads-stories 0.4.0 → 0.5.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 (51) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +260 -28
  3. package/dist/cdn/vtex-ads-stories.js +1073 -20
  4. package/dist/cdn/vtex-ads-stories.js.map +1 -1
  5. package/dist/cjs/index.cjs +4392 -315
  6. package/dist/cjs/index.cjs.map +1 -1
  7. package/dist/cjs/index.d.cts +198 -12
  8. package/dist/cjs/react.cjs.map +1 -1
  9. package/dist/cjs/react.d.cts +46 -5
  10. package/dist/esm/index.d.ts +198 -12
  11. package/dist/esm/index.js +2819 -291
  12. package/dist/esm/index.js.map +1 -1
  13. package/dist/esm/react.d.ts +46 -5
  14. package/package.json +21 -4
  15. package/src/cdn.ts +7 -3
  16. package/src/components/card/card.ts +101 -111
  17. package/src/components/card/index.ts +1 -1
  18. package/src/components/carousel/carousel.ts +670 -0
  19. package/src/components/carousel/index.ts +15 -0
  20. package/src/components/events/events-controller.ts +212 -0
  21. package/src/components/events/index.ts +6 -0
  22. package/src/components/icons/assets/caret-left-bold.svg +1 -0
  23. package/src/components/icons/assets/caret-right-bold.svg +1 -0
  24. package/src/components/icons/assets/caret-up-bold.svg +1 -0
  25. package/src/components/icons/index.ts +30 -9
  26. package/src/components/media/index.ts +3 -0
  27. package/src/components/media/media.ts +70 -0
  28. package/src/components/media/video-controller.ts +125 -0
  29. package/src/components/player/index.ts +6 -2
  30. package/src/components/player/player.ts +946 -134
  31. package/src/components/product/cta.ts +56 -0
  32. package/src/components/product/index.ts +20 -0
  33. package/src/components/product/price.ts +86 -0
  34. package/src/components/product/product.styles.ts +369 -0
  35. package/src/components/product/product.ts +235 -0
  36. package/src/index.ts +9 -1
  37. package/src/locales/en.ts +29 -0
  38. package/src/locales/es.ts +30 -0
  39. package/src/locales/index.ts +36 -0
  40. package/src/locales/pt.ts +29 -0
  41. package/src/locales/types.ts +24 -0
  42. package/src/react.ts +49 -7
  43. package/src/story/index.ts +5 -1
  44. package/src/story/story.ts +528 -93
  45. package/src/tag-name.ts +1 -0
  46. package/src/types.ts +8 -12
  47. package/src/utils/fetch-story.ts +113 -0
  48. package/src/utils/http-url.ts +12 -0
  49. package/src/utils/hydrate-products.ts +88 -0
  50. package/src/utils/send-event.ts +71 -0
  51. package/src/utils/with-timeout.ts +43 -0
@@ -1,8 +1,11 @@
1
1
  import { DetailedHTMLProps, HTMLAttributes } from 'react';
2
- import { VtexAdsStoryElement } from './index.js';
2
+ import { Channel } from '@vtex/ads-core';
3
+ import { TAG_NAME, VtexAdsStoryCarouselElement } from './index.js';
4
+ import 'lit';
3
5
 
4
6
  /**
5
- * React JSX types for <vtex-ads-story>. Types only: the JS output is empty.
7
+ * React JSX types for <vtex-ads-story-carousel>. Types only: the JS output
8
+ * is empty.
6
9
  *
7
10
  * Opt in once per project, so non-React projects never need @types/react:
8
11
  *
@@ -11,13 +14,51 @@ import { VtexAdsStoryElement } from './index.js';
11
14
  * or add "@vtex/ads-stories/react" to `compilerOptions.types` in tsconfig.
12
15
  */
13
16
 
14
- type VtexAdsStoryProps = DetailedHTMLProps<HTMLAttributes<VtexAdsStoryElement>, VtexAdsStoryElement>;
17
+ /**
18
+ * The element's own attributes. The required ones match the README: without
19
+ * them, the element requests nothing and renders nothing.
20
+ */
21
+ interface VtexAdsStoryCarouselAttributes {
22
+ /** The publisher the ads are requested for. */
23
+ "publisher-id": string;
24
+ /** The store's session, also used to deduplicate events. */
25
+ "session-id": string;
26
+ /** The Story placement configured for the publisher. */
27
+ placement: string;
28
+ "user-id"?: string;
29
+ "account-name"?: string;
30
+ /** `site` or `app`. */
31
+ channel?: Channel;
32
+ /** Time limit for the ad request, in milliseconds (default 2000). */
33
+ timeout?: number;
34
+ /** How many Stories to ask for: the carousel positions (default 8). */
35
+ quantity?: number;
36
+ /** Currency of the prices, ISO 4217 ("BRL"). Default BRL. */
37
+ currency?: string;
38
+ /** The add to cart button's text. Default in the element's language. */
39
+ "label-add-to-cart"?: string;
40
+ /** The view product button's text. Default in the element's language. */
41
+ "label-view-product"?: string;
42
+ /**
43
+ * "none": no product request. To set a strategy, assign the element's
44
+ * `hydration` property. Missing: Intelligent Search with `account-name`.
45
+ */
46
+ hydration?: "none";
47
+ /** Time limit for the product request, in milliseconds (default 5000). */
48
+ "hydration-timeout"?: number;
49
+ /**
50
+ * With more than one Story, the cards without the highlight also play
51
+ * their video, muted. Off by default.
52
+ */
53
+ "inactive-autoplay"?: boolean;
54
+ }
55
+ type VtexAdsStoryCarouselProps = DetailedHTMLProps<HTMLAttributes<VtexAdsStoryCarouselElement>, VtexAdsStoryCarouselElement> & VtexAdsStoryCarouselAttributes;
15
56
  declare module "react" {
16
57
  namespace JSX {
17
58
  interface IntrinsicElements {
18
- "vtex-ads-story": VtexAdsStoryProps;
59
+ [TAG_NAME]: VtexAdsStoryCarouselProps;
19
60
  }
20
61
  }
21
62
  }
22
63
 
23
- export type { VtexAdsStoryProps };
64
+ export type { VtexAdsStoryCarouselAttributes, VtexAdsStoryCarouselProps };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vtex/ads-stories",
3
3
  "type": "module",
4
- "version": "0.4.0",
4
+ "version": "0.5.0",
5
5
  "description": "VTEX Ads Stories web component",
6
6
  "main": "dist/cjs/index.cjs",
7
7
  "module": "dist/esm/index.js",
@@ -60,18 +60,35 @@
60
60
  }
61
61
  },
62
62
  "devDependencies": {
63
+ "@storybook/web-components-vite": "10.6.5",
63
64
  "@types/node": "^22.15.21",
64
65
  "@types/react": "^19.1.2",
66
+ "msw": "2.15.0",
67
+ "msw-storybook-addon": "3.0.3",
68
+ "storybook": "10.6.5",
65
69
  "tsup": "^8.5.0",
66
70
  "vite": "^5.0.0"
67
71
  },
72
+ "dependencies": {
73
+ "@vtex/ads-core": "^0.6.0",
74
+ "lit": "^3.3.3"
75
+ },
76
+ "msw": {
77
+ "workerDirectory": [
78
+ ".storybook/public"
79
+ ]
80
+ },
68
81
  "scripts": {
82
+ "prebuild": "pnpm --filter @vtex/ads-core run build",
69
83
  "build": "tsup",
70
84
  "build:watch": "tsup --watch",
71
85
  "clean": "rimraf dist",
72
- "dev": "vite",
73
- "preview:cdn": "tsup && vite --open /?cdn",
74
- "check-types": "tsc --noEmit",
86
+ "predev": "pnpm run prebuild",
87
+ "dev": "storybook dev -p 6006",
88
+ "preview:cdn": "pnpm build && STORIES_SOURCE=cdn storybook dev -p 6006",
89
+ "prebuild-storybook": "pnpm run prebuild",
90
+ "build-storybook": "storybook build",
91
+ "check-types": "tsc --noEmit && tsc -p stories",
75
92
  "test": "vitest run",
76
93
  "test:watch": "vitest --coverage.enabled=false"
77
94
  }
package/src/cdn.ts CHANGED
@@ -1,5 +1,9 @@
1
- import { defineVtexAdsStories } from "./story";
1
+ import { defineVtexAdsStoryCarousel } from "./story";
2
2
 
3
- defineVtexAdsStories();
3
+ defineVtexAdsStoryCarousel();
4
4
 
5
- export { VtexAdsStoryElement, defineVtexAdsStories, TAG_NAME } from "./story";
5
+ export {
6
+ VtexAdsStoryCarouselElement,
7
+ defineVtexAdsStoryCarousel,
8
+ TAG_NAME,
9
+ } from "./story";
@@ -1,12 +1,24 @@
1
- import { createIcon } from "../icons";
1
+ import { css, html, nothing } from "lit";
2
+ import { ref, type RefOrCallback } from "lit/directives/ref.js";
3
+ import type { StoryLabels } from "../../locales";
4
+ import { icon } from "../icons";
5
+ import { hasVideo, renderMedia, type VideoController } from "../media";
6
+ import {
7
+ renderCta,
8
+ renderProduct,
9
+ type CardCta,
10
+ type CardProduct,
11
+ } from "../product";
2
12
  import type { StoryMedia } from "../../types";
3
13
 
4
- export const cardStyles = `
14
+ export const cardStyles = css`
15
+ /* 9:16 at the height its container gives it (--card-height, default
16
+ 500px). */
5
17
  .card {
6
18
  position: relative;
7
19
  box-sizing: border-box;
8
- width: calc(500px * 9 / 16);
9
- height: 500px;
20
+ width: calc(var(--card-height, 500px) * 9 / 16);
21
+ height: var(--card-height, 500px);
10
22
  overflow: hidden;
11
23
  border-radius: var(--vtex-ads-story-radius, 20px);
12
24
  background: #000;
@@ -114,120 +126,98 @@ export interface CardOptions {
114
126
  label: string;
115
127
  /** Called on click, Enter or Space. */
116
128
  onSelect: () => void;
117
- /** Accessible names of the sound button, shown when the card has a video. */
118
- soundOnLabel: string;
119
- soundOffLabel: string;
120
- }
121
-
122
- // Only absolute http(s) URLs reach the DOM. Relative and protocol-relative
123
- // ones ("/a.jpg", "//host/a.jpg") don't parse without a base, so they're out.
124
- function httpUrl(value: string | undefined) {
125
- if (!value) return null;
126
- try {
127
- const { protocol } = new URL(value);
128
- return protocol === "https:" || protocol === "http:" ? value : null;
129
- } catch {
130
- return null;
131
- }
132
- }
133
-
134
- function prefersReducedMotion() {
135
- return (
136
- globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false
137
- );
129
+ /**
130
+ * Whether the video plays over the cover (default true). Without it, the
131
+ * card shows only the cover, with no sound button.
132
+ */
133
+ withVideo?: boolean;
134
+ /** The texts (the sound button's, shown when the card has a video). */
135
+ labels: StoryLabels;
136
+ /** The Story's product, shown at the bottom of the card. */
137
+ product?: CardProduct;
138
+ /** Called by a click on the product (default onSelect). */
139
+ onProductSelect?: () => void;
140
+ /** The Story's call to action, for a link destination (no product). */
141
+ cta?: CardCta;
142
+ /**
143
+ * Called by a click on the call to action instead of following the link
144
+ * (a card without the highlight). Without it, the link opens.
145
+ */
146
+ onCtaSelect?: () => void;
147
+ /**
148
+ * Called by any click on the card, its product, call to action and sound
149
+ * button included, before what that click does.
150
+ */
151
+ onPress?: () => void;
152
+ /** Receives the card's element (see Slide's cardRef). */
153
+ ref?: RefOrCallback;
154
+ /** Receives the button that takes the focus (see Slide's focusRef). */
155
+ openRef?: RefOrCallback;
138
156
  }
139
157
 
140
158
  /**
141
- * Plays a video. A blocked play is ignored: the cover or the paused state
142
- * stays.
159
+ * Sound on/off for the card's video, which starts muted. Only shown while the
160
+ * video plays: a video that never plays (reduced motion, or autoplay blocked
161
+ * as in iOS Low Power Mode) has no sound to turn on, and the card paused
162
+ * behind the open player needs none.
143
163
  */
144
- export function playVideo(video: HTMLVideoElement) {
145
- video.play()?.catch(() => undefined);
146
- }
147
-
148
- function createVideo(src: string, poster: string | null) {
149
- const video = document.createElement("video");
150
- video.className = "video";
151
- // Muted and inline is what browsers, iOS included, allow to autoplay.
152
- video.muted = true;
153
- video.setAttribute("muted", "");
154
- video.setAttribute("playsinline", "");
155
- video.loop = true;
156
- video.preload = "metadata";
157
- // No autoplay for people who asked for reduced motion.
158
- video.autoplay = !prefersReducedMotion();
159
- if (poster) video.poster = poster;
160
- video.src = src;
161
-
162
- // If the video can't load, the cover underneath stays.
163
- video.addEventListener("error", () => video.remove());
164
- return video;
165
- }
166
-
167
- /** Sound on/off for the card's video, which starts muted. */
168
- function createSoundButton(video: HTMLVideoElement, options: CardOptions) {
169
- const button = document.createElement("button");
170
- button.type = "button";
171
- button.className = "card-sound";
172
-
173
- function sync() {
174
- button.setAttribute(
175
- "aria-label",
176
- video.muted ? options.soundOnLabel : options.soundOffLabel,
177
- );
178
- button.replaceChildren(createIcon(video.muted ? "soundOff" : "soundOn"));
179
- }
180
-
181
- video.addEventListener("volumechange", sync);
182
- // Without the video, the cover stays and there is no sound to control.
183
- video.addEventListener("error", () => button.remove());
184
- button.addEventListener("click", () => {
185
- video.muted = !video.muted;
186
- });
187
-
188
- sync();
189
- return button;
164
+ function renderSoundButton(video: VideoController, options: CardOptions) {
165
+ return html`
166
+ <button
167
+ type="button"
168
+ class="card-sound"
169
+ aria-label=${video.muted
170
+ ? options.labels.soundOn
171
+ : options.labels.soundOff}
172
+ @click=${() => video.toggleMuted()}
173
+ >
174
+ ${icon(video.muted ? "soundOff" : "soundOn")}
175
+ </button>
176
+ `;
190
177
  }
191
178
 
192
179
  /**
193
180
  * A 9:16 card with the Story cover and, with a media_url, the video looping
194
- * muted over it. With options, a button with a play icon in the middle covers
195
- * the card, and a card with a video gets a sound button. The sound button is
196
- * beside the card's button, not inside it: a button can't contain another.
181
+ * muted over it (see renderMedia). A button with a play icon in the middle
182
+ * covers the card, and a sound button shows while the video plays. With a
183
+ * product, its pill sits at the bottom (see renderProduct); with a link
184
+ * destination, the call to action does (see renderCta). The sound, product
185
+ * and call to action are beside the card's button, not inside it: a button
186
+ * can't contain another.
197
187
  */
198
- export function createCard(story: StoryMedia, options?: CardOptions) {
199
- const card = document.createElement("div");
200
- card.className = "card";
201
-
202
- const posterUrl = httpUrl(story.poster_url);
203
- if (posterUrl) {
204
- const poster = document.createElement("img");
205
- poster.className = "poster";
206
- poster.alt = "";
207
- poster.src = posterUrl;
208
- card.append(poster);
209
- }
210
-
211
- const mediaUrl = httpUrl(story.media_url);
212
- const video = mediaUrl ? createVideo(mediaUrl, posterUrl) : null;
213
- if (video) card.append(video);
214
-
215
- if (options) {
216
- const open = document.createElement("button");
217
- open.type = "button";
218
- open.className = "card-open";
219
- open.setAttribute("aria-label", options.label);
220
-
221
- const play = document.createElement("span");
222
- play.className = "play";
223
- play.setAttribute("aria-hidden", "true");
224
- play.append(createIcon("play"));
225
- open.append(play);
226
- open.addEventListener("click", options.onSelect);
227
-
228
- card.append(open);
229
- if (video) card.append(createSoundButton(video, options));
230
- }
231
-
232
- return card;
188
+ export function renderCard(
189
+ story: StoryMedia,
190
+ video: VideoController,
191
+ options: CardOptions,
192
+ ) {
193
+ const withVideo = options.withVideo ?? true;
194
+
195
+ return html`
196
+ <div
197
+ class="card"
198
+ ${ref(options.ref)}
199
+ @click=${{ handleEvent: () => options.onPress?.(), capture: true }}
200
+ >
201
+ ${renderMedia(story, video, { withVideo })}
202
+ <button
203
+ type="button"
204
+ class="card-open"
205
+ ${ref(options.openRef)}
206
+ aria-label=${options.label}
207
+ @click=${options.onSelect}
208
+ >
209
+ <span class="play" aria-hidden="true">${icon("play")}</span>
210
+ </button>
211
+ ${withVideo && hasVideo(story, video) && !video.paused
212
+ ? renderSoundButton(video, options)
213
+ : nothing}
214
+ ${options.product
215
+ ? renderProduct(
216
+ options.product,
217
+ options.onProductSelect ?? options.onSelect,
218
+ )
219
+ : nothing}
220
+ ${options.cta ? renderCta(options.cta, options.onCtaSelect) : nothing}
221
+ </div>
222
+ `;
233
223
  }
@@ -1,2 +1,2 @@
1
- export { createCard, cardStyles, playVideo } from "./card";
1
+ export { cardStyles, renderCard } from "./card";
2
2
  export type { CardOptions } from "./card";