@encorekit/web-sdk 2.0.2 → 2.0.3

package/README.md

@@ -16,7 +16,7 @@ A JavaScript/TypeScript SDK that enables web applications to display targeted of
 ## Installation
 
 ```bash
-npm install @encorekit/web-sdk@3.0.0
+npm install @encorekit/web-sdk
 ```
 
 Or via CDN:
@@ -25,9 +25,9 @@ Or via CDN:
 <script src="https://encorekit.com/encore.min.js"></script>
 ```
 
-## Upgrading to 3.0.0
+## Upgrading to 2.0.2
 
-3.0.0 removes the deferred redemption flow and the layout system. Claiming an
+2.0.2 removes the deferred redemption flow and the layout system. Claiming an
 offer now always redirects to the advertiser immediately, and the composition is
 derived from the placement's use case.
 
@@ -112,9 +112,107 @@ await Encore.show(
 | `useCase` | `'reduceChurn' \| 'rewardUsers'` | Why the placement presents, and which composition it renders. Defaults to `'reduceChurn'`. |
 | `headline` | `string` | Per-call override of the sheet's primary heading. |
 | `subheadline` | `string` | Per-call override of the line under it. |
-| `appearance` | `{ backgroundColor?, textColor?, accentColor? }` | Colour overrides for the sheet. |
+| `appearance` | `AppearanceConfig` | Optional colour and per-element overrides. Advanced — see [Appearance](#appearance-advanced--optional). |
 | `statusIcon` | `'success' \| 'none'` | Status icon above the headline. Defaults to `'none'` — nothing renders unless you ask for `'success'`, which draws a green-circle check. Only `'rewardUsers'` has a status block; `'reduceChurn'` ignores it. The default matches iOS and Android, whose reward variant renders no checkmark. |
 
+### Appearance (advanced — optional)
+
+**You can skip this.** Omitting `appearance` renders the SDK's default sheet, which is
+the normal integration path. Everything below is opt-in.
+
+Changing a colour is one line:
+
+```typescript
+await Encore.show(undefined, { appearance: { accentColor: '#0A6' } });
+```
+
+| Option | Type | What it moves |
+|:-------|:-----|:--------------|
+| `accentColor` | colour | `--encore-primary-color`: focus rings, links, the churn CTA. |
+| `backgroundColor` | colour | `--encore-bg-color`: the sheet canvas and every surface derived from it. |
+| `textColor` | colour | `--encore-text-color`, from which muted and secondary ink are derived. |
+| `modalBackgroundColor` | colour | The modal container only — narrower than `backgroundColor`. |
+| `dotColor` / `dotActiveColor` | colour | The page indicator's inactive / active dots. |
+| `headline` / `subheadline` | slot | The reward sheet's heading and the line under it. |
+| `claimButton` / `declineButton` | slot | The "Claim gift" CTA and the "No thanks" button. |
+
+Colours accept hex, `rgb()`/`hsl()`/`oklch()` and friends, named colours, and
+`var(--your-token)`. Slot fields are read by the `'rewardUsers'` composition — the one
+with a heading block, a CTA pair and page dots; `'reduceChurn'` renders the bare
+carousel and uses the colours only.
+
+#### Slots
+
+A **slot** takes whichever of these three you need — nothing more:
+
+```typescript
+appearance: {
+  // 1. Styled text. No DOM required.
+  headline: {
+    text: 'Nice work, Sam!',
+    color: '#FFD166',
+    fontFamily: '"Söhne", system-ui, sans-serif',
+    fontSize: '28px',
+    fontWeight: 700,
+  },
+
+  // 2. Your own element. Render something that is not text at all.
+  subheadline: myStreakBadgeElement,
+
+  // 3. A render function, called per presentation.
+  claimButton: ({ text, useCase, defaultElement }) => myCta(text),
+}
+```
+
+A render function receives `text` (the copy the SDK resolved), `useCase`, and
+`defaultElement` — the element the SDK would have rendered. Return `defaultElement` to
+decorate rather than replace, which keeps every default style and accessibility
+attribute:
+
+```typescript
+declineButton: ({ defaultElement }) => {
+  defaultElement.classList.add('my-ghost-button');
+  return defaultElement;
+}
+```
+
+Text fields accept `text`, `color`, `fontFamily`, `fontSize`, `fontWeight`,
+`letterSpacing` and `textAlign`; button slots add `backgroundColor`, `borderColor` and
+`borderRadius`.
+
+`fontFamily` accepts Latin family names, including accented ones (`"Söhne"`, `Größe`).
+A family name in a non-Latin script (CJK, Cyrillic, Arabic) is not accepted on this
+path — use the element or render-function form for those, which applies your own CSS
+and bypasses the check entirely.
+
+#### Precedence and fallbacks
+
+Copy resolves per field, most specific first:
+
+`appearance.headline.text` → `PlacementOptions.headline` → backend-resolved copy →
+the SDK's built-in fallback.
+
+A blank or whitespace-only value falls **through** to the next tier rather than blanking
+the slot, so omit a field instead of passing `''`.
+
+#### Two guarantees
+
+**A bad override costs you the override, never the sheet.** Render functions run inside
+a guard and colours/fonts/sizes go through an allow-list, so a throw, a non-element
+return, a wrong type or a malformed colour falls back to the SDK's default element. The
+modal cannot be taken down by anything you pass.
+
+**The SDK keeps the action.** On `claimButton` and `declineButton` you supply appearance
+only. Your element is mounted inside an SDK-owned control that carries the role, the tab
+stop and the listener; the listener runs in the capture phase, so the SDK's
+claim/decline runs first and a handler you attached to your own element does not run.
+Read the outcome from `show()`'s resolved `ShowResult` — that is the supported way to
+react to a claim or a dismissal.
+
+> The element you pass is **adopted**: it is moved into the sheet and removed with it.
+> Pass a fresh element (or use a render function) rather than one that is live in your
+> page, and do not pass the same element to two slots.
+
 ### The result
 
 `show()` **never rejects**. It resolves one of three statuses: