Skip to content

feat: code variants on previews, page switch, IframePreview (0.1.13-alpha) - #35

Merged
Shewart merged 6 commits into
mainfrom
feat/preview-code-variants
Oct 10, 2026
Merged

Shewart merged 6 commits into
mainfrom
feat/preview-code-variants

Conversation

@Shewart

@Shewart Shewart commented Oct 10, 2026

Copy link
Copy Markdown
Contributor

Summary

Code variants for cross-platform libraries, first for the ShellUI Native docs: one live preview with code for several platforms (MAUI and Avalonia XAML), like shadcn/ui's library tabs. Also fixes one-line component bodies being wrapped in <p>. Bumps to 0.1.13-alpha.

Added

  • Code tabs on previews. <DemoPreview>, <ComponentPreview> and <IframePreview> take <CodeTab Label="…"> children with a fence inside, or CodeTabs from .razor.
    • The Code panel shows them as tabs instead of the Razor source, and copy copies the visible tab.
    • SyncKey switches blocks together across pages and remembers the choice.
    • A block missing the chosen tab shows "Not available on {label} yet" and keeps its height.
    • Without code tabs nothing changes.
  • Page switch. o.AddSyncSwitch("platform", "MAUI", "Avalonia") adds shadcn-style underlined tabs to pages whose blocks use that key: under the page header, or above the first such block. <SyncSwitch SyncKey> places one by hand.
  • Caption. Caption="…" adds a muted note to the toolbar; o.PreviewCaption sets a site default.
  • <IframePreview Src Height Lazy SyncKey Caption> shows another page, e.g. Avalonia on WebAssembly.
    • It loads when visible (default), on a Run button (Lazy="click") or at once (none).
    • It appends ?theme=light|dark and posts { type: "shelldocs-theme", theme } on theme change.
  • XAML highlighting: xaml / axaml highlight as XML. The init template loads Shiki's xml; existing sites add 'xml' to langs.

Fixed

  • <Badge>v0.3.2</Badge> in prose no longer wraps its text in <p>. As in MDX, a body on the same line as its tags renders inline; multi-line bodies keep their paragraphs.

Notes

  • All of it works in a static export: server-rendered, data-* attributes, shelldocs.js, no @onclick.
  • razor:preview fences can't take code tabs, since their body is Razor.

Testing

  • Release build 0 warnings; 337 tests pass, 15 new: code-tab parsing, variants, the missing-tab note, page switch, caption, iframe markup and inline bodies. Each commit builds and passes on its own.
  • Example site checked, both interactive and as a shelldocs build static export:
    • tab switching and sync, the page switch, the missing note keeping its height, and copy;
    • lazy and click iframe loads, ?theme=, and the theme message;
    • light and dark, at desktop and 375px widths.
  • Pack dry-run: all six packages at 0.1.13-alpha.
  • ShellUI docs site built against this branch: 240/242 pages unchanged; the two introduction pages lose only the badge <p>.

<Badge>v0.3.2 stable</Badge> in prose rendered a <p> inside the badge, so the page's paragraph margin and colour overrode it. As in MDX, a body on the same line as its tags now renders inline; a body on its own lines still becomes paragraphs.
…nd a caption

<DemoPreview> and <ComponentPreview> take <CodeTab Label> children with a fence inside (or CodeTabs from .razor); the Code panel shows them as tabs instead of the Razor source, e.g. MAUI and Avalonia XAML for a cross-platform library. CodeTabParser reads them from the raw body with RazorTagScanner and the CommonMark fence regex. SyncKey uses the [data-tabs] contract, so blocks switch together and remember the choice; a block without the chosen tab shows "Not available on {label} yet" and keeps its height (panels share one grid cell). Copy copies the visible tab. Caption, or ShellDocsOptions.PreviewCaption, adds a muted note to the toolbar. xaml/axaml fences highlight as XML, and the init template loads Shiki's xml grammar.
o.AddSyncSwitch("platform", "MAUI", "Avalonia") adds underlined tabs, like shadcn/ui's library switch, to pages whose blocks use that key: under the page header, or just above the first such block. <SyncSwitch SyncKey> places one by hand. It is a [data-tabs] group without panels, so it drives the same saved choice; until a reader picks, blocks follow its first option.
<IframePreview Src Height Lazy SyncKey Caption Title Id> shows another page (a live Avalonia app on WebAssembly, for instance) in the Preview panel with the same toolbar and code tabs. shelldocs.js sets the iframe's src, with ?theme=light|dark, when it scrolls into view (default), on a Run live preview button (Lazy="click") or at once ("none"), and posts { type: "shelldocs-theme", theme } to the frame's origin when the theme changes. The Code tab is hidden when there's no code.
Example site: a Code variants page covering code tabs, the missing-tab note, the page switch, captions and IframePreview with its URL and message contract, plus wwwroot/preview/index.html, a test page that follows that contract. CHANGELOG [Unreleased], README and ARCHITECTURE describe the new features and the inline-body fix.
Cuts the Unreleased section as 0.1.13-alpha and records the release in the ROADMAP's hardening list.
@Shewart
Shewart merged commit cb539a1 into main Oct 10, 2026
1 check passed
@Shewart
Shewart deleted the feat/preview-code-variants branch October 10, 2026 00:37
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