@vtex/ads-stories 0.5.0 → 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 (48) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +29 -297
  3. package/dist/cdn/vtex-ads-stories.js +438 -113
  4. package/dist/cdn/vtex-ads-stories.js.map +1 -1
  5. package/dist/cjs/index.cjs +909 -186
  6. package/dist/cjs/index.cjs.map +1 -1
  7. package/dist/cjs/index.d.cts +42 -196
  8. package/dist/cjs/react.cjs.map +1 -1
  9. package/dist/cjs/react.d.cts +7 -1
  10. package/dist/cjs/story-DAiAN9v-.d.cts +260 -0
  11. package/dist/esm/index.d.ts +42 -196
  12. package/dist/esm/index.js +933 -209
  13. package/dist/esm/index.js.map +1 -1
  14. package/dist/esm/react.d.ts +7 -1
  15. package/dist/esm/story-DAiAN9v-.d.ts +260 -0
  16. package/package.json +1 -1
  17. package/src/commerce-events.ts +93 -0
  18. package/src/components/card/card.ts +16 -3
  19. package/src/components/carousel/carousel-skeleton.ts +113 -0
  20. package/src/components/carousel/carousel.ts +53 -8
  21. package/src/components/carousel/index.ts +7 -0
  22. package/src/components/events/events-controller.ts +23 -13
  23. package/src/components/icons/assets/minus.svg +1 -0
  24. package/src/components/icons/assets/plus.svg +1 -0
  25. package/src/components/icons/assets/trash.svg +1 -0
  26. package/src/components/icons/assets/warning-circle-fill.svg +1 -0
  27. package/src/components/icons/index.ts +8 -0
  28. package/src/components/media/index.ts +7 -1
  29. package/src/components/media/media.styles.ts +113 -0
  30. package/src/components/media/media.ts +108 -11
  31. package/src/components/media/video-controller.ts +80 -6
  32. package/src/components/player/player.ts +42 -17
  33. package/src/components/product/cta.ts +3 -3
  34. package/src/components/product/index.ts +2 -0
  35. package/src/components/product/product.styles.ts +63 -6
  36. package/src/components/product/product.ts +130 -29
  37. package/src/index.ts +8 -0
  38. package/src/locales/en.ts +13 -3
  39. package/src/locales/es.ts +13 -3
  40. package/src/locales/pt.ts +13 -3
  41. package/src/locales/types.ts +22 -2
  42. package/src/react.ts +6 -0
  43. package/src/story/story.ts +188 -16
  44. package/src/utils/hydrate-products.ts +30 -6
  45. package/src/utils/media-ready.ts +58 -0
  46. package/src/utils/safe-url.ts +36 -0
  47. package/src/utils/send-event.ts +1 -1
  48. package/src/utils/http-url.ts +0 -12
@@ -3,19 +3,28 @@ import type { Channel } from "@vtex/ads-core";
3
3
  import { cardStyles, renderCard } from "../components/card";
4
4
  import {
5
5
  CarouselController,
6
+ carouselSkeletonStyles,
6
7
  carouselStyles,
7
8
  RENDERED_SIDE,
9
+ renderCarouselSkeleton,
8
10
  type Slide,
9
11
  } from "../components/carousel";
10
12
  import { StoryEventsController, type ViewTarget } from "../components/events";
11
- import { VideoController } from "../components/media";
13
+ import {
14
+ mediaStyles,
15
+ prefersReducedMotion,
16
+ VideoController,
17
+ } from "../components/media";
12
18
  import {
13
19
  DEFAULT_LOCALE,
20
+ focusCartAction,
14
21
  priceFormatter,
15
22
  productStyles,
16
23
  toCardCta,
17
24
  toCardProduct,
25
+ type CardProduct,
18
26
  type FetchedProduct,
27
+ type ProductCartActions,
19
28
  } from "../components/product";
