@sesamy/sesamy-components 2.22.4 → 2.24.1

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.
package/README.md CHANGED
@@ -7,6 +7,7 @@ This library provides typed [web components](https://developer.mozilla.org/en-US
7
7
  ## Table of Contents
8
8
 
9
9
  - [Installation](#installation)
10
+ - [Interaction tracking](#interaction-tracking)
10
11
  - [Components](#components)
11
12
  - [sesamy-login](#sesamy-login)
12
13
  - [sesamy-content-container](#sesamy-content-container)
@@ -65,6 +66,37 @@ import type {
65
66
  } from '@sesamy/sesamy-components';
66
67
  ```
67
68
 
69
+ ## Interaction tracking
70
+
71
+ In addition to the DOM events above, the components emit first-party interactions through `sesamy-js` (`window.sesamy.analytics.track`), so they arrive with the sesamy-js context (anonymous id, user id, vendor, page) attached. This is additive: the DOM events keep firing exactly as before, and page views stay `sesamy-js`'s responsibility — the components never emit them.
72
+
73
+ | Event | Emitted by | When | Properties |
74
+ | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
75
+ | `viewArticle` | `sesamy-content-container` | Once per element, as soon as the container has resolved an article and knows its access state | `itemSrc`, `publisherContentId`, `state` (`public`/`logged-in`/`unlocked`/`locked`) |
76
+ | `content_unlocked` | `sesamy-content-container` | Alongside the `sesamy:content-unlocked` DOM event | `itemSrc`, `publisherContentId`, `contentName` |
77
+ | `addToCart` | `sesamy-paywall` | When the user picks a product and continues to checkout | `itemSrc`, `publisherContentId`, `sku`, `purchaseOptionId`, `price`, `currency`, `paywallId` |
78
+
79
+ Event and property names match the ones `@sesamy/web-components` produced, so consumers of the interactions index keep working unchanged — only `context.library` differs (`@sesamy/sesamy-js` instead of `@sesamy/web-components`). Each event also repeats its own name in `properties.name`, as the legacy library did.
80
+
81
+ ### Opting out
82
+
83
+ Tracking is on by default. A page opts out with the same meta tag the legacy components honoured:
84
+
85
+ ```html
86
+ <meta name="sesamy:analytics" content="false" />
87
+ ```
88
+
89
+ or at runtime:
90
+
91
+ ```ts
92
+ import { disableInteractions, enableInteractions } from '@sesamy/sesamy-components';
93
+
94
+ disableInteractions(); // stop emitting; DOM events keep firing
95
+ enableInteractions(); // opt back in, overriding the meta tag
96
+ ```
97
+
98
+ `resetInteractions()` drops an explicit call and returns to the meta-tag default, and `interactionsEnabled()` reports the current state. Turning `sesamy-js` analytics off (`analytics.enabled: false` in its config) suppresses these events too, since they go through its pipeline.
99
+
68
100
  ## Components
69
101
 
70
102
  ### sesamy-login
@@ -229,6 +261,8 @@ All per-element events bubble and are composed (cross shadow roots).
229
261
  - `sesamy:content-unlocked`: Fired when gated content is decrypted and rendered into the element. `detail: { contentName: string }` — matches the element's `data-dca-content-name` attribute when present, otherwise falls back to the resolved `publisher-content-id`.
230
262
  - `sesamyUnlocked`: Legacy event, still dispatched alongside `sesamy:content-unlocked`. `detail: { publisherContentId, itemSrc }`.
231
263
 
264
+ The container also emits the `viewArticle` and `content_unlocked` interactions through sesamy-js — see [Interaction tracking](#interaction-tracking).
265
+
232
266
  ```js
233
267
  const el = document.querySelector('sesamy-content-container');
234
268
  el.addEventListener('sesamy:content-unlocked', (e) => {
@@ -290,6 +324,8 @@ Legacy bus events (emitted on `window` via `api.events.emit`, unchanged):
290
324
  - `sesamyPaywallProductSelected`: Emitted when a product/subscription is selected and the continue button is pressed, with `{ product, checkoutId, paywallId }` in `detail`.
291
325
  - `sesamyPaywallCheckoutRedirect`: Emitted before redirecting to checkout, with `{ checkout, paywallId, paymentMethod }` in `detail`.
292
326
 
327
+ The paywall also emits the `addToCart` interaction through sesamy-js when the user continues to checkout — see [Interaction tracking](#interaction-tracking).
328
+
293
329
  **Slots:**
294
330
 
295
331
  - `below-headline`: Content rendered below the paywall headline (e.g., additional info, custom elements)
@@ -539,36 +575,46 @@ This template does not provide any web components polyfills for older browsers s
539
575
 
540
576
  ### Props
541
577
 
542
- Any props accepted by your web component are automatically transformed to element attributes. Since camelCase or PascalCase does not work in HTML, you have to make sure to name your props in lowercase.
578
+ Props on a `.wc.svelte` component are exposed both as properties of the DOM element and, where possible, as attributes. The attribute name defaults to the prop name lowercased, so a camelCase prop like `buttonText` is only settable from markup as `buttontext` — name each prop exactly as the attribute should be written instead: lowercase for a single word, kebab-case for several. Rename the kebab-case keys to camelCase locals in the `$props()` destructure so the component body stays readable:
543
579
 
544
- ```html
545
- <script>
546
- export let myvalue = 'Default';
580
+ ```svelte
581
+ <!-- MyComponent.wc.svelte -->
582
+ <svelte:options customElement={{ tag: 'my-component' }} />
583
+
584
+ <script lang="ts">
585
+ let { myvalue = 'Default', 'item-src': itemSrc = '' } = $props();
547
586
  </script>
548
587
  ```
549
588
 
550
- ### Events
589
+ ```html
590
+ <my-component myvalue="Hello" item-src="https://example.com/article"></my-component>
591
+ ```
551
592
 
552
- The Svelte syntax event for listening to events like `on:myevent` doesn't work with events dispatched from a Svelte web component ([#3119](https://github.com/sveltejs/svelte/issues/3119)).
593
+ Values set through an attribute always arrive as strings. A prop that needs another type has to declare it in the `customElement.props` config (`{ type: 'Number' | 'Boolean' | 'Array' | 'Object' }`), or be assigned as a DOM property rather than an attribute.
553
594
 
554
- You need to use a workaround for that, by creating a `CustomEvent` and dispatching it.
595
+ See [`ContentContainer.wc.svelte`](packages/lib/src/ContentContainer.wc.svelte) for the same pattern with the prop types declared in `types.ts`.
596
+
597
+ ### Events
598
+
599
+ Between plain Svelte components you'd signal the parent with a callback prop or `createEventDispatcher`; neither travels well across the custom element boundary. `createEventDispatcher` events are never re-dispatched on the element, and a callback prop only reaches the component if the consumer assigns it as a DOM property (`el.onLogin = fn`) — it can't be wired up from plain HTML. So a `.wc.svelte` component talks to the host page by dispatching a real DOM `CustomEvent`, which consumers listen for with `addEventListener`. Inside a component compiled as a custom element the `$host()` rune returns that element — under Svelte 5 this is the supported API rather than a workaround.
555
600
 
556
601
  Here's an example:
557
602
 
558
- ```html
559
- // MyComponent.wc.svelte
560
- <svelte:options tag="my-component" />
561
- <script>
562
- import { get_current_component } from 'svelte/internal';
563
- const component = get_current_component();
603
+ ```svelte
604
+ <!-- MyComponent.wc.svelte -->
605
+ <svelte:options customElement={{ tag: 'my-component' }} />
564
606
 
607
+ <script>
565
608
  // example function for dispatching events
566
609
  const dispatchEvent = (name, detail) =>
567
- component.dispatchEvent(new CustomEvent(name, { detail }));
610
+ $host().dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
568
611
  </script>
569
- <button on:click={() => dispatchEvent('test', 'Hello!')}>Click to dispatch event</button>
612
+
613
+ <button onclick={() => dispatchEvent('test', 'Hello!')}>Click to dispatch event</button>
570
614
  ```
571
615
 
616
+ Both flags matter. Without `bubbles: true` the event only reaches a listener bound directly to the element, so event delegation on a container won't see it; without `composed: true` it can't escape an enclosing shadow root, which bites as soon as the element is nested inside another component's shadow DOM. The components in this repo get both from the typed `dispatchSesamyEvent` helper in `packages/lib/src/events.ts`, which also type-checks `detail` against `SesamyElementEventMap` — prefer it over a raw `CustomEvent`.
617
+
572
618
  ## Create a new component
573
619
 
574
620
  These are the files needed to create a new component: