Skip to content

feat(visual): let an embedded example show its controls - #227

Open
alexgrozav wants to merge 3 commits into
mainfrom
embed-controls-uxf-906
Open

alexgrozav wants to merge 3 commits into
mainfrom
embed-controls-uxf-906

Conversation

@alexgrozav

Copy link
Copy Markdown
Contributor

What changed

An example opened by its own URL (embed.html, ADR-0112) now takes three optional parameters, recorded in ADR-0116, which amends ADR-0112 and ADR-0088:

  • controls=true shows the example's controls below it, in a shadow root, with the same groups, fields and props rule as the shell's example panel. The rule and the fields now live in controlKit (src/preview/panel.ts), which the frame imports and the shell writes into its page, so the two can't drift. The shell's rendered CSS is byte-for-byte unchanged.
  • theme=light|dark sets data-theme and color-scheme on the frame's <html> before the first render. The frame then takes { type: "unframework:embed", kind: "theme", theme } from its parent window only, with exactly those keys.
  • resize=true lays the page out at its natural height and posts { type: "unframework:embed", kind: "resize", height } to the parent when the height changes.

embed.html and the standalone frame both check the values with one function (embedOptions) and show a message for any other value. Without the parameters, an embed is unchanged, and the shell's frames are unchanged.

The docs page's "Embed an example" section, the package README and a changeset (minor) describe the change. No framework's output changes.

How it was tested

  • New: embed-options.test.ts (option parsing, the props rule) and frame.browser.test.ts (startFrame with a recording mount).
  • New in preview-build.test.ts (static site) and preview.test.ts (dev): controls on seven targets compared with the shell's frames, Astro's static first-props limit in an embed, the panel and its first field in a 300 px and a 150 px iframe, the theme message from a second origin, and the height report alone and with controls, settling with nothing scrolling.
  • A new fixture, test/fixtures/embed, covers Styleframe's [data-theme="dark"] selector, a project's global styles against the panel, and a control that changes the height.
  • Mutation checks: a missing natural layout, a theme listener without its source check, the mode set after the first render, a failure that replaces the page and a missing fixed layout each fail a test.

Checklist

  • The title follows Conventional Commits, as in feat(web): sell the next framework on the homepage.
  • pnpm format:check, pnpm lint, pnpm check-types and pnpm test pass. The first three pass. Of the tests, pnpm --filter @unframework.dev/visual test (284 tests) and pnpm test:quick pass, and the full pnpm test didn't run locally, since no compiler output changes.
  • Changes to a published package: a changeset, .changeset/embed-controls-uxf-906.md, written by hand in the format of the earlier ones.
  • Homepage changes: not one. The docs site builds (pnpm --filter web build).

alexgrozav and others added 3 commits November 20, 2026 16:20
An embed takes three optional URL parameters (ADR-0116). controls=true draws
the example's controls below it in a shadow root, with the shell's props rule
from one shared function. theme sets the colour mode before the first render
and takes a theme message from the parent window only. resize=true lays the
page out at its natural height and posts that height to the parent.

Co-authored-by: multica-agent <github@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
@github-actions

Copy link
Copy Markdown
Contributor

Visual report: ✓ passed

3 examples on 7 targets. Pixels: live, compared with the reference's capture in this run. Reference: vue. Commit 5a86517.

Example react vue (reference) svelte solid angular qwik astro
examples/Buttons ✓ matched, 0 px ✓ published-reference ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px
examples/Card ✓ matched, 0 px ✓ published-reference ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px
examples/TextField ✓ matched, 0 px ✓ published-reference ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px ✓ matched, 0 px

The run uploaded the full report as the design-system-visual artefact, kept for 7 days. Download it, unzip it and open report.html.

@alexgrozav
alexgrozav marked this pull request as ready for review November 20, 2026 14:37
@cloudflare-workers-and-pages

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://embed-controls-uxf-906.unframework.dev, https://embed-controls-uxf-906-unframework.blue-water-0397.workers.dev (commit 5a86517)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://ff27b575.unframework.dev, https://ff27b575-unframework.blue-water-0397.workers.dev 5a86517 2026-11-20T14:30:48.720Z Visit the dashboard ↗

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant