@vtex/ads-stories 0.4.1 → 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 (50) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +250 -26
  3. package/dist/cdn/vtex-ads-stories.js +986 -72
  4. package/dist/cdn/vtex-ads-stories.js.map +1 -1
  5. package/dist/cjs/index.cjs +2911 -403
  6. package/dist/cjs/index.cjs.map +1 -1
  7. package/dist/cjs/index.d.cts +193 -8
  8. package/dist/cjs/react.cjs.map +1 -1
  9. package/dist/cjs/react.d.cts +45 -5
  10. package/dist/esm/index.d.ts +193 -8
  11. package/dist/esm/index.js +2528 -121
  12. package/dist/esm/index.js.map +1 -1
  13. package/dist/esm/react.d.ts +45 -5
  14. package/package.json +18 -4
  15. package/src/cdn.ts +7 -3
  16. package/src/components/card/card.ts +64 -12
  17. package/src/components/carousel/carousel.ts +670 -0
  18. package/src/components/carousel/index.ts +15 -0
  19. package/src/components/events/events-controller.ts +212 -0
  20. package/src/components/events/index.ts +6 -0
  21. package/src/components/icons/assets/caret-left-bold.svg +1 -0
  22. package/src/components/icons/assets/caret-right-bold.svg +1 -0
  23. package/src/components/icons/assets/caret-up-bold.svg +1 -0
  24. package/src/components/icons/index.ts +6 -0
  25. package/src/components/media/index.ts +2 -1
  26. package/src/components/media/media.ts +21 -17
  27. package/src/components/media/video-controller.ts +47 -0
  28. package/src/components/player/index.ts +6 -2
  29. package/src/components/player/player.ts +797 -48
  30. package/src/components/product/cta.ts +56 -0
  31. package/src/components/product/index.ts +20 -0
  32. package/src/components/product/price.ts +86 -0
  33. package/src/components/product/product.styles.ts +369 -0
  34. package/src/components/product/product.ts +235 -0
  35. package/src/index.ts +9 -1
  36. package/src/locales/en.ts +29 -0
  37. package/src/locales/es.ts +30 -0
  38. package/src/locales/index.ts +36 -0
  39. package/src/locales/pt.ts +29 -0
  40. package/src/locales/types.ts +24 -0
  41. package/src/react.ts +49 -7
  42. package/src/story/index.ts +5 -1
  43. package/src/story/story.ts +505 -47
  44. package/src/tag-name.ts +1 -0
  45. package/src/types.ts +8 -12
  46. package/src/utils/fetch-story.ts +113 -0
  47. package/src/utils/http-url.ts +12 -0
  48. package/src/utils/hydrate-products.ts +88 -0
  49. package/src/utils/send-event.ts +71 -0
  50. package/src/utils/with-timeout.ts +43 -0
@@ -1,9 +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';
3
4
  import 'lit';
4
5
 
5
6
  /**
6
- * 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.
7
9
  *
8
10
  * Opt in once per project, so non-React projects never need @types/react:
9
11
  *
@@ -12,13 +14,51 @@ import 'lit';
12
14
  * or add "@vtex/ads-stories/react" to `compilerOptions.types` in tsconfig.
13
15
  */
14
16
 
15
- 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;
16
56
  declare module "react" {
17
57
  namespace JSX {
18
58
  interface IntrinsicElements {
19
- "vtex-ads-story": VtexAdsStoryProps;
59
+ [TAG_NAME]: VtexAdsStoryCarouselProps;
20
60
  }
21
61
  }
22
62
  }
23
63
 
24
- 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.1",
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,21 +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
  },
68
72
  "dependencies": {
73
+ "@vtex/ads-core": "^0.6.0",
69
74
  "lit": "^3.3.3"
70
75
  },