20
29
  import {
21
30
  neighborOffsets,
@@ -30,7 +39,14 @@ import {
30
39
  type StoryProductDetails,
31
40
  } from "../utils/hydrate-products";
32
41
  import { fetchStories } from "../utils/fetch-story";
42
+ import { httpUrl } from "../utils/safe-url";
43
+ import { decodeImage, firstReady } from "../utils/media-ready";
33
44
  import { labelsFor, type StoryLabels } from "../locales";
45
+ import {
46
+ addToCartEvent,
47
+ removeFromCartEvent,
48
+ type StoryCartItem,
49
+ } from "../commerce-events";
34
50
  import { TAG_NAME } from "../tag-name";
35
51
 
36
52
  export { TAG_NAME } from "../tag-name";
@@ -77,6 +93,10 @@ const hydrationConverter = {
77
93
  value === "none" ? ("none" as const) : undefined,
78
94
  };
79
95
 
96
+ // A cart line is a SKU from a seller: the stepper counts each pair apart.
97
+ const cartKey = ({ sku, seller }: StoryCartItem) =>
98
+ JSON.stringify([sku, seller ?? ""]);
99
+
80
100
  // LitElement is importable where HTMLElement doesn't exist (SSR, Node): Lit
81
101
  // falls back to a minimal shim there.
82
102
  export class VtexAdsStoryCarouselElement extends LitElement {
@@ -94,6 +114,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
94
114
  labelViewProduct: { attribute: "label-view-product" },
95
115
  hydration: { converter: hydrationConverter },
96
116
  hydrationTimeout: { type: Number, attribute: "hydration-timeout" },
117
+ slideDuration: { type: Number, attribute: "slide-duration" },
97
118
  inactiveAutoplay: {
98
119
  type: Boolean,
99
120
  attribute: "inactive-autoplay",
@@ -101,6 +122,8 @@ export class VtexAdsStoryCarouselElement extends LitElement {
101
122
  },
102
123
  stories: { state: true },
103
124
  products: { state: true },
125
+ requesting: { state: true },
126
+ mediaLoading: { state: true },
104
127
  };
105
128
 
106
129
  /** Required. The publisher the ads are requested for. */
@@ -158,6 +181,12 @@ export class VtexAdsStoryCarouselElement extends LitElement {
158
181
  * only the highlighted card plays.
159
182
  */
160
183
  declare inactiveAutoplay: boolean;
184
+ /**
185
+ * With more than one Story, how long each one stays highlighted before the
186
+ * next, in milliseconds (default 5000). Zero: the highlight moves only by
187
+ * hand. A change starts the time over; it doesn't request again.
188
+ */
189
+ declare slideDuration?: number;
161
190
 
162
191
  /** The Stories shown: none while loading, on error or with none. */
163
192
  declare private stories: StoryAd[];
@@ -168,6 +197,26 @@ export class VtexAdsStoryCarouselElement extends LitElement {
168
197
  */
169
198
  declare private products?: Map<string, StoryProductDetails> | "loading";
170
199
 
200
+ /**
201
+ * The ad request is pending (and has what it needs to go out): a skeleton
202
+ * stands in for the carousel until the Stories arrive.
203
+ */
204
+ declare private requesting: boolean;
205
+
206
+ /**
207
+ * The first Story's media is still loading: a skeleton covers the cards
208
+ * until its cover or its video is ready (or MEDIA_TIMEOUT passes), so the
209
+ * first card doesn't show up piece by piece. Meanwhile, the cards load
210
+ * underneath, their videos without playing, and no event goes out.
211
+ */
212
+ declare private mediaLoading: boolean;
213
+
214
+ /**
215
+ * Cancels the wait for the media in progress: when other Stories replace
216
+ * its Stories, or the element leaves the page.
217
+ */
218
+ private mediaWait?: AbortController;
219
+
171
220
  /**
172
221
  * Cancels the request in progress. Kept, already aborted, when leaving the
173
222
  * page cancelled it, so connecting again requests once more.
@@ -180,14 +229,27 @@ export class VtexAdsStoryCarouselElement extends LitElement {
180
229
  display: block;
181
230
  font-family: var(--vtex-ads-story-font-family, inherit);
182
231
  color: var(--vtex-ads-story-color-text, inherit);
232
+ --_pill-radius: var(--vtex-ads-story-radius, 16px);
233
+ --_pill-inset: 8px;
234
+ --_button-radius: var(--vtex-ads-story-radius, 999px);
183
235
  }
184
236
  `,
185
237
  cardStyles,
238
+ mediaStyles,
186
239
  productStyles,
187
240
  carouselStyles,
241
+ carouselSkeletonStyles,
188
242
  playerStyles,
189
243
  ];
190
244
 
245
+ /**
246
+ * How many of each SKU, from each seller (see cartKey), were added since
247
+ * the player opened, for its stepper. It doesn't read the store's cart: it
248
+ * counts the add and remove events sent, and starts over each time the
249
+ * player opens, as the cart may have changed meanwhile.
250
+ */
251
+ private readonly cartQuantities = new Map<string, number>();
252
+
191
253
  /**
192
254
  * One per rendered card, by its key (see Slide): a Story can show in more
193
255
  * than one card, each with its own video.
@@ -215,7 +277,9 @@ export class VtexAdsStoryCarouselElement extends LitElement {
215
277
  }
216
278
  },
217
279
  // The player shows the highlighted Story: the highlight stays on it.
218
- locked: () => this.player.isOpen,
280
+ locked: () => this.player.isOpen || this.mediaLoading,
281
+ slideDuration: () => this.slideDuration,
282
+ reducedMotion: prefersReducedMotion,
219
283
  });
220
284
 
221
285
  private readonly player = new PlayerController(this, {
@@ -234,6 +298,8 @@ export class VtexAdsStoryCarouselElement extends LitElement {
234
298
  super();
235
299
  this.inactiveAutoplay = false;
236
300
  this.stories = [];
301
+ this.requesting = false;
302
+ this.mediaLoading = false;
237
303
  }
238
304
 
239
305
  // Lit keeps the card's DOM when the element is moved (removed and appended
@@ -254,6 +320,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
254
320
  disconnectedCallback() {
255
321
  super.disconnectedCallback();
256
322
  this.request?.abort();
323
+ this.mediaWait?.abort();
257
324
  }
258
325
 
259
326
  protected willUpdate(changed: PropertyValues<this>) {
@@ -288,6 +355,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
288
355
 
289
356
  // The Stories shown no longer match the request either.
290
357
  this.player.close();
358
+ this.requesting = false;
291
359
  this.showStories([]);
292
360
 
293
361
  // Off the page (an attribute changed just before the element was
@@ -297,6 +365,9 @@ export class VtexAdsStoryCarouselElement extends LitElement {
297
365
  return;
298
366
  }
299
367
 
368
+ this.requesting = Boolean(
369
+ this.publisherId && this.sessionId && this.placement,
370
+ );
300
371
  const stories = await fetchStories(this, {
301
372
  signal: request.signal,
302
373
  timeout: this.timeout,
@@ -305,6 +376,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
305
376
  // Cancelled meanwhile, by a newer request or by leaving the page: this
306
377
  // response is not shown.
307
378
  if (request.signal.aborted) return;
379
+ this.requesting = false;
308
380
 
309
381
  const hydration = this.activeHydration;
310
382
  if (!hydration || !stories.some((story) => story.product)) {
@@ -344,7 +416,42 @@ export class VtexAdsStoryCarouselElement extends LitElement {
344
416
  this.afterRender = undefined;
345
417
  this.carousel.reset(stories.length);
346
418
  this.stories = stories;
419
+ void this.waitForFirstMedia(stories);
420
+ }
421
+
422
+ /**
423
+ * Shows the cards once the first Story's cover or video is ready: whichever
424
+ * loads first, or once both failed. Only then are the Stories impressed
425
+ * and do their videos play, from the start.
426
+ */
427
+ private async waitForFirstMedia(stories: StoryAd[]) {
428
+ this.mediaWait?.abort();
429
+ const wait = new AbortController();
430
+ this.mediaWait = wait;
431
+
432
+ const cover = httpUrl(stories[0]?.poster_url);
433
+ const video = httpUrl(stories[0]?.media_url);
434
+ const checks: Promise<boolean>[] = [];
435
+ if (cover) checks.push(decodeImage(cover));
436
+ // The first card's: the highlighted one, after carousel.reset().
437
+ if (video) checks.push(this.videoFor(this.carousel.activeKey).ready);
438
+
439
+ this.mediaLoading = checks.length > 0;
440
+ await firstReady(checks, wait.signal);
441
+ // Other Stories came meanwhile: they wait for their own media. Leaving
442
+ // the page ends the wait with the cards shown.
443
+ if (this.mediaWait !== wait) return;
444
+
445
+ this.mediaWait = undefined;
446
+ this.mediaLoading = false;
347
447
  this.events.impress(stories);
448
+ this.afterRender = () => {
449
+ if (!this.isConnected) return;
450
+ for (const cardVideo of this.cardVideos.values()) cardVideo.resume();
451
+ };
452
+ // Without media to wait for, mediaLoading didn't change: nothing else
453
+ // asks for the render that sends the impressions.
454
+ this.requestUpdate();
348
455
  }
349
456
 
350
457
  /**
@@ -355,6 +462,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
355
462
  */
356
463
  private *viewTargets(): Generator<ViewTarget> {
357
464
  const { stories } = this;
465
+ if (this.mediaLoading) return;
358
466
 
359
467
  if (!this.player.isExpanded) {
360
468
  for (const [card, { key, index }] of this.carousel.visibleCards()) {
@@ -425,6 +533,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
425
533
  private openPlayer({ productOpen = false } = {}) {
426
534
  if (this.player.isOpen) return;
427
535
 
536
+ this.cartQuantities.clear();
428
537
  // While the player is open, the card behind it stops on its cover.
429
538
  this.activeVideo?.pause();
430
539
  void this.player.open({ productOpen });
@@ -508,6 +617,7 @@ export class VtexAdsStoryCarouselElement extends LitElement {
508
617
  ),
509
618
  labels: this.labels,
510
619
  withVideo: active || (this.inactiveAutoplay && !hidden),
620
+ autoplay: !this.mediaLoading,
511
621
  product: this.productOf(story),
512
622
  onSelect: active
513
623
  ? () => this.openPlayer()
@@ -529,8 +639,28 @@ export class VtexAdsStoryCarouselElement extends LitElement {
529
639
  const { stories } = this;
530
640
  const index = this.carousel.active;
531
641
  const active = stories[index];
532
- if (!active) return nothing;
642
+ if (!active && !this.requesting) return nothing;
643
+
644
+ const loading = this.requesting || this.mediaLoading;
533
645
 
646
+ return html`
647
+ <div
648
+ class="root"
649
+ ?data-loading=${loading}
650
+ ?data-requesting=${this.requesting}
651
+ >
652
+ ${active
653
+ ? this.carousel.render(stories, this.renderSlide, this.labels)
654
+ : nothing}
655
+ ${renderCarouselSkeleton({ done: !loading })}
656
+ </div>
657
+ ${active ? this.renderPlayer(active) : nothing}
658
+ `;
659
+ }
660
+
661
+ private renderPlayer(active: StoryAd) {
662
+ const { stories } = this;
663
+ const index = this.carousel.active;
534
664
  const neighbors = neighborOffsets(stories.length, index).map((offset) => {
535
665
  const neighbor = (index + offset + stories.length) % stories.length;
536
666
  return {
@@ -540,19 +670,61 @@ export class VtexAdsStoryCarouselElement extends LitElement {
540
670
  };
541
671
  });
542
672
 
543
- return html`
544
- <div class="root">
545
- ${this.carousel.render(stories, this.renderSlide, this.labels)}
546
- </div>
547
- ${this.player.render(active, {
548
- labels: this.labels,
549
- navigation: stories.length > 1,
550
- neighbors,
551
- product: this.productOf(active),
552
- cta: toCardCta(active),
553
- onPress: () => this.events.click(active),
554
- })}
555
- `;
673
+ const product = this.productOf(active);
674
+
675
+ return this.player.render(active, {
676
+ labels: this.labels,
677
+ navigation: stories.length > 1,
678
+ neighbors,
679
+ product,
680
+ cta: toCardCta(active),
681
+ productActions: this.cartActionsFor(product),
682
+ onPress: () => this.events.click(active),
683
+ });
684
+ }
685
+
686
+ private cartActionsFor(
687
+ product?: CardProduct,
688
+ ): ProductCartActions | undefined {
689
+ const sku = product?.sku;
690
+ if (!sku) return undefined;
691
+
692
+ const item = { sku, seller: product.seller };
693
+ return {
694
+ cartQuantity: this.cartQuantities.get(cartKey(item)),
695
+ onAddToCart: () => this.changeCart(item, 1),
696
+ onRemoveFromCart: () => this.changeCart(item, -1),
697
+ };
698
+ }
699
+
700
+ /**
701
+ * Adds one of `item` to the stepper's count, or removes one, and tells the
702
+ * store, which changes its cart: the element has none. When add to cart
703
+ * and the stepper swap places, the focus moves to the one now shown.
704
+ */
705
+ private changeCart(item: StoryCartItem, delta: 1 | -1) {
706
+ const key = cartKey(item);
707
+ const before = this.cartQuantities.get(key) ?? 0;
708
+ const after = Math.max(0, before + delta);
709
+ if (after === before) return;
710
+
711
+ if (after > 0) this.cartQuantities.set(key, after);
712
+ else this.cartQuantities.delete(key);
713
+ this.requestUpdate();
714
+
715
+ this.dispatchEvent(
716
+ delta > 0 ? addToCartEvent(item) : removeFromCartEvent(item),
717
+ );
718
+
719
+ let swapped: "stepper" | "add" | undefined;
720
+ if (before === 0) swapped = "stepper";
721
+ else if (after === 0) swapped = "add";
722
+ if (!swapped) return;
723
+
724
+ const action = swapped;
725
+ this.updateComplete.then(
726
+ () => this.shadowRoot && focusCartAction(this.shadowRoot, action),
727
+ );
556
728
  }
557
729
  }
558
730
 
@@ -41,6 +41,23 @@ export interface StoryProductDetails {
41
41
  available?: boolean;
42
42
  }
43
43
 
44
+ // A price the card can show: an amount (0 included, as the strategy says),
45
+ // with the "from" price only when it is above it, as intelligentSearchPrice
46
+ // reads them. A store's own reader may return anything (a missing amount,
47
+ // NaN, a string): then the ad server's price shows instead.
48
+ function toShownPrice(
49
+ value: ProductPrice | undefined,
50
+ ): ProductPrice | undefined {
51
+ const isAmount = (amount: unknown): amount is number =>
52
+ typeof amount === "number" && Number.isFinite(amount) && amount >= 0;
53
+
54
+ if (!isAmount(value?.price)) return undefined;
55
+ const { price, listPrice } = value;
56
+ return isAmount(listPrice) && listPrice > price
57
+ ? { price, listPrice }
58
+ : { price };
59
+ }
60
+
44
61
  export interface HydrateProductsOptions {
45
62
  signal?: AbortSignal;
46
63
  timeout?: number;
@@ -67,12 +84,19 @@ export async function hydrateStoryProducts(
67
84
 
68
85
  for (const { story, product, offer } of hydrated.stories[placement] ?? []) {
69
86
  if (!product || !offer) continue;
70
- const price = hydration.price(product, offer);
71
- const available = hydration.available?.(product, offer);
72
- products.set(story.ad_id, {
73
- ...(price && { price }),
74
- ...(available !== undefined && { available }),
75
- });
87
+ try {
88
+ const price = toShownPrice(hydration.price(product, offer));
89
+ const available = hydration.available?.(product, offer);
90
+ products.set(story.ad_id, {
91
+ ...(price && { price }),
92
+ ...(available !== undefined && { available }),
93
+ });
94
+ } catch (error) {
95
+ console.error(
96
+ `[${TAG_NAME}] Product details failed for ad ${story.ad_id}`,
97
+ error,
98
+ );
99
+ }
76
100
  }
77
101
  } catch (error) {
78
102
  // As for the Story request: a cancelled or timed out request needs no
@@ -0,0 +1,58 @@
1
+ import { withTimeout } from "./with-timeout";
2
+
3
+ /** How long the first Story's media may take before it shows anyway, in ms. */
4
+ export const MEDIA_TIMEOUT = 3000;
5
+
6
+ /**
7
+ * Loads and decodes an image, so it paints at once when it shows. Resolves
8
+ * true once it is ready and false if it fails. Never rejects.
9
+ *
10
+ * Without `Image` or `decode` (SSR, old browsers, jsdom) there is nothing to
11
+ * wait for: it resolves true at once.
12
+ */
13
+ export function decodeImage(url: string): Promise<boolean> {
14
+ if (typeof Image === "undefined") return Promise.resolve(true);
15
+
16
+ const image = new Image();
17
+ image.src = url;
18
+ if (!image.decode) return Promise.resolve(true);
19
+ return image.decode().then(
20
+ () => true,
21
+ () => false,
22
+ );
23
+ }
24
+
25
+ /**
26
+ * Waits for the first of `checks` to be ready: resolves when one resolves
27
+ * true, when all resolved false (nothing left to wait for), after
28
+ * MEDIA_TIMEOUT, or when `signal` aborts. Never rejects.
29
+ */
30
+ export function firstReady(
31
+ checks: readonly Promise<boolean>[],
32
+ signal?: AbortSignal,
33
+ ): Promise<void> {
34
+ if (!checks.length) return Promise.resolve();
35
+
36
+ const limit = withTimeout(undefined, MEDIA_TIMEOUT, signal);
37
+
38
+ return new Promise<void>((resolve) => {
39
+ const done = () => {
40
+ limit.clear();
41
+ resolve();
42
+ };
43
+ if (limit.signal.aborted) return done();
44
+ limit.signal.addEventListener("abort", done, { once: true });
45
+
46
+ let failed = 0;
47
+ for (const check of checks) {
48
+ check.then(
49
+ (ready) => {
50
+ if (ready || ++failed === checks.length) done();
51
+ },
52
+ () => {
53
+ if (++failed === checks.length) done();
54
+ },
55
+ );
56
+ }
57
+ });
58
+ }
@@ -0,0 +1,36 @@
1
+ // Only absolute http(s) URLs reach the DOM or the network. Relative and
2
+ // protocol-relative ones ("/a.jpg", "//host/a.jpg") don't parse without a
3
+ // base, so they're out.
4
+ export function httpUrl(value: string | undefined) {
5
+ if (!value) return null;
6
+ try {
7
+ const { protocol } = new URL(value);
8
+ return protocol === "https:" || protocol === "http:" ? value : null;
9
+ } catch {
10
+ return null;
11
+ }
12
+ }
13
+
14
+ const STORE_BASE = "https://store.invalid";
15
+
16
+ // A path on the store the Story runs in ("/product/p"), resolved the way the
17
+ // browser would, or null when it lands on another host ("//evil.com",
18
+ // "/\\evil.com", "/\t/evil.com").
19
+ function storePath(value: string) {
20
+ try {
21
+ const url = new URL(value, STORE_BASE);
22
+ if (url.origin !== STORE_BASE || url.pathname.startsWith("//")) {
23
+ return null;
24
+ }
25
+ return `${url.pathname}${url.search}${url.hash}`;
26
+ } catch {
27
+ return null;
28
+ }
29
+ }
30
+
31
+ // A destination is an absolute http(s) URL or a path on the store the
32
+ // Story runs in.
33
+ export function destinationUrl(value: string | undefined) {
34
+ if (!value) return null;
35
+ return value.startsWith("/") ? storePath(value) : httpUrl(value);
36
+ }
@@ -1,4 +1,4 @@
1
- import { httpUrl } from "./http-url";
1
+ import { httpUrl } from "./safe-url";
2
2
  import { TAG_NAME } from "../tag-name";
3
3
 
4
4
  // A CORS-safelisted type: the browser sends the event without a preflight
@@ -1,12 +0,0 @@
1
- // Only absolute http(s) URLs reach the DOM or the network. Relative and
2
- // protocol-relative ones ("/a.jpg", "//host/a.jpg") don't parse without a
3
- // base, so they're out.
4
- export function httpUrl(value: string | undefined) {
5
- if (!value) return null;
6
- try {
7
- const { protocol } = new URL(value);
8
- return protocol === "https:" || protocol === "http:" ? value : null;
9
- } catch {
10
- return null;
11
- }
12
- }