feat: versioned docs, multi-sibling previews, DemoPreview, ShellIcons - #27
Merged
Merged
Conversation
- Drop section banners, step-by-step narration, and comments that restate the code. - Keep and tighten the "why" notes: static-host constraints, Markdig/MSBuild gotchas, security caveats, ordering rules. - Remove stale references (Prism, removed methods, old branch names).
- UrlPath.Normalize / IsUnder / RelativeTo / Combine — "/docs/v0.30" is not under "/docs/v0.3"; dotted segments stay intact. - NavigationGraph.GetPrevNext(node, inScope) skips out-of-scope neighbours. - NavigationGraph.FindFolder(url) finds the section built from a content folder (hidden folders included). - NavigationGraph.FirstPageUnder(prefix).
…version-scoped chrome
- ShellDocsOptions.AddVersion(id, label, rootUrl, description, latest) + DocsVersion record.
- DocsVersionResolver: current version (containing → latest → first), scoped sidebar nodes, version/package hrefs, search filter, prev/next scope.
- <VersionSelector />: under PackageSelector in DocsSidebar (mobile drawer included) and in DocsHeader for TopNav. Plain hrefs: same page → same package → first page of the target version.
- "{version}" token in AddPackage root URLs; package matching is segment-aware on resolved URLs.
- Sidebar, prev/next, search and breadcrumb stay inside the current version.
- shelldocs.js: shared dropdown delegation for .pkg/.ver, Escape and option-click close.
- Search recalculates via @Bind:after (no longer one keystroke behind); aria-selected renders true/false.
…kip uncoercible attributes - razor:preview fences parse into ordered nodes (PreviewSlot.Nodes): sibling components, HTML wrappers and text all render inside the one frame, as real render-tree elements. The unknown-component error panel stays when nothing resolves. - RazorTagScanner: quote- and @( … )-aware tag reader; full attribute names kept, so @bind-Value is no longer misread as Value. - SlotRenderer.Coerce accepts @-prefixed values, Type.Member enums, [Flags] "A | B", numeric suffixes and @null. - BuildParameters never throws: directive attributes, EventCallback/delegate params, unsupported types, bad values and unknown attributes without a catch-all are skipped with a logged warning. Same for ComponentPreview. - Parameter names match case-insensitively, like Blazor.
…r .razor source
- <DemoPreview Component="X" Title="…" /> renders registered component X inside the preview frame; the source tab shows {DemoSourceRoot}/**/X.razor (shallowest match, cached, re-read when the file changes).
- ShellDocsOptions.DemoSourceRoot.
- PreviewFrame gains a content mode (Content / Code / Language / Title / Error / ErrorTitle) and an optional title bar.
- A missing component, root or file renders the red error panel, without echoing server paths.
…view
- Two version folders (content/docs/v2.0, content/docs/v1.9.1) with AddVersion; Core/CLI packages use "/docs/{version}/…".
- Demo Ui/Button with enum params for razor:preview, and Demos/ButtonClickDemo.razor for <DemoPreview>.
- Demo .razor files ship via a None item (the Razor SDK drops them from publish otherwise).
- Add ShellIcons.Blazor 0.1.0-alpha (Lucide-derived typed icon components) to ShellDocs.Components. - Replace inline <svg> icons across chrome, content primitives, layouts and the example pages with typed icons (ChevronDown, Search, Copy, Check, PanelLeft, Sun/Moon, TriangleAlert, …). - SidebarIcons maps titles to icon component types instead of raw path strings. - Icon <svg>s now come from a child component, so scoped CSS targets them through ::deep. - Brand marks (GitHub, X) and consumer-supplied raw icons (DocsPackage.IconPath, NavMenuItem.IconSvg, Card.IconSvg) stay inline; only their defaults use ShellIcons. - Files where Lucide names collide (Heading, Type, TableOfContents) use fully qualified icon tags.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Versioned docs for multi-version sites (the ShellUI docs:
content/docs/v0.3,content/docs/v0.2.1),razor:previewfixes so real component-library previews render, a<DemoPreview>primitive for stateful demos, and icons via ShellIcons. Every chrome interaction follows the 0.1.7 static-host pattern: server-rendered initial state, data attributes, and delegated handlers inshelldocs.js. No@onclickstate.Versions
ShellDocsOptions.AddVersion(id, label, rootUrl, description, latest)→Versions/DocsVersionrecord.DocsVersionResolver: the current version is the one whoseRootUrlis a segment-aware prefix of the path, otherwise the latest, otherwise the first.<VersionSelector />sits under the package selector in the sidebar (mobile drawer included) and in the header for the TopNav layout. It's hidden with fewer than 2 versions. Switching keeps the same page → else the same package → else the version's first page.{version}token inAddPackageroot URLs. Switching packages keeps the version.Previews
razor:previewrenders all top-level siblings (components, HTML wrappers, text) in one frame. The unknown-component error panel is kept.ButtonVariant.Destructive,@ButtonVariant.Destructive,@true,@42,[Flags]values asA | B.OnClick="Handler",@bind-*,@ref,@onclick, unsupported types, bad values) are skipped with a warning; the page no longer crashes.<DemoPreview Component="X" Title="…" />+DemoSourceRoot: renders a registered demo component, with its.razorfile shown as source.Icons
ShellIcons.Blazor0.1.0-alpha. Brand marks and consumer-supplied raw icons are unchanged; scoped icon CSS now uses::deep.Housekeeping
Consumer notes
Noneitem. The Razor SDK drops.razorfiles from publish even withContent Update:<None Include="Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />/docs/{*Path:nonfile}won't match a bare/docs/v0.2.1; pages under it are fine. The selectors only link to a version root when it has anindex.md.Testing
dotnet build shelldocs.slnx: 0 warnings.dotnet test: 242 passed; every commit builds and passes on its own.