@sesamy/sesamy-components 2.21.12 → 2.21.13

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
@@ -39,9 +39,35 @@ You can also use the components directly via CDN:
39
39
  <script type="module" src="https://unpkg.com/@sesamy/sesamy-components"></script>
40
40
  ```
41
41
 
42
+ ## Per-element events
43
+
44
+ Each top-level component dispatches per-element `CustomEvent`s (`bubbles: true, composed: true`) that publishers can subscribe to directly on the element — no need to poll or listen on `window`. TypeScript consumers get typed `detail` via `HTMLElementEventMap` augmentation exported from the package:
45
+
46
+ ```ts
47
+ import '@sesamy/sesamy-components'; // ambient augmentation
48
+
49
+ const el = document.querySelector('sesamy-login')!;
50
+ el.addEventListener('sesamy:login-success', (e) => {
51
+ // e.detail is typed as { userinfo: { sub: string; email?: string; … } }
52
+ console.log(e.detail.userinfo.sub);
53
+ });
54
+ ```
55
+
56
+ The full event map and detail interfaces are exported as named types:
57
+
58
+ ```ts
59
+ import type {
60
+ SesamyElementEventMap,
61
+ SesamyLoginSuccessDetail,
62
+ SesamyPaywallShownDetail,
63
+ SesamyAccessGrantedDetail,
64
+ SesamyContentUnlockedDetail
65
+ } from '@sesamy/sesamy-components';
66
+ ```
67
+
42
68
  ## Components
43
69
 
44
- # sesamy-login
70
+ ### sesamy-login
45
71
 
46
72
  A web component that provides authentication functionality, displaying a login button for unauthenticated users and an avatar with a dropdown menu for authenticated users.
47
73
 
@@ -57,7 +83,27 @@ A web component that provides authentication functionality, displaying a login b
57
83
 
58
84
  **Events:**
59
85
 
60
- - `login`: Dispatched when login action is triggered
86
+ All per-element events are `CustomEvent`s dispatched on the `<sesamy-login>` element with `bubbles: true, composed: true`, so they cross shadow DOM boundaries and can be caught via event delegation.
87
+
88
+ - `sesamy:login-success`: Fired when the authenticated state transitions from logged-out to logged-in. `detail: { userinfo: { sub: string; email?: string; name?: string; [key: string]: unknown } }`.
89
+ - `sesamy:login-error`: Fired when a login attempt fails (popup closed, token exchange rejected, network error). `detail: { error: { code: string; message: string; cause?: unknown } }`.
90
+ - `sesamy:logout`: Fired when the authenticated state transitions from logged-in to logged-out. `detail: {}`.
91
+ - `login`: Legacy event, dispatched when the login action is triggered.
92
+
93
+ ```js
94
+ const el = document.querySelector('sesamy-login');
95
+ el.addEventListener('sesamy:login-success', (e) => {
96
+ console.log('welcome', e.detail.userinfo.sub);
97
+ });
98
+ el.addEventListener('sesamy:login-error', (e) => {
99
+ console.warn('login failed', e.detail.error.code, e.detail.error.message);
100
+ });
101
+ el.addEventListener('sesamy:logout', () => {
102
+ console.log('user logged out');
103
+ });
104
+ ```
105
+
106
+ See also the window-level `Events` enum emitted by `@sesamy/sesamy-js` (`AUTHENTICATED`, `LOGOUT`, …) for cross-page coordination.
61
107
 
62
108
  **Basic Usage Example:**
63
109
 
@@ -92,11 +138,11 @@ A web component that provides authentication functionality, displaying a login b
92
138
  ></sesamy-login>
93
139
  ```
94
140
 
95
- ## Slots
141
+ #### Slots
96
142
 
97
143
  The `sesamy-login` component provides several slots for customizing its appearance and behavior:
98
144
 
99
- ### button-text
145
+ ##### button-text
100
146
 
101
147
  - **Purpose:** Replaces the default login button text.
102
148
  - **Behavior:** Content in this slot will be rendered as the main text of the login button, replacing the default (localized) "login" text.
@@ -107,7 +153,7 @@ The `sesamy-login` component provides several slots for customizing its appearan
107
153
  </sesamy-login>
