mosaic-controls

name	mosaic-controls
description	Overview of all Mosaic UI for WPF controls. Use when: implementing a control, looking up properties/events, asking what controls exist, choosing the right control for a UI requirement.
argument-hint	Optional: name of a specific control to focus on (e.g. 'ToggleSwitch', 'AutoCompleteBox')

Mosaic UI for WPF — Control Overview

Mosaic UI for WPF (Mosaic.UI.Wpf) is a lookless, theme-aware WPF control library. Controls are consumed via the canonical XML namespace:

xmlns:mosaic="http://schemas.apexgate.net/wpf/mosaic-ui"

or the CLR form:

xmlns:mosaic="clr-namespace:Mosaic.UI.Wpf.Controls;assembly=Mosaic.UI.Wpf"

The VT52Terminal control requires the sub-namespace:

xmlns:vt52="clr-namespace:Mosaic.UI.Wpf.Controls.VT52Terminal;assembly=Mosaic.UI.Wpf"

The waveform visualizer controls are also mapped to the canonical URI, or can be referenced with:

xmlns:waveform="clr-namespace:Mosaic.UI.Wpf.Controls.WaveformVisualizer;assembly=Mosaic.UI.Wpf"

AvalonDock is shipped as a separate package/project and uses its own XAML URI:

xmlns:ad="https://github.com/blakepell/MosaicUIWpf"

For theme tokens (brushes, font sizes, etc.), declare:

xmlns:themes="http://schemas.apexgate.net/wpf/mosaic-ui"

and reference tokens like {DynamicResource {x:Static themes:MosaicTheme.ControlTextForegroundBrush}}.

---

Control Inventory

For detailed property/event/example documentation, read the individual file listed in the Details column.

