From 9db0829a7c2d6dd5b4e92bdf9f9807375db6f98f Mon Sep 17 00:00:00 2001 From: Shewart Date: Sat, 3 Oct 2026 00:55:48 +0200 Subject: [PATCH 1/6] fix(sidebar): link a folder's index page from its label instead of listing it twice A folder with an index.md showed its title twice: as the section label and as a page right under it. The label now links to the index page (highlighted when current) and the page isn't repeated; collapsible sections keep a separate chevron toggle. aria-expanded is written as "true"/"false", since Blazor dropped the attribute when false. --- .../Chrome/DocsSidebar.razor.css | 34 +++++++++- .../Chrome/DocsSidebarNode.razor | 48 ++++++++++++-- .../ShellDocs.Tests/SidebarIndexPageTests.cs | 64 +++++++++++++++++++ 3 files changed, 140 insertions(+), 6 deletions(-) create mode 100644 tests/ShellDocs.Tests/SidebarIndexPageTests.cs diff --git a/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css b/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css index 708080f..e7ee97b 100644 --- a/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css +++ b/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css @@ -117,10 +117,42 @@ margin-left: 0.25rem; transition: transform 200ms cubic-bezier(0.16, 1, 0.3, 1); } -::deep .sidebar-section[data-open="true"] > .sidebar-section-toggle .sidebar-section-chevron { +::deep .sidebar-section[data-open="true"] > .sidebar-section-toggle .sidebar-section-chevron, +::deep .sidebar-section[data-open="true"] > .sidebar-section-row .sidebar-section-chevron { transform: rotate(90deg); } +/* A section whose folder has an index.md: the label links to that page; in a + collapsible section the chevron is its own toggle button. */ +::deep .sidebar-section-link { + text-decoration: none; + border-radius: calc(var(--radius) - 3px); + transition: background 150ms, color 150ms; +} +::deep .sidebar-section-link:hover { background: var(--muted); } +::deep .sidebar-section-link.active { background: var(--accent); } +::deep .sidebar-section[data-depth="0"] > .sidebar-section-link { padding: 0.3rem 0.5rem; margin: 0.15rem 0 0.35rem 0; } +::deep .sidebar-section > .sidebar-section-label.sidebar-section-row { + padding: 0; + gap: 0; +} +::deep .sidebar-section-row > .sidebar-section-link { + display: inline-flex; + align-items: center; + gap: 0.55rem; + flex: 1; + min-width: 0; + color: inherit; + padding: 0.45rem 0.25rem 0.45rem 0.55rem; +} +::deep .sidebar-section-row > .sidebar-section-toggle { + display: inline-flex; + align-items: center; + padding: 0.45rem 0.5rem; + color: inherit; +} +::deep .sidebar-section-row > .sidebar-section-toggle .sidebar-section-chevron { margin-left: 0; } + /* grid-rows 0fr→1fr animates to natural height without a fixed max-height; the inner wrapper needs min-height: 0 to collapse fully. */ ::deep .sidebar-section-shell { diff --git a/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor b/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor index 202079b..fd7631e 100644 --- a/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor +++ b/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor @@ -11,10 +11,28 @@ else if (Node.Kind == NodeKind.Section)
@if (!string.IsNullOrEmpty(Node.Title)) { - @if (_isToggleable) + @* A folder's index.md is the label's link, not a second item with the same title. *@ + @if (_index is not null && _isToggleable) + { +
+ + @RenderLabelInner() + + +
+ } + else if (_index is not null) + { + + @RenderLabelInner() + + } + else if (_isToggleable) { @* Toggled by shelldocs.js so it works without a Blazor runtime. *@ - @@ -30,7 +48,7 @@ else if (Node.Kind == NodeKind.Section) {
- @foreach (var child in Node.Children.Where(c => !Versions.IsHiddenInSidebar(c))) + @foreach (var child in VisibleChildren) { } @@ -40,7 +58,7 @@ else if (Node.Kind == NodeKind.Section) else {
- @foreach (var child in Node.Children.Where(c => !Versions.IsHiddenInSidebar(c))) + @foreach (var child in VisibleChildren) { } @@ -50,7 +68,7 @@ else if (Node.Kind == NodeKind.Section) } else { - var isActive = string.Equals(Node.Url.TrimEnd('/'), CurrentPath.TrimEnd('/'), StringComparison.OrdinalIgnoreCase); + var isActive = IsActive(Node); var itemIcon = Depth <= 1 ? SidebarIcons.Get(Node.Title) : null; @if (itemIcon is not null) @@ -68,11 +86,13 @@ else private bool _isOpen; private bool _isToggleable; + private NavigationNode? _index; private bool _initialized; private string _lastPath = ""; protected override void OnParametersSet() { + _index = Node.Kind == NodeKind.Section && !string.IsNullOrEmpty(Node.Title) ? FindIndexPage(Node) : null; _isToggleable = Node.Kind == NodeKind.Section && Depth >= 1 && Node.Children.Any(c => c.Kind == NodeKind.Page); @@ -94,6 +114,24 @@ else _lastPath = CurrentPath; } + private IEnumerable VisibleChildren + => Node.Children.Where(c => c != _index && !Versions.IsHiddenInSidebar(c)); + + private bool IsActive(NavigationNode page) + => string.Equals(page.Url.TrimEnd('/'), CurrentPath.TrimEnd('/'), StringComparison.OrdinalIgnoreCase); + + // The page built from the section's own folder/index.md. + private static NavigationNode? FindIndexPage(NavigationNode section) + { + if (string.IsNullOrEmpty(section.Path)) return null; + var folder = System.IO.Path.TrimEndingDirectorySeparator(System.IO.Path.GetFullPath(section.Path)); + return section.Children.FirstOrDefault(c => + c.Kind == NodeKind.Page + && !string.IsNullOrEmpty(c.Path) + && string.Equals(System.IO.Path.GetFileName(c.Path), "index.md", StringComparison.OrdinalIgnoreCase) + && string.Equals(System.IO.Path.GetDirectoryName(System.IO.Path.GetFullPath(c.Path)), folder, StringComparison.OrdinalIgnoreCase)); + } + private static bool ContainsPath(NavigationNode node, string path) { if (string.IsNullOrEmpty(path)) return false; diff --git a/tests/ShellDocs.Tests/SidebarIndexPageTests.cs b/tests/ShellDocs.Tests/SidebarIndexPageTests.cs new file mode 100644 index 0000000..7d6f560 --- /dev/null +++ b/tests/ShellDocs.Tests/SidebarIndexPageTests.cs @@ -0,0 +1,64 @@ +using System.Text.RegularExpressions; +using ShellDocs.Components; +using ShellDocs.Components.Chrome; +using Xunit; + +namespace ShellDocs.Tests; + +// content/docs: introduction, components/index with form/index and form/button. +// docs/ is the top-level section, so components and form are collapsible. +public class SidebarIndexPageTests : IDisposable +{ + private readonly string _root; + + public SidebarIndexPageTests() + { + _root = Path.Combine(Path.GetTempPath(), "shelldocs-sidebar-index-" + Guid.NewGuid().ToString("N")); + Write("docs/introduction.md", "Introduction"); + Write("docs/components/index.md", "Components"); + Write("docs/components/form/index.md", "Form Components"); + Write("docs/components/form/button.md", "Button"); + } + + public void Dispose() + { + try { Directory.Delete(_root, recursive: true); } catch { } + } + + private void Write(string rel, string title) + { + var full = Path.Combine(_root, rel); + Directory.CreateDirectory(Path.GetDirectoryName(full)!); + File.WriteAllText(full, $"---\ntitle: {title}\n---\n# {title}\n"); + } + + private Task Render(string path) => new ComponentRenderHarness(o => + { + o.ContentRoot = _root; + o.LayoutVariant = DocsLayoutVariant.Sidebar; + }, "http://localhost" + path).RenderAsync(); + + [Fact] + public async Task IndexPage_IsTheSectionsLink_NotASecondItem() + { + var html = await Render("/docs/introduction"); + + Assert.Single(Regex.Matches(html, "href=\"/docs/components\"")); + Assert.Matches("Form Components<", html); + } +} From bff161cc95664f10ba854965fc1b88ffaa5badbd Mon Sep 17 00:00:00 2001 From: Shewart Date: Sat, 3 Oct 2026 00:55:49 +0200 Subject: [PATCH 2/6] fix(prose): scroll wide tables inside their own box A markdown table wider than the viewport widened the whole page on phones. Rendered tables are wrapped in .shelldocs-table, which scrolls horizontally. --- src/ShellDocs.Components/wwwroot/shelldocs-theme.css | 2 ++ src/ShellDocs.Markdown/MarkdownRenderer.cs | 10 +++++++++- tests/ShellDocs.Tests/MarkdownRendererTests.cs | 12 ++++++++++++ 3 files changed, 23 insertions(+), 1 deletion(-) diff --git a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css index bd69a35..8b76a99 100644 --- a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css +++ b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css @@ -84,6 +84,8 @@ body { margin: 0; min-height: 100vh; } border-radius: var(--radius); overflow: hidden; } +.shelldocs-table { overflow-x: auto; max-width: 100%; } +.shelldocs-table > table { min-width: 100%; } .shelldocs-prose th:where(:not(.not-prose, .not-prose *)), .shelldocs-prose td:where(:not(.not-prose, .not-prose *)) { padding: 0.625rem 0.875rem; text-align: left; border-bottom: 1px solid var(--border); } .shelldocs-prose th:where(:not(.not-prose, .not-prose *)) { font-weight: 600; color: var(--foreground); background: var(--muted); font-size: 0.8125rem; } .shelldocs-prose tr:last-child td:where(:not(.not-prose, .not-prose *)) { border-bottom: 0; } diff --git a/src/ShellDocs.Markdown/MarkdownRenderer.cs b/src/ShellDocs.Markdown/MarkdownRenderer.cs index e06094f..068cda1 100644 --- a/src/ShellDocs.Markdown/MarkdownRenderer.cs +++ b/src/ShellDocs.Markdown/MarkdownRenderer.cs @@ -1,3 +1,4 @@ +using System.Text.RegularExpressions; using Markdig; using ShellDocs.Core; @@ -28,13 +29,20 @@ public RenderedDocument Render(string markdown) var doc = Markdig.Markdown.Parse(processed, _pipeline); var headings = HeadingExtractor.Extract(doc); - var html = CodeBlockEnhancer.Enhance(doc.ToHtml(_pipeline)); + var html = WrapTables(CodeBlockEnhancer.Enhance(doc.ToHtml(_pipeline))); return new RenderedDocument(html, slots, parsed, headings); } public RenderedDocument RenderFile(string path) => Render(File.ReadAllText(path)); + // Tables scroll inside their own box, so a wide one doesn't widen the page on phones. + private static readonly Regex TableOpen = new(@"]*)?>", RegexOptions.Compiled | RegexOptions.IgnoreCase); + private static readonly Regex TableClose = new(@"", RegexOptions.Compiled | RegexOptions.IgnoreCase); + + internal static string WrapTables(string html) + => TableClose.Replace(TableOpen.Replace(html, m => "
" + m.Value), "
"); + // Razor markup (component child content inside a razor:preview) parsed into // nodes the way the fence itself is: no markdown pass, so nothing gets wrapped // in

and elements around nested components stay intact. diff --git a/tests/ShellDocs.Tests/MarkdownRendererTests.cs b/tests/ShellDocs.Tests/MarkdownRendererTests.cs index 06bbe03..fb5647c 100644 --- a/tests/ShellDocs.Tests/MarkdownRendererTests.cs +++ b/tests/ShellDocs.Tests/MarkdownRendererTests.cs @@ -153,3 +153,15 @@ public void Render_EmptyDocument_ReturnsEmptyShape() Assert.Empty(doc.Headings); } } + +public class TableWrappingTests +{ + [Fact] + public void MarkdownTables_ScrollInTheirOwnBox() + { + var html = new MarkdownRenderer().Render("| Prop | Type |\n|---|---|\n| Class | string |\n").Html; + + Assert.Contains("

", html); + Assert.Contains("
", html); + } +} From 6e78631ddfa4fa6054a2f6eecf313ce9093e5c40 Mon Sep 17 00:00:00 2001 From: Shewart Date: Sat, 3 Oct 2026 00:55:50 +0200 Subject: [PATCH 3/6] docs: changelog for the sidebar and table fixes --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index aca6e32..7b5dbe1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht ## [Unreleased] +### Fixed + +- **Sidebar listed a folder's `index.md` twice**: once as the section label and again as a page with the same title. The label now links to the index page (highlighted when it's the current page) and the page isn't repeated; in collapsible sections the chevron is its own toggle button. +- **Collapsed sidebar sections had no `aria-expanded`**: Blazor drops a `false` boolean attribute, so the toggle now writes `"true"` / `"false"`. +- **Wide markdown tables widened the page on phones.** Tables render inside a `.shelldocs-table` box that scrolls horizontally. + ## [0.1.10-alpha] — 2026-10-02 Previews that look like the real thing (no page typography leaking in, Razor child content, stretch layout, generic components), redirects for folders, version roots and moved URLs, an optional frontmatter page header, and a theme that stays in sync with whatever flips it. From a4e8da86a4279ee99f3b25f7f7d55e92a5fb2b68 Mon Sep 17 00:00:00 2001 From: Shewart Date: Sat, 3 Oct 2026 01:16:18 +0200 Subject: [PATCH 4/6] feat(preview): scroll layout, and room for examples on phones Pagination, toolbars and OTP rows are wider than a phone and spilled past the preview frame. razor:preview scroll / Layout="scroll" lets such an example scroll inside the frame (opt-in, since a scroll box clips popovers). On phones the frame's side padding drops to 0.75rem, and centring uses safe center so a too-wide example starts at the left edge instead of losing both sides. --- .../Content/ComponentPreview.razor | 2 +- src/ShellDocs.Components/Content/DemoPreview.razor | 2 +- src/ShellDocs.Components/Content/PreviewFrame.razor | 10 ++++++++-- .../Content/PreviewFrame.razor.css | 10 ++++++++++ src/ShellDocs.Markdown/RenderedDocument.cs | 2 +- src/ShellDocs.Markdown/SlotExtractor.cs | 6 ++++-- tests/ShellDocs.Tests/PreviewFidelityTests.cs | 8 +++++++- 7 files changed, 32 insertions(+), 8 deletions(-) diff --git a/src/ShellDocs.Components/Content/ComponentPreview.razor b/src/ShellDocs.Components/Content/ComponentPreview.razor index d41e5c3..c2bd4ef 100644 --- a/src/ShellDocs.Components/Content/ComponentPreview.razor +++ b/src/ShellDocs.Components/Content/ComponentPreview.razor @@ -19,7 +19,7 @@ [Parameter] public RenderFragment? ChildContent { get; set; } // Raw child markup from SlotRenderer, used to rebuild the source view. [Parameter] public string? ChildContentSource { get; set; } - // "center" (default) or "stretch"; see PreviewFrame. + // "center" (default), "stretch" or "scroll"; see PreviewFrame. [Parameter] public string? Layout { get; set; } [Parameter(CaptureUnmatchedValues = true)] public IReadOnlyDictionary? ExtraProps { get; set; } diff --git a/src/ShellDocs.Components/Content/DemoPreview.razor b/src/ShellDocs.Components/Content/DemoPreview.razor index cad06ad..0bf7264 100644 --- a/src/ShellDocs.Components/Content/DemoPreview.razor +++ b/src/ShellDocs.Components/Content/DemoPreview.razor @@ -18,7 +18,7 @@ [Parameter] public string? Title { get; set; } // Anchor id; defaults to demo-{component-slug}. Set it when a page shows the same demo twice. [Parameter] public string? Id { get; set; } - // "center" (default) or "stretch"; see PreviewFrame. + // "center" (default), "stretch" or "scroll"; see PreviewFrame. [Parameter] public string? Layout { get; set; } private RenderFragment? _content; diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor b/src/ShellDocs.Components/Content/PreviewFrame.razor index c7df446..6674748 100644 --- a/src/ShellDocs.Components/Content/PreviewFrame.razor +++ b/src/ShellDocs.Components/Content/PreviewFrame.razor @@ -99,7 +99,8 @@ [Parameter] public string? Error { get; set; } [Parameter] public string ErrorTitle { get; set; } = "razor:preview error"; // "center" (default) centres the example; "stretch" lets block-level - // components (charts, inputs, tables) fill the frame's width. + // components (charts, inputs, tables) fill the frame's width; "scroll" lets an + // example wider than the frame (pagination, toolbars) scroll inside it. [Parameter] public string? Layout { get; set; } // Must be deterministic: it's the anchor, and how shelldocs.js restores the @@ -121,7 +122,12 @@ protected override void OnParametersSet() { - _layout = string.Equals(Layout ?? Preview?.Layout, "stretch", StringComparison.OrdinalIgnoreCase) ? "stretch" : "center"; + _layout = (Layout ?? Preview?.Layout)?.ToLowerInvariant() switch + { + "stretch" => "stretch", + "scroll" => "scroll", + _ => "center", + }; var path = DocsVersionResolver.PathOf(Nav); _openHref = string.IsNullOrEmpty(Id) ? path : $"{path}#{Id}"; diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor.css b/src/ShellDocs.Components/Content/PreviewFrame.razor.css index 60a5488..30a0710 100644 --- a/src/ShellDocs.Components/Content/PreviewFrame.razor.css +++ b/src/ShellDocs.Components/Content/PreviewFrame.razor.css @@ -18,6 +18,8 @@ display: flex; align-items: center; justify-content: center; + /* An example wider than the frame starts at the left edge instead of losing both sides. */ + justify-content: safe center; gap: 1rem; flex-wrap: wrap; min-height: 12rem; @@ -30,6 +32,12 @@ } /* Stretch: one column, children take the frame's width. */ +/* Scroll: an example wider than the frame scrolls inside it instead of spilling + past it. A scroll box clips absolutely positioned popovers, so it's opt-in. */ +.preview-render[data-layout="scroll"] { + overflow-x: auto; +} + .preview-render[data-layout="stretch"] { flex-direction: column; align-items: stretch; @@ -231,4 +239,6 @@ @media (max-width: 480px) { .preview-tab span { display: none; } + /* Phones: give the example the width; 1.5rem a side leaves little room for an OTP row. */ + .preview-render { padding: 1.5rem 0.75rem; min-height: 10rem; } } diff --git a/src/ShellDocs.Markdown/RenderedDocument.cs b/src/ShellDocs.Markdown/RenderedDocument.cs index 4e5109d..b10d658 100644 --- a/src/ShellDocs.Markdown/RenderedDocument.cs +++ b/src/ShellDocs.Markdown/RenderedDocument.cs @@ -18,7 +18,7 @@ public record ComponentSlot( // Nodes is the whole fence in order and is what PreviewFrame renders; the other // fields describe the first registered component (or the first unknown tag on Error). -// Layout comes from the fence info string (```razor:preview stretch). +// Layout comes from the fence info string (```razor:preview stretch / scroll). public record PreviewSlot( string Id, Type? ComponentType, diff --git a/src/ShellDocs.Markdown/SlotExtractor.cs b/src/ShellDocs.Markdown/SlotExtractor.cs index 2a2a122..dc1d20a 100644 --- a/src/ShellDocs.Markdown/SlotExtractor.cs +++ b/src/ShellDocs.Markdown/SlotExtractor.cs @@ -129,11 +129,13 @@ or Markdig reads the remaining lines as an indented code block. */ return result.ToString(); } - // `razor:preview stretch` lets block-level examples fill the frame. + // `razor:preview stretch` lets block-level examples fill the frame; `scroll` lets wide ones scroll. private static string? PreviewLayout(string lang) { var words = lang["razor:preview".Length..].Split(' ', StringSplitOptions.RemoveEmptyEntries); - return words.Contains("stretch", StringComparer.OrdinalIgnoreCase) ? "stretch" : null; + if (words.Contains("stretch", StringComparer.OrdinalIgnoreCase)) return "stretch"; + if (words.Contains("scroll", StringComparer.OrdinalIgnoreCase)) return "scroll"; + return null; } private PreviewSlot? TryBuildPreviewSlot(string code, List warnings, string? layout) diff --git a/tests/ShellDocs.Tests/PreviewFidelityTests.cs b/tests/ShellDocs.Tests/PreviewFidelityTests.cs index af44422..d69360b 100644 --- a/tests/ShellDocs.Tests/PreviewFidelityTests.cs +++ b/tests/ShellDocs.Tests/PreviewFidelityTests.cs @@ -84,7 +84,7 @@ public async Task ComponentPreview_ChildContent_IsParsedAsRazor() } [Fact] - public async Task PreviewLayout_DefaultsToCenter_StretchFromFenceOrParameter() + public async Task PreviewLayout_DefaultsToCenter_StretchOrScrollFromFenceOrParameter() { var centered = await Render("```razor:preview\n\n```"); Assert.Contains("data-layout=\"center\"", centered); @@ -94,6 +94,12 @@ public async Task PreviewLayout_DefaultsToCenter_StretchFromFenceOrParameter() var component = await Harness().RenderAsync(new() { ["Component"] = "Button", ["Layout"] = "stretch" }); Assert.Contains("data-layout=\"stretch\"", component); + + var scrolled = await Render("```razor:preview scroll\n\n```"); + Assert.Contains("data-layout=\"scroll\"", scrolled); + + var unknown = await Harness().RenderAsync(new() { ["Component"] = "Button", ["Layout"] = "sideways" }); + Assert.Contains("data-layout=\"center\"", unknown); } [Fact] From d95912d00f8a9872d4e8995a40920a764fe4f7f8 Mon Sep 17 00:00:00 2001 From: Shewart Date: Sat, 3 Oct 2026 01:16:19 +0200 Subject: [PATCH 5/6] docs: scroll preview layout --- CHANGELOG.md | 8 ++++++++ README.md | 2 +- docs/ARCHITECTURE.md | 2 +- .../content/docs/components/component-preview.md | 2 +- .../ShellDocs.Preview/content/docs/markdown-syntax.md | 2 +- 5 files changed, 12 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b5dbe1..c3f5161 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht ## [Unreleased] +### Added + +- **`scroll` preview layout.** `razor:preview scroll`, or `Layout="scroll"` on `` / ``, lets an example wider than the frame (pagination, toolbars, OTP inputs) scroll inside it on small screens instead of spilling past the frame. Opt-in, since a scroll box clips popovers. + +### Changed + +- On phones the preview frame's side padding drops from 1.5rem to 0.75rem, and centring uses `safe center`, so an example that's still too wide starts at the left edge instead of losing both sides. + ### Fixed - **Sidebar listed a folder's `index.md` twice**: once as the section label and again as a page with the same title. The label now links to the index page (highlighted when it's the current page) and the page isn't repeated; in collapsible sections the chevron is its own toggle button. diff --git a/README.md b/README.md index 9a9021a..ddc4861 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ o.AddRedirect("/docs/v0.3.0", "/docs/v0.3"); // also /docs/v0.3.0/x → /docs/ - **Child content is Razor.** Component bodies inside a fence are parsed like the fence itself, so `
…
` keeps its structure and nothing is wrapped in `

`. - **Page typography stays out.** Preview frames are `not-prose`, so prose margins, list padding and link underlines don't reach your components. - **Generic components work.** Set the type argument as Razor does: ``, ``. Libraries' generic components are registered under their bare name. -- **Centred or stretched.** Examples are centred; `razor:preview stretch` (or `Layout="stretch"` on `` / ``) lets charts, inputs and tables fill the frame. +- **Centred, stretched or scrolling.** Examples are centred; `razor:preview stretch` (or `Layout="stretch"` on `` / ``) lets charts, inputs and tables fill the frame, and `scroll` lets an example wider than a phone screen (pagination, toolbars, OTP inputs) scroll inside the frame. A scrolling frame clips popovers, so leave it off examples with dropdowns. - **Razor-shaped attribute values work:** `Variant="ButtonVariant.Destructive"`, `@ButtonVariant.Destructive`, `@true`, `@42`, `[Flags]` values as `Bold | Italic`. - **Attributes a static preview can't evaluate are skipped, not fatal:** `OnClick="HandleClick"`, `@onclick`, `@bind-*`, `@ref`, non-primitive parameter types, unparseable values. Each logs a warning and the component still renders. - **Inline code stays code.** `` `