# XWUIThemeScope A thin wrapper that makes everything inside read ONE token set, whatever the page theme is: a dark scene stage on a light page, a phone chassis, a wall display, a preview of a surface in the theme the user picked. It maps a scope name onto the style tier's existing hooks (`.xwui-night` and `.xwui-day` in `xwui-lib-style/src/theme/viz-tokens.css`) and adds no colour of its own. The projected root IS the host (adoptRoot), so a page class on the host keeps sizing and painting it and there is no wrapper level. ## Basic Usage ```example file: examples/BasicUsage.ts html: examples/BasicUsage.html title: Basic Usage description: A dark scene on a page that may be light: everything inside reads the dark tokens in both themes. ``` ```example file: examples/ThemePreview.ts html: examples/ThemePreview.html title: Theme Preview description: A preview of a surface in the theme the user picked, whatever the page theme is. ``` ## Data `content`: an element, an array of elements (attached as direct children, in order) or a string (text, never HTML). In tag form (`...markup...`) the light-DOM children are the content until `content` is set. ## Options | Option | Default | What it does | | --- | --- | --- | | `scope` | `'inherit'` | `'wall'` dark in both themes (night scope plus `data-surface="wall"`, the hook an app's own surface rules may restyle); `'night'` and `'day'` the style tier's scope classes; `'light'` and `'dark'` the same plus an explicit `data-theme`, so `[data-theme="dark"] .xwui-x` component rules apply inside too; `'inherit'` no scope (and the way to switch one off). An unknown value inherits. | | `role`, `ariaLabel` | none | A scope is a styling boundary, not a landmark: no role by default. A name implies `role="group"`; a name is only written with a role. | | `inline` | `false` | `inline-block` instead of `block`. | | `ground` | `false` | Paints the scope's own `--bg-app` and ink at zero specificity, so a bare scope (a theme preview) is a real ground. Default: paints nothing; the page class gives size and ground. | | `preserveChildren` | `false` | Keep the host's light-DOM children as the content (set automatically for a custom element that has children). | | `className` | none | Extra class on the host. | ## Events and methods `setScope(scope)`, `getScope()`, `setContent(content)`, `updateConfig(patch)`, `onScopeChange((scope, previous) => void): () => void`, `getElement()` (the host), `destroy()`. `setScope` patches the host's class and two attributes only: content nodes keep their identity (focus, listeners, running animations). `destroy()` takes back exactly the classes and attributes it wrote. ## What each scope sets | Scope | Class | `data-surface` | `data-theme` | | --- | --- | --- | --- | | `wall` | `xwui-night` | `wall` | none | | `night` | `xwui-night` | none | none | | `dark` | `xwui-night` | none | `dark` | | `day` | `xwui-day` | none | none | | `light` | `xwui-day` | none | `light` | | `inherit` | none | none | none | Known limit: the style tier declares the colour themes only on `:root[data-theme]`, so `dark` carries the night scope's palette (the scene navy), not the exact dark theme sheet; `light` equals the light theme exactly (`.xwui-day` repeats `colors/light.css`, held by a test). ## Accessibility and RTL No role, no tab stop, no focus handling: the component is invisible to assistive technology unless a role is given. Direction comes from the parent `dir`; the sheet has no physical property and the scope tokens do not depend on direction. Reduced motion and coarse pointers do not apply (nothing moves, nothing is a target). ```api ```