108
154
  ```
109
155
 
110
- ### button-text-prefix
156
+ ##### button-text-prefix
111
157
 
112
158
  - **Purpose:** Inserts content before the login button text.
113
159
  - **Behavior:** Content in this slot will appear before the main button text, useful for adding icons or labels.
@@ -118,7 +164,7 @@ The `sesamy-login` component provides several slots for customizing its appearan
118
164
  </sesamy-login>
119
165
  ```
120
166
 
121
- ### button-text-suffix
167
+ ##### button-text-suffix
122
168
 
123
169
  - **Purpose:** Inserts content after the login button text.
124
170
  - **Behavior:** Content in this slot will appear after the main button text, useful for adding icons or additional info.
@@ -129,7 +175,7 @@ The `sesamy-login` component provides several slots for customizing its appearan
129
175
  </sesamy-login>
130
176
  ```
131
177
 
132
- ### avatar
178
+ ##### avatar
133
179
 
134
180
  - **Purpose:** Replaces the default avatar shown when logged in.
135
181
  - **Behavior:** Content in this slot will be rendered instead of the default avatar image/button when the user is authenticated.
@@ -145,7 +191,7 @@ The `sesamy-login` component provides several slots for customizing its appearan
145
191
  </sesamy-login>
146
192
  ```
147
193
 
148
- ### popup-menu
194
+ ##### popup-menu
149
195
 
150
196
  - **Purpose:** Replaces the default popup menu shown when clicking the avatar.
151
197
  - **Behavior:** Content in this slot will be rendered instead of the default menu (email/account/logout) when the user is authenticated and opens the menu.
@@ -178,7 +224,17 @@ A web component that controls access to content based on user authentication and
178
224
 
179
225
  **Events:**
180
226
 
181
- - `sesamyUnlocked`: Dispatched when content is unlocked (with `item-src` and `publisher-content-id` in detail)
227
+ All per-element events bubble and are composed (cross shadow roots).
228
+
229
+ - `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
+ - `sesamyUnlocked`: Legacy event, still dispatched alongside `sesamy:content-unlocked`. `detail: { publisherContentId, itemSrc }`.
231
+
232
+ ```js
233
+ const el = document.querySelector('sesamy-content-container');
234
+ el.addEventListener('sesamy:content-unlocked', (e) => {
235
+ analytics.track('content_unlocked', { name: e.detail.contentName });
236
+ });
237
+ ```
182
238
 
183
239
  **Basic Usage Example:**
184
240
 
@@ -196,7 +252,7 @@ A web component that controls access to content based on user authentication and
196
252
  </sesamy-content-container>
197
253
  ```
198
254
 
199
- # sesamy-paywall
255
+ ### sesamy-paywall
200
256
 
201
257
  A web component that displays a paywall for content, loading paywall settings from a remote URL and supporting different templates (Article, Boxes, Login).
202
258
 
@@ -212,10 +268,29 @@ A web component that displays a paywall for content, loading paywall settings fr
212
268
 
213
269
  **Events:**
214
270
 
271
+ Per-element events dispatched directly on the `<sesamy-paywall>` element (bubble, composed):
272
+
273
+ - `sesamy:paywall-shown`: Fired once per visible mount when the paywall becomes visible to the user. `detail: { reason: 'unauthenticated' | 'no-entitlement' | 'consent-required' | string }`.
274
+ - `sesamy:paywall-dismissed`: Fired when the user dismisses the paywall without purchasing (element is removed while it was shown and access was never granted). `detail: {}`.
275
+ - `sesamy:access-granted`: Fired when the paywall confirms the user has access and hides itself. `detail: { scopes: string[] }` — the entitlement scopes / passes that granted access.
276
+
277
+ ```js
278
+ const el = document.querySelector('sesamy-paywall');
279
+ el.addEventListener('sesamy:paywall-shown', (e) => {
280
+ console.log('paywall visible; reason:', e.detail.reason);
281
+ });
282
+ el.addEventListener('sesamy:access-granted', (e) => {
283
+ console.log('granted scopes:', e.detail.scopes);
284
+ });
285
+ ```
286
+
287
+ Legacy bus events (emitted on `window` via `api.events.emit`, unchanged):
288
+
215
289
  - `sesamyPaywallAccessChecked`: Emitted after access check, with `{ hasAccess, paywallId, articleUrl, passes }` in `detail`.