76
+ "msw": {
77
+ "workerDirectory": [
78
+ ".storybook/public"
79
+ ]
80
+ },
71
81
  "scripts": {
82
+ "prebuild": "pnpm --filter @vtex/ads-core run build",
72
83
  "build": "tsup",
73
84
  "build:watch": "tsup --watch",
74
85
  "clean": "rimraf dist",
75
- "dev": "vite",
76
- "preview:cdn": "tsup && vite --open /?cdn",
77
- "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",
78
92
  "test": "vitest run",
79
93
  "test:watch": "vitest --coverage.enabled=false"
80
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,14 +1,24 @@
1
1
  import { css, html, nothing } from "lit";
2
+ import { ref, type RefOrCallback } from "lit/directives/ref.js";
3
+ import type { StoryLabels } from "../../locales";
2
4
  import { icon } from "../icons";
3
5
  import { hasVideo, renderMedia, type VideoController } from "../media";
6
+ import {
7
+ renderCta,
8
+ renderProduct,
9
+ type CardCta,
10
+ type CardProduct,
11
+ } from "../product";
4
12
  import type { StoryMedia } from "../../types";
5
13
 
6
14
  export const cardStyles = css`
15
+ /* 9:16 at the height its container gives it (--card-height, default
16
+ 500px). */
7
17
  .card {
8
18
  position: relative;
9
19
  box-sizing: border-box;
10
- width: calc(500px * 9 / 16);
11
- height: 500px;
20
+ width: calc(var(--card-height, 500px) * 9 / 16);
21
+ height: var(--card-height, 500px);
12
22
  overflow: hidden;
13
23
  border-radius: var(--vtex-ads-story-radius, 20px);
14
24
  background: #000;
@@ -116,9 +126,33 @@ export interface CardOptions {
116
126
  label: string;
117
127
  /** Called on click, Enter or Space. */
118
128
  onSelect: () => void;
119
- /** Accessible names of the sound button, shown when the card has a video. */
120
- soundOnLabel: string;
121
- soundOffLabel: string;
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;
122
156
  }
123
157
 
124
158
  /**
@@ -132,7 +166,9 @@ function renderSoundButton(video: VideoController, options: CardOptions) {
132
166
  <button
133
167
  type="button"
134
168
  class="card-sound"
135
- aria-label=${video.muted ? options.soundOnLabel : options.soundOffLabel}
169
+ aria-label=${video.muted
170
+ ? options.labels.soundOn
171
+ : options.labels.soundOff}
136
172
  @click=${() => video.toggleMuted()}
137
173
  >
138
174
  ${icon(video.muted ? "soundOff" : "soundOn")}
@@ -143,29 +179,45 @@ function renderSoundButton(video: VideoController, options: CardOptions) {
143
179
  /**
144
180
  * A 9:16 card with the Story cover and, with a media_url, the video looping
145
181
  * muted over it (see renderMedia). A button with a play icon in the middle
146
- * covers the card, and a sound button shows while the video plays. The sound
147
- * button is beside the card's button, not inside it: a button can't contain
148
- * another.
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.
149
187
  */
150
188
  export function renderCard(
151
189
  story: StoryMedia,
152
190
  video: VideoController,
153
191
  options: CardOptions,
154
192
  ) {
193
+ const withVideo = options.withVideo ?? true;
194
+
155
195
  return html`
156
- <div class="card">
157
- ${renderMedia(story, video)}
196
+ <div
197
+ class="card"
198
+ ${ref(options.ref)}
199
+ @click=${{ handleEvent: () => options.onPress?.(), capture: true }}
200
+ >
201
+ ${renderMedia(story, video, { withVideo })}
158
202
  <button
159
203
  type="button"
160
204
  class="card-open"
205
+ ${ref(options.openRef)}
161
206
  aria-label=${options.label}
162
207
  @click=${options.onSelect}
163
208
  >
164
209
  <span class="play" aria-hidden="true">${icon("play")}</span>
165
210
  </button>
166
- ${hasVideo(story, video) && !video.paused
211
+ ${withVideo && hasVideo(story, video) && !video.paused
167
212
  ? renderSoundButton(video, options)
168
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}
169
221
  </div>
170
222
  `;
171
223
  }