@tesouro/embedded-components-react 0.9.1 → 0.9.4

package/README.md

@@ -165,6 +165,82 @@ all utilities are `ttw`-prefixed, so it won't collide with your own Tailwind.
 Design tokens (`--ttw-*`) are declared on `:root` / `.dark`. Dark mode follows an
 ancestor `.dark` class, and you can set the widget font with `--ttw-font-family`.
 
+### Theming
+
+Widgets read their look from `--ttw-*` CSS variables. Set them on `:root`, or
+on any element around the widgets, in plain CSS or with `createTheme`.
+
+**Basic theming** is all most integrations need: your brand color, the corner
+radius and the font.
+
+```tsx
+import type { CSSProperties } from 'react';
+import { createTheme, themeToCss } from '@tesouro/embedded-components-react';
+
+const theme = createTheme({
+  primary: '#0f766e',
+  primaryForeground: '#ffffff',
+  radius: '0.5rem',
+  fontFamily: 'Inter, sans-serif',
+});
+
+// On a wrapper around the widgets…
+<div style={theme as CSSProperties}>{/* widgets */}</div>;
+// …or once for the page: themeToCss(theme) prints a `:root { … }` rule.
+```
+
+A wrapper theme reaches the widgets' dialogs, sheets and menus too, although
+they render at the end of `<body>`: the widgets copy the wrapper's values onto
+their overlay root each time they render.
+
+Nested widgets share that overlay root. When a themed widget sits inside
+another widget (or inside another `WidgetProvider` / `RootWidgetProvider`
+scope), its dialogs, sheets and menus render into the outer scope's overlay
+root and so take the outer theme. If two widgets need different themes, theme
+the outermost wrapper, or render them side by side rather than nested.
+
+**Advanced theming** reaches every public variable:
+
+| Group      | Keys (`createTheme`) and variables                                                                                                                                               |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Surfaces   | `background`, `foreground`, `card`, `cardForeground`, `popover`, `popoverForeground`, `muted`, `mutedForeground` (`--ttw-background` …)                                          |
+| Actions    | `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`                                         |
+| Lines      | `border`, `input`, `ring`                                                                                                                                                        |
+| Tones      | `info`, `success`, `warning`, and `destructive`: one color each for a status badge                                                                                               |
+| Accents    | `violet`, `cyan`: for a status no tone carries                                                                                                                                   |
+| Overrides  | `<tone>Subtle` and `<tone>Foreground` (`--ttw-success-subtle`, `--ttw-success-foreground`; for destructive, `destructiveSubtle` and `destructiveSubtleForeground`), all optional |
+| Overlay    | `overlay`: the scrim behind dialogs and sheets, black at 50% by default                                                                                                          |
+| Shape/type | `radius` (0–1.25rem), `fontFamily`                                                                                                                                               |
+
+A tone or accent is one color. The badge's tinted fill and its text are
+derived from it where the badge is painted, so they follow a dark card or a
+tinted page without extra variables; set the `Subtle` / `Foreground` override
+only to pick either half yourself.
+
+**Compatibility variables.** `surfaceSubtle` (`--ttw-surface-subtle`) and the
+eight sidebar keys (`sidebar`, `sidebarForeground`, `sidebarPrimary`,
+`sidebarPrimaryForeground`, `sidebarAccent`, `sidebarAccentForeground`,
+`sidebarBorder`, `sidebarRing`) keep working for existing themes and will be
+removed in a future major version. None is declared: until you set one,
+`surfaceSubtle` is `muted` and each sidebar color is its base color (`card`,
+`foreground`, `primary`, `accent`, `border`, `ring`). A new theme can leave
+them out.
+
+In development, `createTheme` warns once in the console about unknown keys,
+text under 4.5:1 contrast (3:1 for `mutedForeground` on `muted`) and a radius
+outside 0–1.25rem, and the widgets run the same contrast check once against
+the theme they actually render with.
+Nothing warns in production, and a warning never stops a widget rendering.
+`themeIssues(tokens)` returns the same findings as data, for a test in your
+own CI; a variable you leave out is judged at its default, so
+`themeIssues(createTheme({ primary }))` checks `primary` against the default
+`primaryForeground`.
+
+Only the variables above are supported. Tailwind's own variables share the
+`--ttw-` prefix (`--ttw-spacing`, `--ttw-text-sm`, `--ttw-color-*` …) because
+the utilities are prefixed `ttw`; they are pinned inside the widgets, so
+setting one has no effect. `--ttw-chart-*` were removed.
+
 <!-- BEGIN GENERATED REFERENCE -->
 
 ## Providers

package/dist/core.js

@@ -1,2 +1,3 @@
 import { createWidgetTokenManager as e } from "./libs/tesouro-embedded-components-react/shared/util/dist/lib/widgetTokenManager.js";
+import "./libs/tesouro-embedded-components-react/shared/util/dist/index.js";
 export { e as createWidgetTokenManager };