@sesamy/sesamy-components 2.23.0 → 2.24.2
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 +61 -15
- package/dist/lib/sesamy-components.es.js +7605 -6110
- package/dist/lib/sesamy-components.umd.js +32 -31
- package/package.json +14 -7
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
|
-
|
|
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
|
-
```
|
|
545
|
-
|
|
546
|
-
|
|
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
|
-
|
|
589
|
+
```html
|
|
590
|
+
<my-component myvalue="Hello" item-src="https://example.com/article"></my-component>
|
|
591
|
+
```
|
|
551
592
|
|
|
552
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
559
|
-
|
|
560
|
-
<svelte:options tag
|
|
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
|
-
|
|
610
|
+
$host().dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
|
|
568
611
|
</script>
|
|
569
|
-
|
|
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:
|