diff --git a/CHANGELOG.md b/CHANGELOG.md index aca6e32..57ca380 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,24 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht ## [Unreleased] +## [0.1.11-alpha] — 2026-10-03 + +Polish from moving the ShellUI docs onto 0.1.10: the sidebar no longer repeats a folder's index page, and previews and tables behave on phones. + +### 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. +- **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. @@ -342,7 +360,8 @@ Published to NuGet: - `` is hand-authored today; XML-doc auto-generation ships in `ShellDocs.Xml` (Phase 4) - No `` opt-out — currently hides when the trail has ≤ 1 node, otherwise always renders -[Unreleased]: https://github.com/shellui-dev/shelldocs/compare/v0.1.10-alpha...HEAD +[Unreleased]: https://github.com/shellui-dev/shelldocs/compare/v0.1.11-alpha...HEAD +[0.1.11-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.11-alpha [0.1.10-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.10-alpha [0.1.9-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.9-alpha [0.1.8-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.8-alpha diff --git a/Directory.Build.props b/Directory.Build.props index bbb10c5..887c6ad 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -17,7 +17,7 @@ - 0.1.10-alpha + 0.1.11-alpha ShellUI ShellUI Copyright © 2026 ShellUI 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.** `` ` + + } + 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/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.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/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/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); + } +} 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] 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); + } +}