@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
@@ -0,0 +1,235 @@
1
+ import { html, nothing } from "lit";
2
+ import type { StoryLabels } from "../../locales";
3
+ import { icon } from "../icons";
4
+ import { httpUrl } from "../../utils/http-url";
5
+ import type { StoryAd } from "../../types";
6
+ import type { StoryProductDetails } from "../../utils/hydrate-products";
7
+ import { readProductPrice } from "./price";
8
+
9
+ /** What the card shows of the Story's product, with the prices formatted. */
10
+ export interface CardProduct {
11
+ name: string;
12
+ imageUrl?: string;
13
+ price?: string;
14
+ /** The "from" price, struck through. Only with a price. */
15
+ listPrice?: string;
16
+ /** The product page, opened by view product link button. */
17
+ url?: string;
18
+ /** Accessible name of the product button: name and prices. */
19
+ label: string;
20
+ /**
21
+ * The product's details are being fetched: placeholders show in their
22
+ * place (for now, the price's).
23
+ */
24
+ isLoading?: boolean;
25
+ /**
26
+ * The text shown in place of the price ("Esgotado") when the fetched
27
+ * product can't be bought. Add to cart then becomes a disabled button.
28
+ */
29
+ soldOut?: string;
30
+ }
31
+
32
+ /**
33
+ * The Story's product as fetched: `"loading"` while the request runs, its
34
+ * details once found, or undefined without them (no request, not found,
35
+ * failed). Without a fetched price, the ad server's shows.
36
+ */
37
+ export type FetchedProduct = StoryProductDetails | "loading" | undefined;
38
+
39
+ /**
40
+ * The card's view of a Story's product, or undefined when the Story has none
41
+ * (its destination is a link) or the product has no name.
42
+ *
43
+ * The price is the fetched one when there is one; while the product loads,
44
+ * none; and otherwise the ad server's, from `product_metadata`. A fetched
45
+ * product that can't be bought shows `labels.soldOut` instead.
46
+ */
47
+ export function toCardProduct(
48
+ story: Pick<StoryAd, "product" | "destination_url">,
49
+ format: (amount: number) => string,
50
+ labels: StoryLabels,
51
+ fetched?: FetchedProduct,
52
+ ): CardProduct | undefined {
53
+ const product = story.product;
54
+ const name = product?.product_name?.trim();
55
+ if (!product || !name) return undefined;
56
+
57
+ const base = {
58
+ name,
59
+ imageUrl: httpUrl(product.image_url) ?? undefined,
60
+ url: httpUrl(story.destination_url) ?? undefined,
61
+ };
62
+
63
+ if (fetched === "loading") {
64
+ return { ...base, label: labels.product(name), isLoading: true };
65
+ }
66
+ if (fetched?.available === false) {
67
+ return {
68
+ ...base,
69
+ label: labels.product(name, labels.soldOut),
70
+ soldOut: labels.soldOut,
71
+ };
72
+ }
73
+
74
+ const amounts = fetched?.price ?? readProductPrice(product.product_metadata);
75
+ const price = amounts && format(amounts.price);
76
+ const listPrice =
77
+ amounts?.listPrice === undefined ? undefined : format(amounts.listPrice);
78
+
79
+ return {
80
+ ...base,
81
+ price,
82
+ listPrice,
83
+ label: labels.product(name, price, listPrice),
84
+ };
85
+ }
86
+
87
+ const priceSkeleton = html`
88
+ <span
89
+ class="product-price product-loading product-price-loading"
90
+ aria-hidden="true"
91
+ ></span>
92
+ `;
93
+
94
+ // The add to cart button's place, while the product loads. Hidden from
95
+ // assistive technology, as the price's.
96
+ const addToCartSkeleton = html`
97
+ <span
98
+ class="product-loading product-add-to-cart-loading"
99
+ aria-hidden="true"
100
+ ></span>
101
+ `;
102
+
103
+ // The price and, on sale, the "from" price struck through beside it. While
104
+ // the product loads, its placeholder; sold out, the sold out text; without a
105
+ // price, nothing.
106
+ function renderPrice({ isLoading, soldOut, price, listPrice }: CardProduct) {
107
+ if (isLoading) return priceSkeleton;
108
+ if (soldOut) {
109
+ return html`<span class="product-price product-sold-out">${soldOut}</span>`;
110
+ }
111
+ if (!price) return nothing;
112
+
113
+ return html`
114
+ <span class="product-price">
115
+ <span>${price}</span>
116
+ ${listPrice
117
+ ? html`<s class="product-list-price">${listPrice}</s>`
118
+ : nothing}
119
+ </span>
120
+ `;
121
+ }
122
+
123
+ // Image, name and prices: what the pill shows.
124
+ function renderSummary(product: CardProduct) {
125
+ return html`
126
+ ${product.imageUrl
127
+ ? html`<img class="product-image" alt="" src=${product.imageUrl} />`
128
+ : nothing}
129
+ <span class="product-info">
130
+ <span class="product-name">${product.name}</span>
131
+ ${renderPrice(product)}
132
+ </span>
133
+ `;
134
+ }
135
+
136
+ /**
137
+ * The product pill on the carousel card: image, name (up to two lines),
138
+ * price and, on sale, the "from" price struck through. Without a price, only
139
+ * the name. A button of its own, beside the card's (a button can't contain
140
+ * another).
141
+ */
142
+ export function renderProduct(product: CardProduct, onSelect: () => void) {
143
+ return html`
144
+ <button
145
+ type="button"
146
+ class="card-product"
147
+ aria-label=${product.label}
148
+ @click=${onSelect}
149
+ >
150
+ ${renderSummary(product)}
151
+ </button>
152
+ `;
153
+ }
154
+
155
+ export interface ExpandableProductOptions {
156
+ /** Whether the panel with the actions shows. */
157
+ open: boolean;
158
+ /** Called by the pill's button, to open or close the panel. */
159
+ onToggle: () => void;
160
+ /** Id of the panel, for the button's aria-controls. */
161
+ panelId: string;
162
+ /** The texts: add to cart, its disabled "unavailable" and view product. */
163
+ labels: StoryLabels;
164
+ }
165
+
166
+ // Add to cart: its placeholder while the product loads, and a disabled
167
+ // button when sold out.
168
+ function renderAddToCart(
169
+ { isLoading, soldOut }: CardProduct,
170
+ { labels }: ExpandableProductOptions,
171
+ ) {
172
+ if (isLoading) return addToCartSkeleton;
173
+ if (soldOut) {
174
+ return html`
175
+ <button type="button" class="product-action product-unavailable" disabled>
176
+ ${labels.unavailable}
177
+ </button>
178
+ `;
179
+ }
180
+ return html`
181
+ <button type="button" class="product-action product-add-to-cart">
182
+ ${labels.addToCart}
183
+ </button>
184
+ `;
185
+ }
186
+
187
+ /**
188
+ * The product pill in the player. The pill is a button that opens a panel
189
+ * below it, as in the prototype, with "Adicionar ao carrinho" (a placeholder
190
+ * while the product loads, a disabled "Produto indisponível" when sold out)
191
+ * and "Ver produto" (the product page, in a new tab; only with a URL). Open,
192
+ * the pill turns white.
193
+ *
194
+ * Adding to the cart does nothing yet: it will emit an event for the store
195
+ * to handle.
196
+ */
197
+ export function renderExpandableProduct(
198
+ product: CardProduct,
199
+ options: ExpandableProductOptions,
200
+ ) {
201
+ const { open } = options;
202
+
203
+ return html`
204
+ <div class="card-product product-expandable" ?data-open=${open}>
205
+ <button
206
+ type="button"
207
+ class="product-summary"
208
+ aria-label=${product.label}
209
+ aria-expanded=${open ? "true" : "false"}
210
+ aria-controls=${options.panelId}
211
+ @click=${options.onToggle}
212
+ >
213
+ ${renderSummary(product)}
214
+ <span class="product-toggle">${icon("caretUp")}</span>
215
+ </button>
216
+ <div id=${options.panelId} class="product-panel" ?inert=${!open}>
217
+ <div class="product-actions">
218
+ ${renderAddToCart(product, options)}
219
+ ${product.url
220
+ ? html`
221
+ <a
222
+ class="product-action product-view"
223
+ href=${product.url}
224
+ target="_blank"
225
+ rel="noopener noreferrer"
226
+ >
227
+ ${options.labels.viewProduct}
228
+ </a>
229
+ `
230
+ : nothing}
231
+ </div>
232
+ </div>
233
+ </div>
234
+ `;
235
+ }
package/src/index.ts CHANGED
@@ -1 +1,9 @@
1
- export { VtexAdsStoryElement, defineVtexAdsStories, TAG_NAME } from "./story";
1
+ export {
2
+ VtexAdsStoryCarouselElement,
3
+ defineVtexAdsStoryCarousel,
4
+ TAG_NAME,
5
+ } from "./story";
6
+ export type {
7
+ StoryHydration,
8
+ StoryProductDetails,
9
+ } from "./utils/hydrate-products";
@@ -0,0 +1,29 @@
1
+ import type { StoryLabels } from "./types";
2
+
3
+ /** The texts in English. */
4
+ export const en: StoryLabels = {
5
+ watch: "Watch video",
6
+ show: "Show video",
7
+ carousel: "Videos",
8
+ carouselRole: "carousel",
9
+ previous: "Previous video",
10
+ next: "Next video",
11
+ player: "Video",
12
+ expand: "Expand video",
13
+ collapse: "Collapse video",
14
+ close: "Close video",
15
+ play: "Play video",
16
+ pause: "Pause video",
17
+ soundOn: "Turn sound on",
18
+ soundOff: "Turn sound off",
19
+ addToCart: "Add to cart",
20
+ unavailable: "Product unavailable",
21
+ soldOut: "Sold out",
22
+ viewProduct: "View product",
23
+ product: (name, price, listPrice) => {
24
+ if (price && listPrice) return `${name}, was ${listPrice}, now ${price}`;
25
+ return price ? `${name}, ${price}` : name;
26
+ },
27
+ position: (label, index, count) =>
28
+ count > 1 ? `${label} ${index + 1} of ${count}` : label,
29
+ };
@@ -0,0 +1,30 @@
1
+ import type { StoryLabels } from "./types";
2
+
3
+ /** The texts in Spanish. */
4
+ export const es: StoryLabels = {
5
+ watch: "Ver video",
6
+ show: "Mostrar video",
7
+ carousel: "Videos",
8
+ carouselRole: "carrusel",
9
+ previous: "Video anterior",
10
+ next: "Video siguiente",
11
+ player: "Video",
12
+ expand: "Ampliar video",
13
+ collapse: "Reducir video",
14
+ close: "Cerrar video",
15
+ play: "Reproducir video",
16
+ pause: "Pausar video",
17
+ soundOn: "Activar sonido",
18
+ soundOff: "Desactivar sonido",
19
+ addToCart: "Agregar al carrito",
20
+ unavailable: "Producto no disponible",
21
+ soldOut: "Agotado",
22
+ viewProduct: "Ver producto",
23
+ product: (name, price, listPrice) => {
24
+ if (price && listPrice)
25
+ return `${name}, antes ${listPrice}, ahora ${price}`;
26
+ return price ? `${name}, ${price}` : name;
27
+ },
28
+ position: (label, index, count) =>
29
+ count > 1 ? `${label} ${index + 1} de ${count}` : label,
30
+ };
@@ -0,0 +1,36 @@
1
+ import { en } from "./en";
2
+ import { es } from "./es";
3
+ import { pt } from "./pt";
4
+ import type { StoryLabels } from "./types";
5
+
6
+ export type { StoryLabels } from "./types";
7
+ export { en } from "./en";
8
+ export { es } from "./es";
9
+ export { pt } from "./pt";
10
+
11
+ export interface StoryLabelOverrides {
12
+ addToCart?: string;
13
+ viewProduct?: string;
14
+ }
15
+
16
+ const BY_LANGUAGE = new Map<string, StoryLabels>([
17
+ ["pt", pt],
18
+ ["es", es],
19
+ ["en", en],
20
+ ]);
21
+
22
+ export function labelsFor(
23
+ locale: string,
24
+ overrides: StoryLabelOverrides = {},
25
+ ): StoryLabels {
26
+ const language = locale.split("-")[0].toLowerCase();
27
+ const labels = BY_LANGUAGE.get(language) ?? pt;
28
+ const addToCart = overrides.addToCart?.trim();
29
+ const viewProduct = overrides.viewProduct?.trim();
30
+
31
+ return {
32
+ ...labels,
33
+ ...(addToCart && { addToCart }),
34
+ ...(viewProduct && { viewProduct }),
35
+ };
36
+ }
@@ -0,0 +1,29 @@
1
+ import type { StoryLabels } from "./types";
2
+
3
+ /** The texts in Portuguese, the default. */
4
+ export const pt: StoryLabels = {
5
+ watch: "Assistir vídeo",
6
+ show: "Mostrar vídeo",
7
+ carousel: "Vídeos",
8
+ carouselRole: "carrossel",
9
+ previous: "Vídeo anterior",
10
+ next: "Próximo vídeo",
11
+ player: "Vídeo",
12
+ expand: "Expandir vídeo",
13
+ collapse: "Reduzir vídeo",
14
+ close: "Fechar vídeo",
15
+ play: "Reproduzir vídeo",
16
+ pause: "Pausar vídeo",
17
+ soundOn: "Ativar som",
18
+ soundOff: "Desativar som",
19
+ addToCart: "Adicionar ao carrinho",
20
+ unavailable: "Produto indisponível",
21
+ soldOut: "Esgotado",
22
+ viewProduct: "Ver produto",
23
+ product: (name, price, listPrice) => {
24
+ if (price && listPrice) return `${name}, de ${listPrice} por ${price}`;
25
+ return price ? `${name}, ${price}` : name;
26
+ },
27
+ position: (label, index, count) =>
28
+ count > 1 ? `${label} ${index + 1} de ${count}` : label,
29
+ };
@@ -0,0 +1,24 @@
1
+ export interface StoryLabels {
2
+ watch: string;
3
+ show: string;
4
+ carousel: string;
5
+ carouselRole: string;
6
+ previous: string;
7
+ next: string;
8
+ player: string;
9
+ expand: string;
10
+ collapse: string;
11
+ close: string;
12
+ play: string;
13
+ pause: string;
14
+ soundOn: string;
15
+ soundOff: string;
16
+ addToCart: string;
17
+ unavailable: string;
18
+ soldOut: string;
19
+ viewProduct: string;
20
+ /** The product button: "Tênis, de R$ 159,90 por R$ 129,90". */
21
+ product: (name: string, price?: string, listPrice?: string) => string;
22
+ /** Tells the cards apart: "Mostrar vídeo 2 de 4". */
23
+ position: (label: string, index: number, count: number) => string;
24
+ }
package/src/react.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * React JSX types for <vtex-ads-story>. Types only: the JS output is empty.
2
+ * React JSX types for <vtex-ads-story-carousel>. Types only: the JS output
3
+ * is empty.
3
4
  *