216
290
  - `sesamyPaywallProductSelected`: Emitted when a product/subscription is selected and the continue button is pressed, with `{ product, checkoutId, paywallId }` in `detail`.
217
291
  - `sesamyPaywallCheckoutRedirect`: Emitted before redirecting to checkout, with `{ checkout, paywallId, paymentMethod }` in `detail`.
218
- **Slots:**
292
+
293
+ **Slots:**
219
294
 
220
295
  - `below-headline`: Content rendered below the paywall headline (e.g., additional info, custom elements)
221
296
  - `features`: Content rendered in the features section of the paywall (e.g., feature list, benefits)
@@ -239,11 +314,11 @@ A web component that displays a paywall for content, loading paywall settings fr
239
314
  </sesamy-paywall>
240
315
  ```
241
316
 
242
- ## Slots
317
+ #### Slots
243
318
 
244
319
  The `sesamy-paywall` component provides two main slots for customization:
245
320
 
246
- ### below-headline
321
+ ##### below-headline
247
322
 
248
323
  - **Purpose:** Inserts custom content directly below the paywall headline.
249
324
  - **Behavior:** The content you provide in this slot will be rendered in addition to the default paywall content, immediately below the headline. Use this for adding extra information, banners, or custom elements.
@@ -254,7 +329,7 @@ The `sesamy-paywall` component provides two main slots for customization:
254
329
  </sesamy-paywall>
255
330
  ```
256
331
 
257
- ### features
332
+ ##### features
258
333
 
259
334
  - **Purpose:** Replaces the default features section of the paywall.
260
335
  - **Behavior:** When you provide content in the `features` slot, it will completely replace the built-in features list or section. Use this slot to fully customize the list of benefits, features, or selling points shown to the user.
@@ -275,7 +350,7 @@ The `sesamy-paywall` component provides two main slots for customization:
275
350
 
276
351
  - The `below-headline` slot adds to the paywall, while the `features` slot replaces the default features section entirely.
277
352
 
278
- # sesamy-visibility
353
+ ### sesamy-visibility
279
354
 
280
355
  A simple web component that conditionally renders content based on user authentication status.
281
356
 
@@ -288,7 +363,7 @@ A simple web component that conditionally renders content based on user authenti
288
363
  </sesamy-visibility>
289
364
  ```
290
365
 
291
- # sesamy-avatar
366
+ ### sesamy-avatar
292
367
 
293
368
  A web component that displays a user avatar image with configurable size and loading state.
294
369
 
@@ -309,7 +384,7 @@ A web component that displays a user avatar image with configurable size and loa
309
384
  <sesamy-avatar src="https://example.com/user.jpg" size="lg" loading></sesamy-avatar>
310
385
  ```
311
386
 
312
- # sesamy-button
387
+ ### sesamy-button
313
388
 
314
389
  A customizable button web component with multiple variants and sizes.
315
390
 
@@ -336,7 +411,7 @@ A customizable button web component with multiple variants and sizes.
336
411
  <sesamy-button href="/checkout" variant="primary">Go to Checkout</sesamy-button>
337
412
  ```
338
413
 
339
- # sesamy-login-menu-item
414
+ ### sesamy-login-menu-item
340
415
 
341
416
  A web component for individual menu items in the login dropdown menu. Can be used to customize the logged-in user menu.
342
417
 
@@ -491,7 +566,7 @@ Here's an example:
491
566
  const dispatchEvent = (name, detail) =>
492
567
  component.dispatchEvent(new CustomEvent(name, { detail }));
493
568
  </script>
494
- <button onclick="{()" ="">dispatchEvent("test", "Hello!")}> Click to dispatch event</button>
569
+ <button on:click={() => dispatchEvent('test', 'Hello!')}>Click to dispatch event</button>
495
570
  ```
496
571
 
497
572
  ## Create a new component