Control	Base Class	Category	Description	Details
AccentButton	Button	Input	Button with built-in accent color variants	AccentButton.md
AdaptiveImage	Image	Media	Pixel-level HSL theme adaptation for images (light/dark mode)	AdaptiveImage.md
AsteriskTextBlock	Control	Display	Displays masked text with a configurable mask character (default: ●)	AsteriskTextBlock.md
AudioPlayer	Control	Media	Audio transport control with playlist, seek slider, playback events, and MediaPlayer backing	AudioPlayer.md
AudioPlayerSpectrumAnalyzer	FrameworkElement	Media	WASAPI loopback spectrum analyzer intended to pair with AudioPlayer	AudioPlayer.md
AutoCompleteBox	Control	Input	Searchable autocomplete combo box with async provider support	AutoCompleteBox.md
Avatar	Button	Display	User avatar with image source or fallback initials	Avatar.md
Badge	ContentControl	Display	Small inline status/count badge	Badge.md
BindablePasswordBox	ContentControl	Input	Password field with a bindable Password string property	BindablePasswordBox.md
ContentPanel	ContentControl	Layout	Themed content container with header, footer, separator, and corner styling	ContentPanel.md
ChatThread	UserControl	Data	Chat conversation view with sent/received message templates	ChatThread.md
CheckBoxList	ListBox	Input	Multi-select list that shows checkboxes beside each item	CheckBoxList.md
ClipBorder	Border	Layout	Border that clips child content to its CornerRadius	ClipBorder.md
ColorPicker	UserControl	Input	Visual color picker with hex input and preset colors	ColorPicker.md
DatePicker	Control	Input	Mosaic date picker with popup month calendar and nullable selected date	DatePicker.md
DocumentContainer	TabControl	Navigation	Closable, reorderable document tabs with active-document tracking	DocumentContainer.md
EditableTextBlock	Control	Input	Inline editable text that toggles between view/edit mode	EditableTextBlock.md
FavoriteCheckBox	CheckBox	Input	Symbol-based favorite/star toggle with configurable brushes	FavoriteCheckBox.md
FileDropper	Control	Input	File drag-and-drop target with file type validation and command/event hooks	FileDropper.md
Files	Control	Data	Directory file list with shell icons, sorting, selection, watcher refresh, and activation event	Files.md
FlipPanel	ContentControl	Display	Animated flip panel with front and back content faces	FlipPanel.md
GravatarImage	Image	Media	Loads and displays a Gravatar avatar from an email address	GravatarImage.md
HexColorTextBox	ComboBox	Input	Editable hex color field (#RGB, #RRGGBB, #AARRGGBB) with shade drop-down	HexColorTextBox.md
Hyperlink	ContentControl	Navigation	Clickable link that opens a URI or executes an ICommand	Hyperlink.md
InertiaScrollViewer	ScrollViewer	Layout	ScrollViewer with animated inertia/momentum on mouse wheel	InertiaScrollViewer.md
InfoCard	ContentControl	Display	Card with animated accent bar, title, header, body, and footer	InfoCard.md
InputWaveformVisualizer	WaveformVisualizerBase	Media	Live waveform from a selectable Windows audio input device	WaveformVisualizer.md
LabeledSeparator	ContentControl	Display	Horizontal separator with an embedded text label	LabeledSeparator.md
LoopbackWaveformVisualizer	WaveformVisualizerBase	Media	Live waveform from the default Windows audio render device via WASAPI loopback	WaveformVisualizer.md
MarkdownEditor	UserControl	Input	Markdown editor built on SyntaxEditor with toolbar, snippets, save helpers, and preview/copy actions	MarkdownEditor.md
MarkdownViewer	Control	Display	WPF-native Markdown renderer backed by a copyable FlowDocument/RichTextBox	MarkdownViewer.md
MessageBox	static class	Dialog	Themed drop-in replacement for System.Windows.MessageBox Show overloads	MessageBox.md
NumericTextBox	TextBox	Input	Text box that accepts only numeric input with configurable decimal places	NumericTextBox.md
ProgressRing	Control	Display	Indeterminate animated ring/spinner controlled by IsActive	ProgressRing.md
PropertyGrid	Control	Data	Object property inspector using TypeDescriptor with category grouping	PropertyGrid.md
RadialProgressBar	ProgressBar	Display	Circular progress bar with fill, pie, shape, and indeterminate modes	RadialProgressBar.md
RelativePanel	Panel	Layout	Arranges children relative to each other via attached properties	RelativePanel.md
ScalingTextBlock	TextBlock	Display	TextBlock that automatically lowers font size to fit available width	ScalingTextBlock.md
SearchBox	TextBox	Input	Text box with watermark, clear button, and SearchExecuted event	SearchBox.md
SettingsItem	ContentControl	Display	Settings row with icon, title, description, and slot for a control	SettingsItem.md
ShadowPanel	ContentControl	Layout	Content container with configurable drop shadow effect	ShadowPanel.md
ShadowTextBlock	TextBlock	Display	TextBlock with automatically applied drop shadow	ShadowTextBlock.md
Shield	Control	Display	GitHub-style shield/badge with label and value sections	Shield.md
SideMenu	UserControl	Navigation	Collapsible navigation side menu with search and drag-drop reorder	SideMenu.md
SimpleStackPanel	Panel	Layout	Efficient stack panel with uniform Spacing between children	SimpleStackPanel.md
SmallPanel	Panel	Layout	Overlay panel that stacks children in the same bounds	SmallPanel.md
SplitButton	ContentControl	Input	Button with a separate drop-down chevron that opens a ContextMenu	SplitButton.md
SplitPanel	Control	Layout	Two-pane resizable container with a draggable GridSplitter and bindable split ratio	SplitPanel.md
StopwatchDisplay	ContentControl	Display	Real-time stopwatch with Start/Stop/Reset methods	StopwatchDisplay.md
StringListEditor	ContentControl	Input	Editable list of strings with add/remove and duplicate/validation support	StringListEditor.md
SymbolRating	Control	Input	Star/symbol rating control with hover preview and deselect	SymbolRating.md
SyntaxEditor	TextEditor	Input	AvalonEdit-based code editor with Mosaic themes, bundled syntax highlighting, search, JSON commands, and line editing commands	SyntaxEditor.md
TabControl	TabControl	Navigation	Mosaic-themed tab control with top/bottom active indicator	TabControl.md
TagBox	Control	Input	Token/tag entry box with removable chips, duplicate control, and cancellable change events	TagBox.md
ToggleButton	ToggleButton	Input	Mosaic-themed toggle button with checked/unchecked background	ToggleButton.md
ToggleSwitch	Control	Input	Mobile-style on/off toggle switch with custom colors and MVVM	ToggleSwitch.md
TwoPaneView	Control	Layout	Adaptive two-pane layout (side-by-side or stacked)	TwoPaneView.md
ValidationSummaryPanel	ItemsControl	Data	Validation error collector and display panel with auto-hide	ValidationSummaryPanel.md
VersionTextBlock	TextBlock	Display	Displays version string from a configurable assembly source	VersionTextBlock.md
VT52Terminal	TextEditor	Terminal	Full ANSI/VT100/VT220/xterm terminal emulator (AvalonEdit-based)	VT52Terminal.md
WindowTitleBar	UserControl	Windowing	Custom Mosaic window title bar with min/max/close and custom content slots	WindowTitleBar.md

---

Behaviors

Behaviors live in the Mosaic.UI.Wpf.Behaviors namespace and add functionality to existing WPF controls without subclassing them — reach for one before authoring a new control. Most are Behavior<T> (attached inside <i:Interaction.Behaviors>); GridViewSortBehavior, WindowChromeBehavior, and BrushModifier are attached-property helpers (applied as behaviors:Foo.Bar="..."). The namespace is also mapped to the canonical Mosaic URI, so mosaic:-prefixed usage works too. See Behaviors.md for full property/usage details.

xmlns:behaviors="clr-namespace:Mosaic.UI.Wpf.Behaviors;assembly=Mosaic.UI.Wpf"
xmlns:i="http://schemas.microsoft.com/xaml/behaviors"

Behavior	Attaches to	Description	Details
FocusBehavior	Control	Focuses the control when it loads	Behaviors.md
BlinkingBehavior	FrameworkElement	Blinks an element by animating its opacity	Behaviors.md
FrameworkElementZoomFontSizeOnMouseWheelBehavior	FrameworkElement	Ctrl+MouseWheel font-size zoom (clamped min/max)	Behaviors.md
BrushModifier	Control/Border/Panel	Lightens/darkens the background brush by an HSL percentage	Behaviors.md
TextBoxCopyBehavior	Button	Copies a target TextBox's (selected) text to the clipboard on click	Behaviors.md
TextBoxClearTextOnEscapeBehavior	TextBoxBase	Clears the text box when Escape is pressed	Behaviors.md
BlockCaretBehavior	TextBox	Terminal-style full-width block caret	Behaviors.md
ItemsControlAutoScrollBehavior	ItemsControl	Auto-scrolls to the newest item when the collection changes	Behaviors.md
ItemsControlFilterBehavior	TextBox	Debounced text filter over a target ItemsControl	Behaviors.md
DataGridFilterBehavior	TextBox	Debounced full-text filter over a target DataGrid	Behaviors.md
DataGridLastColumnFillBehavior	DataGrid	Stretches the last column to fill remaining width	Behaviors.md
GridViewLastColumnFillBehavior	ListView	Auto-sizes the last GridView column	Behaviors.md
GridViewSortBehavior	ListView/GridViewColumn	Click-header sorting for a GridView	Behaviors.md
ListViewDeleteBehavior	ListView	Deletes selected items on the Delete key (optional confirm)	Behaviors.md
OpenContextMenuBehavior	ButtonBase	Opens the button's ContextMenu on click	Behaviors.md
OpenWindowBehavior	ButtonBase/MenuItem	Opens a Window of a given type on click (modal/modeless)	Behaviors.md
CloseWindowOnEscapeBehavior	Window	Closes the window on Escape	Behaviors.md
WindowChromeBehavior	Window	Custom borderless chrome, themed brushes, rounded corners	Behaviors.md
AvalonTextEditorBindingBehavior	AvalonEdit TextEditor	Bindable text, selection, selected text, and caret offset	AvalonEditBehaviors.md
AvalonEditPropertiesBehavior	AvalonEdit TextEditor	Binds caret brush and hyperlink enablement	AvalonEditBehaviors.md
AvalonEditVtTerminalBehavior	AvalonEdit TextEditor	Applies a retro VT/CRT visual skin	AvalonEditBehaviors.md
AvalonEditCopyBehavior	Button	Copies a target TextEditor's (selected) text to the clipboard on click	AvalonEditBehaviors.md

File name ≠ class name for four behaviors: AvalonEditBindingBehavior.cs → AvalonTextEditorBindingBehavior, TextBoxClearOnEscapeBehavior.cs → TextBoxClearTextOnEscapeBehavior, CloseWindowOnEscape.cs → CloseWindowOnEscapeBehavior, ButtonOpenContextMenu.cs → OpenContextMenuBehavior. Use the class name in XAML.

Integration Packages

These are not main-assembly controls, but are part of the Mosaic usage surface and have demo examples.

Item	Kind	Namespace / URI	Description	Details
DockingManager / MosaicTheme	Separate package/project	https://github.com/blakepell/MosaicUIWpf	Mosaic-themed AvalonDock fork/integration for IDE-style document and tool-window docking	AvalonDock.md

Support Controls

These public controls exist for native style dictionaries and low-level template composition. Prefer the higher-level controls in the main inventory unless you are editing Mosaic's native styles or need this exact primitive.

Control	Base Class	Primary Use	Details
SliderRepeatButton	RepeatButton	Slider track repeat buttons with corner orientation metadata	SupportControls.md
SystemDropShadowChrome	Decorator	WPF-style chrome shadow rendering for popups and native templates	SupportControls.md
WDScrollViewer	ScrollViewer	Native TreeView template scrolling with optional wheel animation	SupportControls.md

---

Theme Tokens

Reference theme brushes via DynamicResource using MosaicTheme static keys:

xmlns:themes="http://schemas.apexgate.net/wpf/mosaic-ui"

<!-- Foreground / background -->
Foreground="{DynamicResource {x:Static themes:MosaicTheme.ControlTextForegroundBrush}}"
Background="{DynamicResource {x:Static themes:MosaicTheme.ControlBackgroundBrush}}"

<!-- Border -->
BorderBrush="{DynamicResource {x:Static themes:MosaicTheme.ControlBorderBrush}}"

<!-- Accent / status -->
Fill="{DynamicResource {x:Static themes:MosaicTheme.AccentBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.SuccessBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.WarningBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.ErrorBrush}}"
Fill="{DynamicResource {x:Static themes:MosaicTheme.InfoBrush}}"

<!-- Font sizes -->
FontSize="{DynamicResource {x:Static themes:MosaicTheme.FontSizeSmall}}"
FontSize="{DynamicResource {x:Static themes:MosaicTheme.FontSizeMedium}}"
FontSize="{DynamicResource {x:Static themes:MosaicTheme.FontSizeLarge}}"

---

App Setup

Consumer apps wire Mosaic by:

1. Using MosaicApp<TSettings, TViewModel> as the Application base in App.xaml.
2. Merging a ThemeManager into application resources.
3. Placing mosaic:WindowTitleBar + WindowChromeBehavior in MainWindow.

See the mosaic-setup-project skill for the full wiring procedure.

---

Quick Tips

• Always use DynamicResource for theme tokens — switching themes requires live updates.
• CustomControls (most controls) support re-templating; UserControl-based controls (ColorPicker, ChatThread, MarkdownEditor, SideMenu, WindowTitleBar) do not.
• VT52Terminal requires the separate sub-namespace Mosaic.UI.Wpf.Controls.VT52Terminal.
• InputWaveformVisualizer and LoopbackWaveformVisualizer live in Mosaic.UI.Wpf.Controls.WaveformVisualizer, but are mapped to the canonical Mosaic XAML URI.
• AvalonDock lives in Mosaic.UI.Wpf.AvalonDock / package MosaicUIWpf.AvalonDock and uses xmlns:ad="https://github.com/blakepell/MosaicUIWpf".
• AdaptiveImage requires ThemeManager in the DI container (AppServices).
• PropertyGrid reads [Category], [Description], and [PropertyGridAttribute] attributes on the target object.
• SideMenu uses ContentTypeIsSingleton + AppServices DI for singleton view navigation in the demo.
• Public support controls such as WDScrollViewer, SliderRepeatButton, and SystemDropShadowChrome are primarily used by native theme dictionaries; see SupportControls.md.