# Component Factory Surface Reference

This page documents the verified public `MASApplicationWindow.Controls` factory surface. It is based on `MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.vb` and the exact partial-file list in `docs/_inventory/component-factory-inventory.md`. Detailed behavior for each returned control is intentionally deferred to the relevant component/system documentation phase.

## Usage rule

For consumer documentation, the primary safe path for adding retained MAS controls is the Application-owned controls facade, for example `window.Controls.AddButton(...)` or `window.Controls.AddDataGrid(...)`. Direct constructors or class-specific `Create` helpers may exist in the code, but they are not promoted as the primary commercial adoption route in this phase.

Controls created through `Add*` factory helpers are tracked as facade-created while they remain hosted by that window. `Remove` and `Clear` are detach-only; use `RemoveAndDispose(control)` or `ClearAndDisposeCreatedControls()` when the window should also dispose factory-created controls during screen teardown. Manually added controls remain consumer-owned.

The factory surface hosts retained direct controls. Use it for bounded page/application controls and batch creation with `PerformUpdate(...)` when needed. Do not model 10k/100k repeated records as direct controls; those scenarios belong to MASDataGrid, MASListView, MASListBox, or another Nexamas UI surface backed by MASVirtualizedItemsSystem.

## Buttons

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddButton | MASButton | Optional text As String = Nothing, Optional configure As Action(Of MASButton) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddSplitButton | MASSplitButton | Optional text As String = Nothing, Optional configure As Action(Of MASSplitButton) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddCheckBox | MASCheckBox | Optional text As String = Nothing, Optional checked As Boolean = False, Optional configure As Action(Of MASCheckBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddRadioButton | MASRadioButton | Optional text As String = Nothing, Optional groupName As String = Nothing, Optional checked As Boolean = False, Optional configure As Action(Of MASRadioButton) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddToggleSwitch | MASToggleSwitch | Optional text As String = Nothing, Optional checked As Boolean = False, Optional configure As Action(Of MASToggleSwitch) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddRating | MASRating | Optional value As Double = 0.0R, Optional maximum As Integer = 5, Optional configure As Action(Of MASRating) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddSegmentedControl | MASSegmentedControl | Optional segments As IEnumerable(Of MASSegmentEntry) = Nothing, Optional configure As Action(Of MASSegmentedControl) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |
| AddSelectorItemList | MASSelectorItemControl | Optional items As IEnumerable(Of MASSelectorItemEntry) = Nothing, Optional configure As Action(Of MASSelectorItemControl) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Buttons.vb |

## Containers

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddSplitView | MASSplitView | Optional title As String = Nothing, Optional configure As Action(Of MASSplitView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddAppLayout | MASAppLayout | Optional title As String = Nothing, Optional configure As Action(Of MASAppLayout) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddGroupBox | MASGroupBox | Optional title As String = Nothing, Optional configure As Action(Of MASGroupBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddExpander | MASExpander | Optional title As String = Nothing, Optional expanded As Boolean = True, Optional configure As Action(Of MASExpander) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddAccordion | MASAccordion | Optional allowMultipleExpanded As Boolean = False, Optional configure As Action(Of MASAccordion) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddStepper | MASStepper | Optional orientation As MASStepperOrientation = MASStepperOrientation.Horizontal, Optional configure As Action(Of MASStepper) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddWizard | MASWizard | Optional orientation As MASStepperOrientation = MASStepperOrientation.Horizontal, Optional configure As Action(Of MASWizard) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddTileBox | MASTileBox | Optional configure As Action(Of MASTileBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddLabel | MASLabel | Optional text As String = Nothing, Optional configure As Action(Of MASLabel) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |
| AddTitle | MASTitle | text As String, Optional configure As Action(Of MASTitle) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Containers.vb |

## Data

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddFilterBuilder | MASFilterBuilder | Optional rules As IEnumerable(Of MASFilterRule) = Nothing, Optional configure As Action(Of MASFilterBuilder) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddAppliedFiltersBar | MASAppliedFiltersBar | Optional title As String = Nothing, Optional savedViewName As String = Nothing, Optional configure As Action(Of MASAppliedFiltersBar) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddKanbanBoard | MASKanbanBoard | Optional title As String = Nothing, Optional configure As Action(Of MASKanbanBoard) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddAgendaView | MASAgendaView | Optional title As String = Nothing, Optional day As Nullable(Of Date) = Nothing, Optional configure As Action(Of MASAgendaView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddTreeGrid | MASTreeGrid | Optional title As String = Nothing, Optional configure As Action(Of MASTreeGrid) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddPivotTable | MASPivotTable | Optional title As String = Nothing, Optional configure As Action(Of MASPivotTable) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddDashboardGrid | MASDashboardGrid | Optional title As String = Nothing, Optional configure As Action(Of MASDashboardGrid) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddMasterDetailView | MASMasterDetailView | Optional title As String = Nothing, Optional configure As Action(Of MASMasterDetailView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddChartLegend | MASChartLegend | Optional title As String = Nothing, Optional configure As Action(Of MASChartLegend) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddDataGrid | MASDataGrid | Optional configure As Action(Of MASDataGrid) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddDataForm | MASDataForm | Optional configure As Action(Of MASFormBuilder) = Nothing, Optional configureControl As Action(Of MASDataForm) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddChart | MASChart | Optional configure As Action(Of MASChart) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddListBox | MASListBox | Optional items As IEnumerable(Of String) = Nothing, Optional configure As Action(Of MASListBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddListView | MASListView | Optional textItems As IEnumerable(Of String) = Nothing, Optional configure As Action(Of MASListView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |
| AddTreeView | MASTreeView | Optional configure As Action(Of MASTreeView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Data.vb |

## Feedback

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddValidationMessage | MASValidationMessage | Optional text As String = Nothing, Optional state As MASTextValidationState = MASTextValidationState.Information, Optional configure As Action(Of MASValidationMessage) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddFormValidationSummary | MASFormValidationSummary | Optional title As String = Nothing, Optional configure As Action(Of MASFormValidationSummary) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddCallout | MASCallout | Optional title As String = Nothing, Optional text As String = Nothing, Optional configure As Action(Of MASCallout) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddBadge | MASBadge | Optional text As String = Nothing, Optional tone As MASToastTone = MASToastTone.Neutral, Optional configure As Action(Of MASBadge) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddStatusBanner | MASStatusBanner | Optional title As String = Nothing, Optional message As String = Nothing, Optional tone As MASToastTone = MASToastTone.Info, Optional configure As Action(Of MASStatusBanner) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddNotificationPanel | MASNotificationPanel | Optional title As String = Nothing, Optional configure As Action(Of MASNotificationPanel) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddEmptyState | MASEmptyState | Optional title As String = Nothing, Optional description As String = Nothing, Optional configure As Action(Of MASEmptyState) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddLoadingSkeleton | MASLoadingSkeleton | Optional rowCount As Integer = 4, Optional configure As Action(Of MASLoadingSkeleton) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddAvatar | MASAvatar | Optional displayName As String = Nothing, Optional initials As String = Nothing, Optional configure As Action(Of MASAvatar) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddAvatarGroup | MASAvatarGroup | Optional avatars As IEnumerable(Of MASAvatar) = Nothing, Optional configure As Action(Of MASAvatarGroup) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddMetricCard | MASMetricCard | Optional title As String = Nothing, Optional valueText As String = Nothing, Optional configure As Action(Of MASMetricCard) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddTimeline | MASTimeline | Optional title As String = Nothing, Optional description As String = Nothing, Optional configure As Action(Of MASTimeline) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddOperationProgressBox | MASOperationProgressBox | Optional titleText As String = Nothing, Optional statusText As String = Nothing, Optional configure As Action(Of MASOperationProgressBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |
| AddProgressBar | MASProgressBar | Optional configure As Action(Of MASProgressBar) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Feedback.vb |

## Inputs

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddComboBox | MASComboBox | Optional items As IEnumerable(Of String) = Nothing, Optional selectedIndex As Integer = -1, Optional configure As Action(Of MASComboBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddDatePicker | MASDatePicker | Optional selectedDate As Nullable(Of Date) = Nothing, Optional configure As Action(Of MASDatePicker) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddDateRangePicker | MASDateRangePicker | Optional startDate As Nullable(Of Date) = Nothing, Optional endDate As Nullable(Of Date) = Nothing, Optional configure As Action(Of MASDateRangePicker) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddTimePicker | MASTimePicker | Optional selectedTime As Nullable(Of TimeSpan) = Nothing, Optional configure As Action(Of MASTimePicker) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddTagInput | MASTagInput | Optional tags As IEnumerable(Of String) = Nothing, Optional configure As Action(Of MASTagInput) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddSlider | MASSlider | Optional minimum As Double = 0.0, Optional maximum As Double = 100.0, Optional value As Double = 0.0, Optional configure As Action(Of MASSlider) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddTextBox | MASTextBox | Optional text As String = Nothing, Optional configure As Action(Of MASTextBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddMultilineTextBox | MASMultilineTextBox | Optional text As String = Nothing, Optional configure As Action(Of MASMultilineTextBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddSearchTextBox | MASSearchTextBox | Optional text As String = Nothing, Optional configure As Action(Of MASSearchTextBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddPasswordTextBox | MASPasswordTextBox | Optional text As String = Nothing, Optional configure As Action(Of MASPasswordTextBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddNumericTextBox | MASNumericTextBox | Optional configure As Action(Of MASNumericTextBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddPathTextBox | MASPathTextBox | Optional path As String = Nothing, Optional configure As Action(Of MASPathTextBox) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddColorPicker | MASColorPicker | Optional configure As Action(Of MASColorPicker) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |
| AddPropertyGrid | MASPropertyGrid | Optional source As Object = Nothing, Optional configure As Action(Of MASPropertyGrid) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Inputs.vb |

## Media

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddImageViewer | MASImageViewer | Optional title As String = Nothing, Optional subtitle As String = Nothing, Optional configure As Action(Of MASImageViewer) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Media.vb |
| AddFileDropZone | MASFileDropZone | Optional title As String = Nothing, Optional description As String = Nothing, Optional configure As Action(Of MASFileDropZone) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Media.vb |
| AddCalendarView | MASCalendarView | Optional selectedDate As Nullable(Of Date) = Nothing, Optional displayMonth As Nullable(Of Date) = Nothing, Optional configure As Action(Of MASCalendarView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Media.vb |
| AddFilePickerControl | MASFilePickerControl | Optional configure As Action(Of MASFilePickerControl) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Media.vb |
| AddFileExplorerView | MASFileExplorerView | Optional configure As Action(Of MASFileExplorerView) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Media.vb |

## Navigation

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddTransferList | MASTransferList | Optional availableItems As IEnumerable(Of String) = Nothing, Optional selectedItems As IEnumerable(Of String) = Nothing, Optional configure As Action(Of MASTransferList) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddContentCarousel | MASContentCarousel | Optional title As String = Nothing, Optional configure As Action(Of MASContentCarousel) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddNavigationRail | MASNavigationRail | Optional title As String = Nothing, Optional configure As Action(Of MASNavigationRail) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddCommandPalette | MASCommandPalette | Optional title As String = Nothing, Optional configure As Action(Of MASCommandPalette) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddMenuBar | MASMenuBar | Optional configure As Action(Of MASMenuBar) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |

| AddBreadcrumb | MASBreadcrumb | Optional items As IEnumerable(Of String) = Nothing, Optional configure As Action(Of MASBreadcrumb) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddPagination | MASPagination | Optional currentPage As Integer = 1, Optional totalPages As Integer = 1, Optional configure As Action(Of MASPagination) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddTabControl | MASTabControl | Optional configure As Action(Of MASTabControl) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddToolbar | MASToolbar | Optional configure As Action(Of MASToolbar) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |
| AddCommandBar | MASToolbar | Optional configure As Action(Of MASToolbar) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.Navigation.vb |

`AddMenuBar` is the public consumer gateway for the official full-width MainMenuBar below the TopBar. It follows the `window.Controls.Add*` factory pattern while internally attaching through the shell-owned chrome slot. It is intentionally not a direct/page-control factory; direct `MASMenuBar` hosting is rejected by `MASApplicationWindowControls`, and page/content layout builders reject `MASMenuBar` entries to prevent middle-of-form menu bars. Consumers configure the menu inside `AddMenuBar(...)` and must not pass the returned bar to `page.FullWidth(...)` or any region/content builder.

## General

| Method | Return type | Parameters | Evidence path |
|---|---|---|---|
| AddControl | TControl | Of TControl As MASControlBase)(control As TControl, Optional configure As Action(Of TControl) = Nothing | MASSystem/Application/Facade/MASApplicationWindowControls.ControlFactory.vb |