## Problem The component browser (`/admin/appearance/ui/components`) renders each component preview inline inside its card. A component written for a full page width therefore renders at ~330px card width with the page's theme styling. Wide components (grid rows, graphic lists) overflow and get cropped, and every preview changes appearance whenever the site's default theme changes. The library should give a predictable view of every component, styled the way the component is meant to look, on both the overview page and the single component page (Preview / Stories / Variants tabs). ## Resolution All three options were implemented rather than one being chosen: they solve different problems and a component library needs more than one. A fourth, `inline`, is kept as the "no isolation" escape hatch and is what previews fall back to when the feature is switched off. The decision is **per component**, not per site, because whether a preview needs a real document is a property of the component (does its JavaScript have to run?) rather than of the page showing it. ### Renderer precedence Highest first: 1. The component's own `.component.yml`, under core's `thirdPartySettings` extension point: ```yaml thirdPartySettings: ui_patterns_library_plus: renderer: iframe viewport_width: 400 max_height: 120 ``` `thirdPartySettings` is where core's component schema reserves space for contrib, so a declaration there cannot collide with a future SDC key. Bare top-level keys are deliberately **not** read. 2. The settings form's per-component override map — the layer for components the site builder does not control (contrib theme components). 3. The global default. The component author wins because they know their component. Values are narrowed at every layer: an unknown renderer id, or a size that is not a positive number, falls through to the next layer instead of reaching the template. Sizing follows the identical chain, so the rule is learned once. **Overview cards ignore the renderer setting and are always Declarative Shadow DOM.** A card is a static picture whose overlay link is the only click target, so the one thing DSD cannot do — run the component's JavaScript — is the one thing a card does not need. In exchange the grid stays a single document instead of one nested browsing context per card. ### Option 1: `thumbnail.png` as the card preview Core's autodetected `thumbnail.png` is used as the card image where a component ships one; components without one fall back to the normal preview. Off by default, configurable. Orthogonal to the renderer choice — it replaces rendering entirely. A thumbnail is a property of the component rather than of a story, so a component that ships one but authors no stories still gets a preview. Paths still absolute after core strips the app root are rejected: such a component cannot be served over HTTP, and emitting the path would produce a broken `<img src="/var/www/…">`. ### Option 2: iframe The preview is embedded as an `<iframe>` pointing at a dedicated, permission-gated route (`access components page`) that renders one story as a bare document. A true separate viewport: media queries match the iframe's own width, so breakpoint-driven reflow is faithful, and styles are fully isolated. **This is the only renderer where a component's own JavaScript runs**, which is why it is needed alongside DSD and why it is the shipped default for the single component page. Details that turned out to be load-bearing: - The document is produced by `renderBarePage()`, not the regular main-content pipeline. That pipeline fires `hook_page_top`/`hook_page_bottom`/`hook_page_attachments` in every enabled module, so toolbar, admin_toolbar and contextual would inject their markup and assets into the iframe. `renderBarePage()` attaches only the system defaults plus the active theme's own libraries. - The route is deliberately **not** an admin route, so theme negotiation resolves a front-end theme. - An iframe has no auto height. The framed document measures itself with a `ResizeObserver` and posts its height to the host; the host also asks for a measurement whenever it starts listening or reloads a frame, because a frame in the initial HTML can finish loading — and post — before the host's listener exists. Both directions are origin-checked. - A frame inside a closed tab has never been laid out and reports zero height. The tab component emits a `uipl:tab:shown` event on reveal and the host re-measures — a plain bubbling event rather than an `IntersectionObserver`, which is suspended while a browser tab is in the background. - On the single component page the frame *is* the content: it fills the panel at its real width, stays clickable, and is neither scaled nor height-capped. ### Option 3: Declarative Shadow DOM Each preview is rendered inside a `<template shadowrootmode="open">` shadow root carrying the component's own markup plus the stylesheet links of the theme the component lives in, independent of the selected default theme. The content comes from an internal sub-request to the same bare-document route, with the target theme active. Drupal's kernel does not re-negotiate themes for a `SUB_REQUEST`, so the active theme is switched by hand around it and restored afterwards. The resulting document is parsed, its head's stylesheet links deduplicated by href, and its body markup wrapped in a viewport box. No JavaScript and no per-card document: the browser attaches the shadow root natively on initial parse. Only the single component page's live Settings panel needs a small JS helper, because browsers parse `shadowrootmode` on initial document parse only, never in AJAX-inserted HTML. `<script>` elements are stripped from the whole sub-rendered document at any depth, not just the body's top level. A component is free to render `<div><script>…</script></div>`, and the two paths consuming this content disagree about what happens next: the overview prints it into `<template shadowrootmode>` for the parser, while the panel's AJAX update hands a plain `<template>` to a helper that appends into a live tree — where a script *would* execute. Stripping server-side means neither path has to be the safe one. ### Provider-theme rendering A component shipped by a theme previews with that theme's styling and scripts regardless of the site default, so a component from a design-system theme still looks right on a site themed with something else. Module-provided components use the site default. One rule the original proposal missed: **when the site's default theme inherits from the provider, the default theme wins.** Sub-theming is a first-class workflow for component themes — a starterkit generates sub-themes declaring the provider as their `base theme` — and a component the sub-theme has not overridden is still *provided by* the base theme. Using the provider there would preview the base theme's bare output and miss every token, override and stylesheet the sub-theme adds, which is the opposite of showing the component as it really is on that site. The default theme is strictly more specific and already loads the provider's libraries through the base-theme chain. DSD and iframe reach the same answer by different routes: DSD switches the active theme around its sub-request; the iframe is negotiated normally, via a theme negotiator on the preview route (priority 100, beating `theme.negotiator.default` at −100). Both delegate to one resolver so they cannot drift. ### Virtual viewport and scaling Card previews lay out at a configurable virtual viewport width and are scaled into the card with `transform: scale(cardWidth / viewport)`. `transform` rather than `zoom`: it applies to the preview as a single box and never to component DOM, so it cannot disturb nested positioning or stacking contexts. This applies to **both** card renderers, not only the iframe — the DSD viewport box runs the same scale pass, driven by custom properties that inherit into the shadow tree. The single component page renders at the panel's real width and is never scaled. ### Live Settings panel previews The single component page's Settings panel composes its preview from the authored story values plus whatever the visitor typed. In DSD mode that composed render array reaches the controller directly as a sub-request attribute — a channel no external request can populate. An iframe has no such channel: it is a real browser GET, and the route's three ids cannot express panel state. Putting prop and slot values in the iframe URL would mean caller-supplied values reaching the renderer, which the controller deliberately never allows. So the build is composed server-side as before and parked in the requesting user's own private tempstore; the iframe URL carries only `?live=1`, a request to read back whatever that user's own store holds. Nothing crosses the wire, and one user cannot address another's build. Nothing is written on a page render. The build a page render would park is the story the route renders anyway, so parking it bought nothing and cost a lock acquire plus a tempstore write per GET — and for an anonymous visitor `PrivateTempStore::set()` writes to the session, which starts one, sets a cookie, and makes that visitor uncacheable site-wide from then on. The first write happens on the first panel change instead, which is a POST. A `?live=1` request arriving with nothing parked is therefore the normal path, not an edge case, and falls back to the route's own story. ### Caching A sub-request is a full kernel pass plus a DOM parse of an entire HTML document, and the overview page needs one per card, so story fragments are cached in a dedicated bin (`cache.ui_patterns_library_plus_preview`) — its own bin rather than `cache.default` because the entries are large and entirely rebuildable, so a site can flush them without touching anything else. Invalidated by `component_plugins`, `config:system.theme` and `library_info`; the same tags go on the pages printing the fragments, since flushing the bin only helps if the surrounding page goes too. The cache id carries the resolved `user.permissions` hash, because a service-level cache has no render context to bubble that context into and a component's template is free to render something the visitor may not be allowed to see. Panel-composed builds are never cached: they are per user and superseded by the next keystroke. ## Configuration form The pre-existing colour-scheme form was widened into a single settings form (`SettingsForm`, replacing `ColorSchemeSettingsForm`) at `/admin/config/user-interface/ui-patterns-library-plus`, since both sets of keys live in one config object: | Setting | Default | Notes | |---|---|---| | Colour scheme | System | Pre-existing | | Isolate previews from the library page | on | Off renders every component inline, as the browser does without this module | | Default renderer for the single component page | **Iframe** | Overridable per component. Overview cards ignore it | | Render previews in their provider theme | on | Applies to both renderers | | Use thumbnail image defined in component | off | | | Virtual viewport width | 800px | Overview cards only | | Maximum preview height | 300px | Also caps a thumbnail; the single page is never capped | | Per-component preview overrides | empty | YAML map of component id → `renderer`, `viewport_width`, `max_height` | The override map is a YAML textarea, parsed and validated on submit so the error message can point at the offending input. Note it accepts `renderer` as well as the two sizes — the original proposal listed only viewport/height. Both dimensions are guarded on the way in at three points, because zero is not a smaller setting but a broken one — a zero viewport width reaches the card as `--uipl-preview-viewport: 0px` and collapses the preview box to nothing, and both numbers are divisors client-side: - `'#min' => 1` as an element property, so `Number::validateNumber()` enforces it server-side rather than it being only a browser hint; - a `Range: min: 1` schema constraint on all four integer keys, so a value written straight into config is rejected too; - a fallback to the stored value for the empty string an emptied field submits, which `#min` deliberately passes over. The config object is `FullyValidatable`, so every key must exist — hence one update hook per key group (`11001` seeds `color_scheme`, `11002` the `preview` mapping) and `requiredKey: false` on the optional override keys. ## Known limitations Inherent to shadow DOM rather than to this module, and the reason the iframe renderer exists: - **A component's JavaScript does not run under DSD.** A shadow root is invisible to `document`-scoped queries, retargets events crossing its boundary to the host element, and hides its ids from `document.getElementById()`. Design-system libraries are commonly built on all three patterns, so loading their scripts changes nothing. Two distinct symptoms, and the difference matters when deciding what to do: - *Markup complete, behaviour dead* — an accordion shows every panel expanded and will not collapse. The preview still looks like the component. - *Markup itself is JavaScript-built, so the preview is a stub* — a date picker may ship only a `<label>` and a text `<input>`, with the calendar button, and the icon on it, constructed at runtime. Under DSD you get the bare text field, which reads as a rendering bug but is the component behaving exactly as it must. Combo boxes, time pickers and tooltips are frequently the same shape. - Media queries inside the shadow root evaluate against the real browser width; the scale pass fixes layout width, not breakpoints. - Theme tokens scoped to `:root` / `html` / `body` selectors do not apply within a shadow root. Guidance in the UI and README: move a component to the iframe when it is interactive **or** when its preview looks incomplete. A missing icon, button or panel is almost always a runtime-built component, not a styling problem to chase. This still enables the original end goal — the library pages themselves can move to the admin theme while only the previews carry front-theme styling — but that move is not part of this issue. ## References - [#3562060] "Render UI with admin theme" + MR !183 — DSD via sub-requests; prior art and documented limitations.