@sentientui/react 0.36.0 → 0.37.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.
- package/README.md +110 -63
- package/dist/index.d.cts +36 -4
- package/dist/index.d.ts +36 -4
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/dist/next/adaptive-root.d.ts +6 -0
- package/dist/next/adaptive-root.js +2 -2
- package/dist/next/adaptive-root.js.map +1 -1
- package/dist/testing/react.js +1 -1
- package/dist/testing/react.js.map +1 -1
- package/dist/testing/react.mjs +1 -1
- package/dist/testing/react.mjs.map +1 -1
- package/llms.txt +2 -2
- package/package.json +10 -7
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
React SDK for [SentientUI](https://sentient-ui.com) — the adaptive ladder. Declare bounded
|
|
4
4
|
variations (styles, content, arrangement order); a persona-keyed optimizer on the hosted API
|
|
5
|
-
learns which one converts best for each visitor type
|
|
5
|
+
learns which one converts best for each visitor type, and measures the lift against a held-out control group.
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
@@ -67,6 +67,11 @@ attributes: only that inline script (which `AdaptiveRoot` includes for you) writ
|
|
|
67
67
|
the attributes itself, so the demo works either way — don't let that mask a missing script when
|
|
68
68
|
you add a real key.)
|
|
69
69
|
|
|
70
|
+
Give `<SentientPersonaScript>` the same consent gate as the provider
|
|
71
|
+
(`<SentientPersonaScript apiKey="pk_…" consentFrom="cookiebot" />`). With `consent={false}`, or a
|
|
72
|
+
`consentFrom` and no `consent={true}`, it renders nothing, because its fallback reads the decision
|
|
73
|
+
stored on the visitor's device, which has to wait for consent. `AdaptiveRoot` does this for you.
|
|
74
|
+
|
|
70
75
|
## The adaptive ladder
|
|
71
76
|
|
|
72
77
|
### Rung 0 — Observe
|
|
@@ -228,9 +233,27 @@ Imported from `@sentientui/react/next`.
|
|
|
228
233
|
| `persona` | `string` *(optional)* | Declared persona — the role your app already knows for this visitor (e.g. from your auth context). Must be a key in the project's persona vocabulary (dashboard → Settings → Personas); unrecognized values are ignored server-side. Served at full confidence, overriding the inferred persona; forwarded through both SSR paths. Stable for the session — remount to apply a new value. Never a user id or email. |
|
|
229
234
|
| `consent` | `boolean` *(default `true`)* | Set `false` to skip SDK init (no cookies, no events). Flip to `true` after the visitor accepts. |
|
|
230
235
|
| `respectDoNotTrack` | `boolean` *(default `true`)* | Honor the browser's Do Not Track signal. When on and DNT is enabled, the SDK sets no cookies and sends no tracking data (overriding `consent: true`), and `grantConsent()` won't re-enable it. Set `false` to make your own consent gate authoritative. |
|
|
236
|
+
| `consentFrom` | preset or `{ cookie, value, event }` *(optional)* | Your consent platform — see [Consent management](#consent-management-gdpr). Cookie-based sources are also read on the server, so a consented visitor gets personalized HTML and a non-consented one gets none. |
|
|
231
237
|
| `timeoutMs` | `number` *(default `1000`)* | Server-side fetch timeout before falling back to the first variant. Typical decide is well under 150 ms; the full budget is only reached on a cold start or an API distant from your SSR host. |
|
|
238
|
+
| `nonce` | `string` *(optional)* | CSP nonce for the inline pre-paint script and the `<style>` the client injects. |
|
|
232
239
|
| `debug` | `boolean` | Log assignment and event activity to the console. |
|
|
233
240
|
|
|
241
|
+
#### What `<AdaptiveRoot>` costs your rendering
|
|
242
|
+
|
|
243
|
+
- **Every route under it renders dynamically.** It reads `headers()` and `cookies()` to decide per visitor, so
|
|
244
|
+
Next.js can't statically generate or ISR-cache those routes.
|
|
245
|
+
- **It adds one API round trip to time-to-first-byte**, usually well under 150 ms and capped by `timeoutMs`
|
|
246
|
+
(default 1000 ms). On timeout the page renders the originals and decides in the browser instead.
|
|
247
|
+
- **It skips the round trip entirely** for visitors it must not track (DNT/GPC, consent refused or not yet given).
|
|
248
|
+
|
|
249
|
+
Want static pages? Put `<AdaptiveProvider>` in a client component instead, only around the routes that adapt.
|
|
250
|
+
Decisions then happen in the browser after hydration: the server HTML shows the originals, a returning
|
|
251
|
+
visitor's last decision is restored from the SDK's local snapshot as soon as the client starts (no network
|
|
252
|
+
wait), and a first-time visitor's arrives after one round trip.
|
|
253
|
+
|
|
254
|
+
`@sentientui/react/next` is ESM-only (the App Router always loads it as ESM). The package root and
|
|
255
|
+
`/server` ship both ESM and CommonJS.
|
|
256
|
+
|
|
234
257
|
### `<AdaptiveProvider>` (any React app)
|
|
235
258
|
|
|
236
259
|
Accepts the same `apiKey`, `persona`, `consent`, `debug` props as `<AdaptiveRoot>`, plus `onAssignment` (not available on `<AdaptiveRoot>` — function props can't cross the RSC boundary) and:
|
|
@@ -255,7 +278,8 @@ never both. `AdaptiveProps` is the union of the two exported prop types below.
|
|
|
255
278
|
| `children` | `ReactNode` | The original. Renders for holdout/control traffic, unknown visitor types, visitor types with no version, and every error path. |
|
|
256
279
|
| `goal` | `string \| GoalConfig` *(optional)* | Conversion goal credited to this region. |
|
|
257
280
|
| `onFormSubmit` | `(values: Record<string, string>) => void` *(optional)* | Receives the values when a generated form version submits. Form versions are only offered when this is present; values never reach SentientUI. |
|
|
258
|
-
| `
|
|
281
|
+
| `as` | `'div' \| 'section' \| 'li' \| 'span' \| …` *(optional, default `'div'`)* | Wrapper element — e.g. `'li'` inside a list. Always a real element, never `display: contents`: it is what exposure and goals observe. |
|
|
282
|
+
| `className` | `string` *(optional)* | Class for the wrapper element. |
|
|
259
283
|
| `reportBaselineText` | `boolean` *(default `true`)* | At first registration, send this region's rendered text (capped at 400 chars) so generated versions are grounded in what they replace. Set `false` for a region wrapping personalized or account content. |
|
|
260
284
|
|
|
261
285
|
**Code variants** — `AdaptiveVariantsProps`:
|
|
@@ -269,8 +293,24 @@ never both. `AdaptiveProps` is the union of the two exported prop types below.
|
|
|
269
293
|
| `microSignalGoals` | `MicroSignalGoals` *(optional)* | When a passive micro-signal fires on this component, also record a named goal: micro-signal type → goal name (or `{ name, weight?, stepIndex? }`), e.g. `{ rage_click: 'confused_by_hero' }`. |
|
|
270
294
|
| `agentDataByVariant` | `Record<string, unknown>` *(optional)* | Structured data keyed by variant ID that AI agents can consume via `GET /v1/agent/layout`. Only the assigned variant's entry is sent to the server. Preferred over `agentData`. |
|
|
271
295
|
| `agentData` | `unknown` *(optional, deprecated)* | Deprecated in favour of `agentDataByVariant`. Single value stored once regardless of which variant is shown; kept for backward compatibility. |
|
|
296
|
+
| `as`, `className` | *(optional)* | Wrapper element and its class, as for generated versions. |
|
|
272
297
|
| `clientOnly` | `boolean` | Render nothing on the server; resolve on the client only. Use for cookie-dependent components. Without it, a component with no preloaded assignment server-renders its first variant. (This replaces the deprecated provider-level `ssrFallback="none"`, which is still accepted.) |
|
|
273
298
|
|
|
299
|
+
#### Which goal API?
|
|
300
|
+
|
|
301
|
+
One canonical path per situation — the others are for the cases these can't reach:
|
|
302
|
+
|
|
303
|
+
| You want to record… | Use | Credits |
|
|
304
|
+
|---|---|---|
|
|
305
|
+
| a click, submit or scroll inside an adaptive region | the `goal` prop on `<Adaptive>` | the version that region showed |
|
|
306
|
+
| a visitor reaching a page or route (pricing, checkout) | `usePageGoal(name, { componentId? })` | that component's version, or the session |
|
|
307
|
+
| an event you fire yourself, tied to a region (a phone call, a custom widget) | `useAdaptiveGoal(componentId)` | the version that region showed |
|
|
308
|
+
| a conversion outside React (server, another framework) | `client.goal(name, { value, externalId })` from `@sentientui/core` | the session |
|
|
309
|
+
|
|
310
|
+
`useAssignment` records nothing (use `useAdaptive`), and the positional
|
|
311
|
+
`client.goal(name, metadata, weight, stepIndex)` form is deprecated in favour of
|
|
312
|
+
`client.goal(name, options)`; both leave in 1.0.
|
|
313
|
+
|
|
274
314
|
#### Goal types
|
|
275
315
|
|
|
276
316
|
**A string is the goal's NAME; an object config has none.** `goal="signup_click"` reports under
|
|
@@ -556,6 +596,8 @@ DOM graph scanning and behavioral engagement capture are **on by default** — n
|
|
|
556
596
|
|
|
557
597
|
Both modules are loaded on demand after init, so the base bundle stays lean, and neither ever runs for a Do-Not-Track, Global Privacy Control, or consent-gated visitor (see Consent below).
|
|
558
598
|
|
|
599
|
+
What they cost, so you can decide: about 21 KB gzip on top of the ~16 KB core client, fetched after hydration (never on the critical path). One `MutationObserver` watches the page for sections added later, and it batches a burst of DOM changes into a single scan 200 ms after the burst starts, so a chat or a live list doesn't make it do work on every frame. Turn graph scanning off and the dashboard's page-structure view goes empty. Turn engagement off and audiences stop learning from on-page behaviour.
|
|
600
|
+
|
|
559
601
|
Opt out per feature:
|
|
560
602
|
|
|
561
603
|
```tsx
|
|
@@ -568,85 +610,90 @@ Direct `@sentientui/core` users enable graph scanning by importing `init` from `
|
|
|
568
610
|
|
|
569
611
|
## Consent management (GDPR)
|
|
570
612
|
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
consent={hasConsent}
|
|
577
|
-
preConsentBehavior="statistical_winner"
|
|
578
|
-
>
|
|
579
|
-
{children}
|
|
580
|
-
</AdaptiveProvider>
|
|
581
|
-
```
|
|
582
|
-
|
|
583
|
-
Set `hasConsent` to `false` until the user accepts your cookie banner, then flip it to `true`. The provider re-initialises automatically and begins full tracking.
|
|
584
|
-
|
|
585
|
-
### Without React
|
|
613
|
+
Tracking starts on first paint unless you gate it — opt-in consent is something you wire up,
|
|
614
|
+
not the default (in development the provider warns once when neither `consent` nor
|
|
615
|
+
`consentFrom` is set). While the SDK is gated no cookie is written and nothing about the
|
|
616
|
+
visitor is sent. The one exception is `preConsentBehavior="statistical_winner"`, which asks
|
|
617
|
+
`GET /v1/winner` for the best version, a read-only request that carries no identifier.
|
|
586
618
|
|
|
587
|
-
|
|
588
|
-
|
|
619
|
+
A refusal forgets the visitor: the cookie, the assignment cache and the decision snapshot.
|
|
620
|
+
That means `consent` flipping to `false`, or the platform recording a "no". A platform that is
|
|
621
|
+
still loading, or reopened by a visitor who already said yes, only pauses tracking. Once the
|
|
622
|
+
platform has answered in the page load, a return to "no answer" (a banner reset that deletes its
|
|
623
|
+
cookie) also pauses: `AdaptiveRoot`'s server-side read applies only until the browser answers.
|
|
589
624
|
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
});
|
|
625
|
+
Conversions fired before consent is known: with `preConsentBehavior` they are held in memory
|
|
626
|
+
and sent, in order and ahead of later goals, if the visitor accepts on the same page (dropped on a refusal). Without it there is no
|
|
627
|
+
client yet, so `useSentient()` returns `null` and a conversion fired then is not recorded. Use
|
|
628
|
+
`usePageGoal`, which waits, or fire once `useSentient()` returns a client.
|
|
595
629
|
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
```
|
|
630
|
+
Every key the SDK stores is listed in
|
|
631
|
+
[SDK_COOKIE_DISCLOSURE.md](https://github.com/SentientUI/sdk/blob/main/SDK_COOKIE_DISCLOSURE.md).
|
|
599
632
|
|
|
600
|
-
###
|
|
633
|
+
### Follow your consent platform (recommended)
|
|
601
634
|
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
`consentFrom` at the CMP instead. The source is re-read every time the event fires, so a later
|
|
606
|
-
withdrawal gates the SDK again too:
|
|
635
|
+
Point `consentFrom` at your CMP. The provider reads the platform's own API, events and cookie,
|
|
636
|
+
starts the moment it grants, and gates and forgets again on withdrawal — no reload, no callback
|
|
637
|
+
wiring:
|
|
607
638
|
|
|
608
639
|
```tsx
|
|
609
|
-
|
|
610
|
-
<AdaptiveProvider
|
|
611
|
-
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
|
|
612
|
-
consentFrom={{
|
|
613
|
-
check: () => window.OnetrustActiveGroups?.includes('C0002') === true,
|
|
614
|
-
event: 'OneTrustGroupsUpdated',
|
|
615
|
-
}}
|
|
616
|
-
>
|
|
617
|
-
{children}
|
|
618
|
-
</AdaptiveProvider>
|
|
619
|
-
|
|
620
|
-
// Cookiebot — re-read on accept AND decline, so withdrawal is honoured
|
|
621
|
-
<AdaptiveProvider
|
|
622
|
-
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
|
|
623
|
-
consentFrom={{
|
|
624
|
-
check: () => window.Cookiebot?.consent?.statistics === true,
|
|
625
|
-
event: 'CookiebotOnConsentReady',
|
|
626
|
-
}}
|
|
627
|
-
>
|
|
640
|
+
<AdaptiveProvider apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!} consentFrom="onetrust">
|
|
628
641
|
{children}
|
|
629
642
|
</AdaptiveProvider>
|
|
630
643
|
```
|
|
631
644
|
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
645
|
+
| Preset | Reads | Default category |
|
|
646
|
+
|---|---|---|
|
|
647
|
+
| `'cookiebot'` | `Cookiebot.consent`, `CookieConsent` cookie | `statistics` — `{ cmp: 'cookiebot', category: 'marketing' }` to change |
|
|
648
|
+
| `'onetrust'` | `OnetrustActiveGroups` (exact group match), `OptanonConsent` cookie | `C0002` — `{ cmp: 'onetrust', group: 'C0004' }` |
|
|
649
|
+
| `'cookieyes'` | `getCkyConsent()`, `cookieyes-consent` cookie | `analytics` |
|
|
650
|
+
| `'tcf'` | IAB TCF v2.2 `__tcfapi`, `euconsent-v2` cookie | purposes 1, 5, 6, 8 (8 may rest on legitimate interest); `{ cmp: 'tcf', vendorId }` also requires vendor consent |
|
|
651
|
+
| `'google-consent-mode'` | the latest `consent default/update` in `dataLayer` | `analytics_storage`; pass `region: 'ES'` (e.g. from your CDN's country header) to resolve region-scoped defaults — without it a region-scoped denial reads as denied |
|
|
652
|
+
| `'shopify'` | Shopify Customer Privacy API | `analytics` |
|
|
653
|
+
|
|
654
|
+
Your own banner works too: `consentFrom={{ cookie: 'analytics_consent', value: 'granted', event: 'consent-decided' }}`,
|
|
655
|
+
or any JS API: `consentFrom={{ check: () => window.myCmp?.analytics === true, event: 'mycmp:changed' }}`.
|
|
656
|
+
A `check` returning false only pauses tracking; add `refused: () => window.myCmp?.answered === true`
|
|
657
|
+
so a refusal also deletes the visitor's data.
|
|
658
|
+
Hand-rolled checks are where CMP bugs live (`OnetrustActiveGroups.includes('C0002')` is also
|
|
659
|
+
true for `C00021`), so prefer a preset.
|
|
660
|
+
|
|
661
|
+
To show the best-performing version while the banner is pending, instead of the first one, add
|
|
662
|
+
`preConsentBehavior="statistical_winner"` — it calls only `GET /v1/winner`, a read-only endpoint
|
|
663
|
+
that stores nothing about the visitor.
|
|
664
|
+
|
|
665
|
+
### `<AdaptiveRoot>` (Next.js)
|
|
666
|
+
|
|
667
|
+
`<AdaptiveRoot>` is a Server Component: it takes every preset and the cookie form (a `check`
|
|
668
|
+
function cannot cross the server→client boundary). For the cookie-based presets
|
|
669
|
+
(`cookiebot`, `onetrust`, `cookieyes`, `tcf`) and the cookie form it also reads the decision on
|
|
670
|
+
the server, so an already-consented visitor gets personalized server HTML:
|
|
635
671
|
|
|
636
672
|
```tsx
|
|
637
|
-
<AdaptiveRoot
|
|
638
|
-
apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!}
|
|
639
|
-
consentFrom={{ cookie: 'analytics_consent', value: 'granted', event: 'consent-decided' }}
|
|
640
|
-
>
|
|
673
|
+
<AdaptiveRoot apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!} consentFrom="cookiebot">
|
|
641
674
|
{children}
|
|
642
675
|
</AdaptiveRoot>
|
|
643
676
|
```
|
|
644
677
|
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
678
|
+
### Your own flag
|
|
679
|
+
|
|
680
|
+
```tsx
|
|
681
|
+
<AdaptiveProvider apiKey={process.env.NEXT_PUBLIC_SENTIENT_API_KEY!} consent={hasConsent}>
|
|
682
|
+
```
|
|
683
|
+
|
|
684
|
+
Flip `hasConsent` to `true` on accept and back to `false` on withdrawal. Don't wire a CMP
|
|
685
|
+
callback to `grantConsent()` in React: with `consent={false}` and no `preConsentBehavior` the
|
|
686
|
+
provider has no client to upgrade.
|
|
648
687
|
|
|
649
|
-
|
|
688
|
+
### Without React
|
|
689
|
+
|
|
690
|
+
```ts
|
|
691
|
+
import { init, grantConsent } from '@sentientui/core';
|
|
692
|
+
|
|
693
|
+
const client = init({ apiKey: 'pk_...', consent: false });
|
|
694
|
+
grantConsent(); // on accept: upgrades the client in place
|
|
695
|
+
client.destroy(); // on withdrawal: forgets the visitor
|
|
696
|
+
```
|
|
650
697
|
|
|
651
698
|
## Docs
|
|
652
699
|
|
package/dist/index.d.cts
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { ReactNode, JSX } from 'react';
|
|
2
2
|
import { SentientConfig, ConsentSource, SlotResult, SlotConfigEntry, SitePalette, StyleVocabulary, SentientClient, MicroSignalType, ComponentGoalOptions, BlockNode, ComposeArm } from '@sentientui/core';
|
|
3
|
-
export { SitePalette, deriveSessionSegment as detectSegment, grantConsent } from '@sentientui/core';
|
|
3
|
+
export { ConsentPreset, ConsentSource, ConsentWatcher, SitePalette, deriveSessionSegment as detectSegment, grantConsent } from '@sentientui/core';
|
|
4
4
|
import { SemanticType } from '@sentientui/core/engagement';
|
|
5
5
|
export { SemanticType } from '@sentientui/core/engagement';
|
|
6
6
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
7
|
+
export { consentWatcher } from '@sentientui/core/consent';
|
|
7
8
|
|
|
8
9
|
/** How to render adaptive slots during SSR when assignments are not preloaded. */
|
|
9
10
|
type SsrFallback = 'first' | 'none';
|
|
@@ -197,6 +198,12 @@ type AdaptiveProviderProps = {
|
|
|
197
198
|
* Never runs for a DNT/GPC or consent-gated visitor (no client → no capture).
|
|
198
199
|
*/
|
|
199
200
|
engagement?: boolean;
|
|
201
|
+
/**
|
|
202
|
+
* CSP nonce for the <style> the SDK injects (the adaptation reveal), so a
|
|
203
|
+
* nonce-based CSP needs no `style-src 'unsafe-inline'`. `AdaptiveRoot`
|
|
204
|
+
* forwards its own `nonce`. Defaults to the nonce of a script on the page.
|
|
205
|
+
*/
|
|
206
|
+
nonce?: string;
|
|
200
207
|
children: ReactNode;
|
|
201
208
|
};
|
|
202
209
|
/**
|
|
@@ -211,6 +218,9 @@ declare function AdaptiveProvider(props: AdaptiveProviderProps): JSX.Element;
|
|
|
211
218
|
declare function useSentient(): SentientClient | null;
|
|
212
219
|
/** Internal: SSR-preloaded assignments for hydration-safe first render. */
|
|
213
220
|
declare function useInitialAssignments(): Record<string, string>;
|
|
221
|
+
/** The `device:source` segment this provider decides and caches under —
|
|
222
|
+
* the SSR value when one was passed, else derived once per mount. */
|
|
223
|
+
declare function useSessionSegment(): string;
|
|
214
224
|
/**
|
|
215
225
|
* Returns the persona-specific section order from SSR, or null when no
|
|
216
226
|
* sections were declared on AdaptiveRoot or reliability is below threshold.
|
|
@@ -221,6 +231,14 @@ declare function useLayoutOrder(): string[] | null;
|
|
|
221
231
|
/** Internal: configured API base URL (devtools fetches /v1/explain against this, never a relative URL). */
|
|
222
232
|
declare function useAdaptiveApiBaseUrl(): string;
|
|
223
233
|
|
|
234
|
+
/**
|
|
235
|
+
* The element `<Adaptive>` renders around its content (audit S17: it was
|
|
236
|
+
* always a `<div>`, which is invalid inside a `<ul>`, a `<p>` or a table row
|
|
237
|
+
* and broke `display: grid` children). Intrinsic tags only: the wrapper is
|
|
238
|
+
* what exposure, goals and micro-signals observe, so it must be a real box —
|
|
239
|
+
* `display: contents` would give IntersectionObserver nothing to measure.
|
|
240
|
+
*/
|
|
241
|
+
type AdaptiveElement = 'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav' | 'span' | 'li' | 'figure' | 'form' | 'label' | 'td' | 'th';
|
|
224
242
|
type ScrollDepthGoal = {
|
|
225
243
|
type: 'scroll_depth';
|
|
226
244
|
threshold: number;
|
|
@@ -273,13 +291,15 @@ type AdaptiveSlotProps = {
|
|
|
273
291
|
* shape as AdaptiveGroup's. Form arms fire their own submitGoal regardless. */
|
|
274
292
|
goal?: string | GoalConfig;
|
|
275
293
|
className?: string;
|
|
294
|
+
/** Wrapper element. @default 'div' */
|
|
295
|
+
as?: AdaptiveElement;
|
|
276
296
|
/** On first registration the SDK sends the region's rendered text (capped at
|
|
277
297
|
* 400 chars) so dashboard-generated versions are grounded in what they
|
|
278
298
|
* replace. Set false for a slot wrapping personalized or account content —
|
|
279
299
|
* the text of THIS region is all that is ever read, never the page. */
|
|
280
300
|
reportBaselineText?: boolean;
|
|
281
301
|
};
|
|
282
|
-
declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
|
|
302
|
+
declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, as: Tag, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
|
|
283
303
|
|
|
284
304
|
/** `<Adaptive>` with variants written in code — each key an arm, first key the control. */
|
|
285
305
|
type AdaptiveVariantsProps = {
|
|
@@ -305,6 +325,10 @@ type AdaptiveVariantsProps = {
|
|
|
305
325
|
* Use for inferred goals surfaced in the dashboard (e.g. rage_click → 'confused_by_hero').
|
|
306
326
|
*/
|
|
307
327
|
microSignalGoals?: MicroSignalGoals;
|
|
328
|
+
/** Wrapper element. @default 'div' */
|
|
329
|
+
as?: AdaptiveElement;
|
|
330
|
+
/** Class for the wrapper element. */
|
|
331
|
+
className?: string;
|
|
308
332
|
/**
|
|
309
333
|
* When true, renders nothing during SSR and before client hydration.
|
|
310
334
|
* Use when you cannot pass `initialAssignments` and prefer a blank slot over
|
|
@@ -510,6 +534,14 @@ type SentientPersonaScriptProps = {
|
|
|
510
534
|
persona: string;
|
|
511
535
|
confidence: number;
|
|
512
536
|
} | null;
|
|
537
|
+
/**
|
|
538
|
+
* The same consent gate you give the provider. With `consent={false}`, or a
|
|
539
|
+
* `consentFrom` source and no `consent={true}`, nothing is rendered: the
|
|
540
|
+
* fallback reads the stored decision from the visitor's device, and that
|
|
541
|
+
* must wait for consent (grader F3). `AdaptiveRoot` handles this for you.
|
|
542
|
+
*/
|
|
543
|
+
consent?: boolean;
|
|
544
|
+
consentFrom?: unknown;
|
|
513
545
|
};
|
|
514
546
|
/**
|
|
515
547
|
* Single writer of the Rung-1a `<html>` attributes
|
|
@@ -523,7 +555,7 @@ type SentientPersonaScriptProps = {
|
|
|
523
555
|
* (the same pattern next-themes uses). The client SDK adopts the attributes
|
|
524
556
|
* as truth and never rewrites them mid-session.
|
|
525
557
|
*/
|
|
526
|
-
declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element;
|
|
558
|
+
declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element | null;
|
|
527
559
|
|
|
528
560
|
type UseAdaptiveTokensOptions = {
|
|
529
561
|
goal?: string | GoalConfig;
|
|
@@ -729,4 +761,4 @@ declare function renderBlocks(node: BlockNode, opts: RenderBlocksOptions): JSX.E
|
|
|
729
761
|
*/
|
|
730
762
|
declare function renderCompose(compose: ComposeArm, opts: RenderBlocksOptions): JSX.Element | null;
|
|
731
763
|
|
|
732
|
-
export { Adaptive, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient };
|
|
764
|
+
export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { ReactNode, JSX } from 'react';
|
|
2
2
|
import { SentientConfig, ConsentSource, SlotResult, SlotConfigEntry, SitePalette, StyleVocabulary, SentientClient, MicroSignalType, ComponentGoalOptions, BlockNode, ComposeArm } from '@sentientui/core';
|
|
3
|
-
export { SitePalette, deriveSessionSegment as detectSegment, grantConsent } from '@sentientui/core';
|
|
3
|
+
export { ConsentPreset, ConsentSource, ConsentWatcher, SitePalette, deriveSessionSegment as detectSegment, grantConsent } from '@sentientui/core';
|
|
4
4
|
import { SemanticType } from '@sentientui/core/engagement';
|
|
5
5
|
export { SemanticType } from '@sentientui/core/engagement';
|
|
6
6
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
7
|
+
export { consentWatcher } from '@sentientui/core/consent';
|
|
7
8
|
|
|
8
9
|
/** How to render adaptive slots during SSR when assignments are not preloaded. */
|
|
9
10
|
type SsrFallback = 'first' | 'none';
|
|
@@ -197,6 +198,12 @@ type AdaptiveProviderProps = {
|
|
|
197
198
|
* Never runs for a DNT/GPC or consent-gated visitor (no client → no capture).
|
|
198
199
|
*/
|
|
199
200
|
engagement?: boolean;
|
|
201
|
+
/**
|
|
202
|
+
* CSP nonce for the <style> the SDK injects (the adaptation reveal), so a
|
|
203
|
+
* nonce-based CSP needs no `style-src 'unsafe-inline'`. `AdaptiveRoot`
|
|
204
|
+
* forwards its own `nonce`. Defaults to the nonce of a script on the page.
|
|
205
|
+
*/
|
|
206
|
+
nonce?: string;
|
|
200
207
|
children: ReactNode;
|
|
201
208
|
};
|
|
202
209
|
/**
|
|
@@ -211,6 +218,9 @@ declare function AdaptiveProvider(props: AdaptiveProviderProps): JSX.Element;
|
|
|
211
218
|
declare function useSentient(): SentientClient | null;
|
|
212
219
|
/** Internal: SSR-preloaded assignments for hydration-safe first render. */
|
|
213
220
|
declare function useInitialAssignments(): Record<string, string>;
|
|
221
|
+
/** The `device:source` segment this provider decides and caches under —
|
|
222
|
+
* the SSR value when one was passed, else derived once per mount. */
|
|
223
|
+
declare function useSessionSegment(): string;
|
|
214
224
|
/**
|
|
215
225
|
* Returns the persona-specific section order from SSR, or null when no
|
|
216
226
|
* sections were declared on AdaptiveRoot or reliability is below threshold.
|
|
@@ -221,6 +231,14 @@ declare function useLayoutOrder(): string[] | null;
|
|
|
221
231
|
/** Internal: configured API base URL (devtools fetches /v1/explain against this, never a relative URL). */
|
|
222
232
|
declare function useAdaptiveApiBaseUrl(): string;
|
|
223
233
|
|
|
234
|
+
/**
|
|
235
|
+
* The element `<Adaptive>` renders around its content (audit S17: it was
|
|
236
|
+
* always a `<div>`, which is invalid inside a `<ul>`, a `<p>` or a table row
|
|
237
|
+
* and broke `display: grid` children). Intrinsic tags only: the wrapper is
|
|
238
|
+
* what exposure, goals and micro-signals observe, so it must be a real box —
|
|
239
|
+
* `display: contents` would give IntersectionObserver nothing to measure.
|
|
240
|
+
*/
|
|
241
|
+
type AdaptiveElement = 'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav' | 'span' | 'li' | 'figure' | 'form' | 'label' | 'td' | 'th';
|
|
224
242
|
type ScrollDepthGoal = {
|
|
225
243
|
type: 'scroll_depth';
|
|
226
244
|
threshold: number;
|
|
@@ -273,13 +291,15 @@ type AdaptiveSlotProps = {
|
|
|
273
291
|
* shape as AdaptiveGroup's. Form arms fire their own submitGoal regardless. */
|
|
274
292
|
goal?: string | GoalConfig;
|
|
275
293
|
className?: string;
|
|
294
|
+
/** Wrapper element. @default 'div' */
|
|
295
|
+
as?: AdaptiveElement;
|
|
276
296
|
/** On first registration the SDK sends the region's rendered text (capped at
|
|
277
297
|
* 400 chars) so dashboard-generated versions are grounded in what they
|
|
278
298
|
* replace. Set false for a slot wrapping personalized or account content —
|
|
279
299
|
* the text of THIS region is all that is ever read, never the page. */
|
|
280
300
|
reportBaselineText?: boolean;
|
|
281
301
|
};
|
|
282
|
-
declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
|
|
302
|
+
declare function AdaptiveSlot({ id, children, variants, onFormSubmit, goal, className, as: Tag, reportBaselineText, }: AdaptiveSlotProps): JSX.Element;
|
|
283
303
|
|
|
284
304
|
/** `<Adaptive>` with variants written in code — each key an arm, first key the control. */
|
|
285
305
|
type AdaptiveVariantsProps = {
|
|
@@ -305,6 +325,10 @@ type AdaptiveVariantsProps = {
|
|
|
305
325
|
* Use for inferred goals surfaced in the dashboard (e.g. rage_click → 'confused_by_hero').
|
|
306
326
|
*/
|
|
307
327
|
microSignalGoals?: MicroSignalGoals;
|
|
328
|
+
/** Wrapper element. @default 'div' */
|
|
329
|
+
as?: AdaptiveElement;
|
|
330
|
+
/** Class for the wrapper element. */
|
|
331
|
+
className?: string;
|
|
308
332
|
/**
|
|
309
333
|
* When true, renders nothing during SSR and before client hydration.
|
|
310
334
|
* Use when you cannot pass `initialAssignments` and prefer a blank slot over
|
|
@@ -510,6 +534,14 @@ type SentientPersonaScriptProps = {
|
|
|
510
534
|
persona: string;
|
|
511
535
|
confidence: number;
|
|
512
536
|
} | null;
|
|
537
|
+
/**
|
|
538
|
+
* The same consent gate you give the provider. With `consent={false}`, or a
|
|
539
|
+
* `consentFrom` source and no `consent={true}`, nothing is rendered: the
|
|
540
|
+
* fallback reads the stored decision from the visitor's device, and that
|
|
541
|
+
* must wait for consent (grader F3). `AdaptiveRoot` handles this for you.
|
|
542
|
+
*/
|
|
543
|
+
consent?: boolean;
|
|
544
|
+
consentFrom?: unknown;
|
|
513
545
|
};
|
|
514
546
|
/**
|
|
515
547
|
* Single writer of the Rung-1a `<html>` attributes
|
|
@@ -523,7 +555,7 @@ type SentientPersonaScriptProps = {
|
|
|
523
555
|
* (the same pattern next-themes uses). The client SDK adopts the attributes
|
|
524
556
|
* as truth and never rewrites them mid-session.
|
|
525
557
|
*/
|
|
526
|
-
declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element;
|
|
558
|
+
declare function SentientPersonaScript(props: SentientPersonaScriptProps): JSX.Element | null;
|
|
527
559
|
|
|
528
560
|
type UseAdaptiveTokensOptions = {
|
|
529
561
|
goal?: string | GoalConfig;
|
|
@@ -729,4 +761,4 @@ declare function renderBlocks(node: BlockNode, opts: RenderBlocksOptions): JSX.E
|
|
|
729
761
|
*/
|
|
730
762
|
declare function renderCompose(compose: ComposeArm, opts: RenderBlocksOptions): JSX.Element | null;
|
|
731
763
|
|
|
732
|
-
export { Adaptive, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient };
|
|
764
|
+
export { Adaptive, type AdaptiveElement, type AdaptiveGeneratedProps, AdaptiveGroup, type AdaptiveGroupProps, type AdaptivePersona, type AdaptiveProps, AdaptiveProvider, type AdaptiveProviderProps, AdaptiveSlot, type AdaptiveSlotProps, AdaptiveText, type AdaptiveTextProps, type AdaptiveVariantsProps, type AgentBlock, type AgentFeed, type AssignmentState, type ClickGoal, type ComponentWeights, type CompositeGoal, type FireGoal, type FormSubmitGoal, type GoalConfig, type MicroSignalGoalConfig, type MicroSignalGoals, type PageGoalOptions, type RenderBlocksOptions, type ScrollDepthGoal, SentientPersonaScript, type SentientPersonaScriptProps, type SsrFallback, type UseAdaptiveBind, type UseAdaptiveResult, type UseAdaptiveTokensOptions, type UseAdaptiveTokensResult, type VariantWeight, type WeightedCompositeGoal, type WeightedStep, buildAgentFeed, defineAgentContent, getAgentContent, renderAgentJsonLd, renderAgentJsonLdBody, renderAgentMarkdown, renderBlocks, renderCompose, useAdaptive, useAdaptiveApiBaseUrl, useAdaptiveGoal, useAdaptivePersona, useAdaptiveTokens, useAssignment, useInitialAssignments, useLayoutOrder, usePageGoal, useSentient, useSessionSegment };
|