# Catalog sample format Every page in the ControlCatalog uses one of two shapes. Both are built from the same controls and the same palette, so they read as one app. ## Choosing a tier Write a **sectioned-scroll** page by default: one scrolling page whose examples are all visible at once. Reach for a **gallery** only when one of these is true: - a sample needs the whole pane to be usable (a navigation stack, a drawer, a large table, a GL surface, a gesture surface, a full app showcase); - two samples on one page would fight over something scoped to the window: focus and tab order, access keys, drop targets, pointer capture, the clipboard; - building every sample at once is measurably expensive; - there are eight or more substantial samples, each with its own options. When the lesson is *comparison* ("here are the six Stretch modes"), stay sectioned even at high counts. A gallery replaces adjacency with a memory test. ## Sectioned-scroll page ```xml ... ``` The code-behind derives from `SamplePage`. The page scrolls by default. A page whose content scrolls on its own (a `ListBox`, a `DataGrid`) sets `ScrollViewer.VerticalScrollBarVisibility="Disabled"` on the `SamplePage`, so the content gets the page height and scrolls on its own instead of growing to its full extent. Sections are always wrapped in a `SampleGroup` whose `Header` is one of the group names below. This is what makes the two tiers one format: a scrolling page and a gallery show the **same groups in the same order**, and differ only in whether a group's samples are expanded inline or collapsed into cards. `SampleSection` gives you: - `Header` — the example's title. - `Description` — one sentence saying what it shows. - `Content` — the live example, on a stage. - `Options` — controls that configure it. Docked to the right on wide layouts, dropped below the stage under 620px. Leave it unset when there is nothing to configure. - `Code` / `CodeLanguage` — a short snippet, syntax-highlighted, with a copy button. Short ones start open; anything over 12 lines starts collapsed. Use the attribute form for one line and `` with a `CDATA` block for several. Show the lines that matter, not the whole example. Keep rendered lines under about 100 columns, and never put an element and its children on one line — the snippet is teaching markup, so it should look like markup. Wrapped attributes are re-aligned under the first attribute automatically, so you do not need to count spaces. - `Stage` — `Padded` (default), `Flush` for content that paints its own edges, `None` for content that must sit directly on the card. This is the only sanctioned way to change the stage; never set a literal `Background` on it. - `StageMinHeight` — when an example needs room to be understood. - `StageHeight` — a *fixed* stage, for content that is a frame rather than a document: a whole demo app, a `Carousel`, a GL surface, anything rooted in its own `ScrollViewer` or with no natural height. The stage sits inside the page's `ScrollViewer`, so it offers unbounded height and such content would otherwise stretch to its entire scroll extent. Set this on the section and set both `*ContentAlignment`s to `Stretch`; never put a literal `Height` on the example to work around it. ## Gallery page ```xml ``` ```csharp public partial class MyControlPage : SampleGalleryPage { private static readonly SampleInfo[] Demos = { new(SampleGroups.Overview, "First Look", "The minimal demo.", () => new MyControlFirstLookPage()), }; public MyControlPage() { InitializeComponent(); Samples = Demos; } } ``` Sub-samples are `UserControl`s under `Pages//`, named `Page`. The factory runs only when the card is clicked, so a gallery costs nothing until it is used. A sub-sample that throws shows the exception on its own page rather than taking the app down. A card pushes its sample on the host `NavigationPage` rather than on a navigation host of its own, so the shell keeps a single navigation bar: the page title and the drawer toggle on the gallery, the sample title and the back button once a sample is open. The registry must be reachable without constructing the page, so declare it as an `internal static readonly` field (the convention is `Demos`) and pass it when the page is registered in `MainWindowViewModel_PageList`: ```csharp s.Add("Calendar", Icons.Calendar, "A month calendar for selecting dates", CalendarPage.Demos); ``` The drawer search reads the registry without building the page, so it matches a page by its samples ("BlackoutDates" finds Calendar). A page whose samples do not show up in search is usually missing this argument. ## Groups `SampleGroups` defines the order, and the gallery enforces it regardless of the array order: **Overview → Populate → Appearance → Features → Events → Performance → Showcases** Every page gets exactly one Overview sample: the minimal, no-options demo. Leave a group out rather than inventing filler. A group name outside this list is allowed but renders after all of them. Both tiers use these names: a single page wraps its sections in ``, a gallery sets `new(SampleGroups.Appearance, ...)` in its registry. Same vocabulary, same order, two densities. Use the `SampleGroups` constants, never a literal: a misspelled group renders after all known ones with no warning. ## Colours Prefer the theme's own defaults: leave `Background` and `Foreground` unset wherever the control already looks right. Pages have no background of their own, so window transparency shows through; never give one a background. When a colour is needed, use only `Catalog*` keys. They are defined for `Default` and `Dark` in `CustomThemes.xaml` (`CatalogBaseLowColor` in `App.xaml`) and are independent of the theme flavour. Keep this list short: add a key only when several pages need it. | Key | Use | |---|---| | `CatalogCardBackground` / `CatalogCardBorderBrush` | cards | | `CatalogStageBackground` | the area behind a live example, and code snippets | | `CatalogSubtleForeground` | secondary text | | `CatalogAccentBackground` | a tinted accent surface, for text in `CatalogAccentForeground` | | `CatalogAccentForeground` | accent text | | `CatalogBaseLowColor` | hairlines and borders | **Never reference a key starting `SystemControl`, `SystemAccent` or `Theme`.** Those exist in only one of the two theme flavours, so they silently resolve to nothing under the other. A hardcoded hex is acceptable only when the colour *is* the demo (a swatch, a deliberately red shape), and then set the foreground alongside it. Text roles live in `App.xaml`: `sample-description`, `sample-card-title`, `sample-card-description`, `sample-section-description`, `sample-options-title`, `sample-caption`. ## Lifetime Every `Loaded` or `AttachedToVisualTree` subscription in a sample must be symmetric and idempotent. `Loaded` fires on every attach, so a handler that adds items or subscribes must remove or guard on the way out. `DrawerPageEventsPage` is the reference. ## Responsiveness Do not hardcode a width on an options panel or a container; `SampleSection` and `CardGrid` handle reflow. A fixed width on the example itself is fine when the control needs one (a slider track, a numeric box). The same goes for height: if an example grows to fill the page, it has no natural height, and the fix is `StageHeight` on the section, not a `Height` on the example. ## Leave the page cleaner than you found it Converting a page is the moment to remove what it accumulated: - dead code: handlers wired to nothing, fields never read, `x:Name`s nobody references, commented-out blocks; - unused `using` directives, unused XAML namespace prefixes, and resources declared but never referenced; - duplicated markup: the same demo repeated with one property changed belongs in one section with an option, not in five near-identical copies; - a view model used only by this page that has drifted from what the page shows; - files and folders left behind by a sample that no longer exists. Do not delete anything reachable from another page without saying so.