4
5
  * Opt in once per project, so non-React projects never need @types/react:
5
6
  *
@@ -8,18 +9,59 @@
8
9
  * or add "@vtex/ads-stories/react" to `compilerOptions.types` in tsconfig.
9
10
  */
10
11
  import type { DetailedHTMLProps, HTMLAttributes } from "react";
11
- import type { VtexAdsStoryElement } from "./story";
12
+ import type { Channel } from "@vtex/ads-core";
13
+ import type { TAG_NAME, VtexAdsStoryCarouselElement } from "./story";
12
14
 
13
- export type VtexAdsStoryProps = DetailedHTMLProps<
14
- HTMLAttributes<VtexAdsStoryElement>,
15
- VtexAdsStoryElement
16
- >;
15
+ /**
16
+ * The element's own attributes. The required ones match the README: without
17
+ * them, the element requests nothing and renders nothing.
18
+ */
19
+ export interface VtexAdsStoryCarouselAttributes {
20
+ /** The publisher the ads are requested for. */
21
+ "publisher-id": string;
22
+ /** The store's session, also used to deduplicate events. */
23
+ "session-id": string;
24
+ /** The Story placement configured for the publisher. */
25
+ placement: string;
26
+ "user-id"?: string;
27
+ "account-name"?: string;
28
+ /** `site` or `app`. */
29
+ channel?: Channel;
30
+ /** Time limit for the ad request, in milliseconds (default 2000). */
31
+ timeout?: number;
32
+ /** How many Stories to ask for: the carousel positions (default 8). */
33
+ quantity?: number;
34
+ /** Currency of the prices, ISO 4217 ("BRL"). Default BRL. */
35
+ currency?: string;
36
+ /** The add to cart button's text. Default in the element's language. */
37
+ "label-add-to-cart"?: string;
38
+ /** The view product button's text. Default in the element's language. */
39
+ "label-view-product"?: string;
40
+ /**
41
+ * "none": no product request. To set a strategy, assign the element's
42
+ * `hydration` property. Missing: Intelligent Search with `account-name`.
43
+ */
44
+ hydration?: "none";
45
+ /** Time limit for the product request, in milliseconds (default 5000). */
46
+ "hydration-timeout"?: number;
47
+ /**
48
+ * With more than one Story, the cards without the highlight also play
49
+ * their video, muted. Off by default.
50
+ */
51
+ "inactive-autoplay"?: boolean;
52
+ }
53
+
54
+ export type VtexAdsStoryCarouselProps = DetailedHTMLProps<
55
+ HTMLAttributes<VtexAdsStoryCarouselElement>,
56
+ VtexAdsStoryCarouselElement
57
+ > &
58
+ VtexAdsStoryCarouselAttributes;
17
59
 
18
60
  declare module "react" {
19
61
  // eslint-disable-next-line @typescript-eslint/no-namespace
20
62
  namespace JSX {
21
63
  interface IntrinsicElements {
22
- "vtex-ads-story": VtexAdsStoryProps;
64
+ [TAG_NAME]: VtexAdsStoryCarouselProps;
23
65
  }
24
66
  }
25
67
  }
@@ -1 +1,5 @@
1
- export { VtexAdsStoryElement, defineVtexAdsStories, TAG_NAME } from "./story";
1
+ export {
2
+ VtexAdsStoryCarouselElement,
3
+ defineVtexAdsStoryCarousel,
4
+ TAG_NAME,
5
+ } from "./story";