# V1 Public API Catalog

This catalog is the human-readable entry point for the approved v1 public API surface. It is derived from the repository evidence assets, not from Showcase behavior.

## Evidence Sources

| Source | Role |
|---|---|
| `eng/tests/Nexamas.UI.ApprovedV1PublicSurface.json` | Defines the v1-approved stable public type set. |
| `eng/tests/Nexamas.UI.PublicApiClassificationBaseline.json` | Classifies public types as Stable, Advanced, Evidence, Preview, Compat, or InternalCandidate. |
| `eng/tests/Nexamas.UI.PublicSurfaceTypeBaseline.json` | Captures the full source-derived public type baseline and evidence paths. |
| [Public surface inventory](../_inventory/public-surface-inventory.md) | Assembly-reconciled inventory of all consumer-visible public types and their source evidence. |

## Stability Boundary

| Category | Count | Meaning for consumer docs |
|---|---:|---|
| V1-approved Stable public types | 117 | Safe to document as the long-term beginner SDK contract. |
| Advanced public types | 159 | May be public, but should not be promoted as the default beginner path. |
| Evidence public types | 10 | May support diagnostics, quality proof, or release evidence. |
| Preview public types | 9 | Public preview surface; do not present as stable v1 contract. |
| Compat public types | 1 | Compatibility surface; do not make it the main adoption route. |

These categories classify **296 explicitly source-declared public type records**. The compiled assembly additionally exposes **6 compiler-generated nested event-delegate types**, producing **302 CLR-visible public types** in total. The generated delegates are event contracts rather than separately promoted beginner APIs.

Only the 117 approved stable records are treated as the v1 consumer API catalog here.

## Primary Namespaces

| Namespace | Approved v1 types | What it is for |
|---|---:|---|
| `Nexamas.UI.Application` | 68 | Application lifetime, windows, layout builders, services, themes, output, dialogs, and shell-owned routes. |
| `Nexamas.UI.Controls` | 49 | Stable direct control types and related public enums for the beginner control surface. |

## Beginner Usage Rule

Prefer the application facade and window-owned control factories:

```vb
Imports System.Windows.Forms
Imports Nexamas.UI.Application

Public Class MainForm
    Inherits Form

    Private ReadOnly _application As MASApplication
    Private ReadOnly _window As MASApplicationWindow

    Public Sub New()
        _application = MASApplication.Create()
        _window = _application.CreateWindow(owner:=Me)

        Dim button = _window.Controls.AddButton("Save")
    End Sub

    Protected Overrides Sub OnFormClosed(e As FormClosedEventArgs)
        _window.Dispose()
        _application.Dispose()
        MyBase.OnFormClosed(e)
    End Sub
End Class
```

Use direct control constructors only when a reviewed page specifically documents that path. The consumer-first route is `MASApplication`, `MASApplicationWindow`, layout builders, and `window.Controls.Add*` factories.

## Common Goals

| I want to... | Start with | More detail |
|---|---|---|
| Create a window | `MASApplication`, `MASApplicationWindow` | [Application recipes](../recipes/application.md) |
| Add buttons and actions | `window.Controls.AddButton`, `MASButton` | [Button recipes](../recipes/buttons.md) |
| Compose a page | `LayoutPage`, `MASApplicationLayoutPageBuilder` | [Layout recipes](../recipes/layout.md) |
| Add inputs | `window.Controls.AddTextBox`, `AddComboBox`, `AddSlider` | [Input recipes](../recipes/inputs.md) |
| Show feedback | `AddStatusBanner`, `AddValidationMessage`, `AddEmptyState` | [Feedback recipes](../recipes/feedback.md) |
| Add surfaces | `AddGroupBox`, `AddExpander`, `AddAccordion`, `AddTileBox` | [Surface recipes](../recipes/surfaces.md) |
| Add navigation | `AddTabControl`, `AddBreadcrumb`, `AddPagination`, `AddCommandBar` | [Navigation recipes](../recipes/navigation.md) |
| Show tabular data | `AddDataGrid`, `MASDataView` | [DataGrid recipes](../recipes/datagrid.md) |
| Use product-size controls | `AddTreeGrid`, `AddKanbanBoard`, `AddPivotTable`, and peers | [Product control recipes](../recipes/product-controls.md) |
| Apply theme/surface choices | `MASApplicationTheme`, `MASApplicationSurfaceMaterialGateway` | [Theme and surface recipes](../recipes/theme-surface.md) |
| Export output | `MASApplication.Output`, `MASOutputTarget`, `MASOutputOptions` | [Output recipes](../recipes/output.md) |

## Approved Application Types

These `Nexamas.UI.Application` types are v1-approved Stable records.

### Classes

`MASApplication`, `MASApplicationActionGroupLayoutBuilder`, `MASApplicationClosedEventArgs`, `MASApplicationDialogShieldOptions`

`MASApplicationFileExplorerOptions`, `MASApplicationFileExplorerResult`, `MASApplicationFilterBarLayoutBuilder`, `MASApplicationFormRowLayoutBuilder`

`MASApplicationGalleryLayoutBuilder`, `MASApplicationLayoutFlowBuilder`, `MASApplicationLayoutGridBuilder`, `MASApplicationLayoutPageBuilder`

`MASApplicationLayoutStackBuilder`, `MASApplicationOpenedEventArgs`, `MASApplicationOutput`, `MASApplicationPageHost`

`MASApplicationProgressHandle`, `MASApplicationResult`, `MASApplicationSizing`, `MASApplicationSplitPaneLayoutBuilder`

`MASApplicationSurfaceHandle`, `MASApplicationSurfaceLayoutBuilder`, `MASApplicationSurfaceMaterialGateway`, `MASApplicationSurfaceMaterialOption`

`MASApplicationSurfaceMaterialScope`, `MASApplicationSurfaceShowResult`, `MASApplicationTheme`, `MASApplicationTooltipTarget`

`MASApplicationWindow`, `MASApplicationWindowChrome`, `MASApplicationWindowContextMenus`, `MASApplicationWindowControls`

`MASApplicationWindowDialogs`, `MASApplicationWindowFileExplorer`, `MASApplicationWindowFilePicker`, `MASApplicationWindowGeometry`

`MASApplicationWindowInput`, `MASApplicationWindowPresentation`, `MASApplicationWindowProgress`, `MASApplicationWindowServices`

`MASApplicationWindowShell`, `MASApplicationWindowSizing`, `MASApplicationWindowTheme`, `MASApplicationWindowToasts`

`MASApplicationWindowTooltips`, `NexamasUIChangedEventArgs`

### Enums

`MASApplicationActionGroupAlignment`, `MASApplicationCloseReason`, `MASApplicationDialogShieldMode`, `MASApplicationDialogShieldReason`

`MASApplicationDialogShowPolicy`, `MASApplicationFilterBarAlignment`, `MASApplicationFilterBarDirection`, `MASApplicationGalleryAlignment`

`MASApplicationGalleryTileSize`, `MASApplicationPageLayoutKind`, `MASApplicationResultStatus`, `MASApplicationSurfaceBarSize`

`MASApplicationSurfaceCommandBarPlacement`, `MASApplicationSurfaceFooterPlacement`, `MASApplicationSurfaceRhythm`, `MASApplicationSurfaceShowStatus`

`MASApplicationSurfaceSideSize`, `MASApplicationSurfaceState`, `MASApplicationThemeScope`, `MASWindowPresentationProfileKind`

`MASWindowShadowMode`, `MASWindowStartupPlacement`

## Approved Control Types

These `Nexamas.UI.Controls` types are v1-approved Stable records.
Detailed stable/advanced controls and components reference: [Batch 2 Controls and Components API](api/controls-components-api.md).


### Classes

`MASAccordion`, `MASBadge`, `MASButton`, `MASCallout`

`MASCard`, `MASCommandPalette`, `MASDrawer`, `MASEmptyState`

`MASExpander`, `MASFormValidationSummary`, `MASGroupBox`, `MASLabel`

`MASLoadingSkeleton`, `MASNotificationPanel`, `MASOperationProgressBox`, `MASPopover`

`MASProgressBar`, `MASSegmentedControl`, `MASSegmentedControlSelectionChangedEventArgs`, `MASSelectorItemControl`

`MASSidePanel`, `MASStatusBanner`, `MASStepper`, `MASTabControl`

`MASTabItem`, `MASTitle`, `MASToastEventArgs`, `MASToastOptions`

`MASValidationMessage`, `MASWinControlBase`, `MASWizard`

### Enums

`MASButtonIconPlacement`, `MASCalloutPlacement`, `MASDrawerSide`, `MASFormValidationSummaryInteractionMode`

`MASGroupBoxBorderRecipe`, `MASGroupBoxBorderStrength`, `MASGroupBoxSurfaceSource`, `MASGroupBoxTitlePlateStrength`

`MASHorizontalAlignment`, `MASLabelTextRole`, `MASLabelVariant`, `MASProgressBarFrameMode`

`MASProgressBarLabelPlacement`, `MASStepperOrientation`, `MASStepperStepState`, `MASToastPlacement`

`MASToastTone`, `MASVerticalAlignment`

## Member-Level References

- [Batch 1 Application API reference](api/application-api.md)
- [Batch 2 Controls and Components API reference](api/controls-components-api.md)
- [Batch 3 Systems, Evidence, and Compatibility API reference](api/systems-evidence-compat-api.md)
- [All public types index](api/all-public-types-index.md)
This catalog is type-level because the official approval manifest is type-level. The three batch pages together document all current public type records in the manifest; use these member-level references for source-reviewed public usage details:

- [Component factory surface](component-factory-surface.md)
- [Application facade surface](application-facade-surface.md)
- [Layout and size surface](layout-size-surface.md)
- [Theme and surface surface](theme-surface-surface.md)
- [Data component surface](data-component-surface.md)
- [Output surface](output-surface.md)

## Verification boundary

This catalog classifies the intended public consumer surface. It does not by itself prove that every documentation snippet compiles; snippet compilation and external-consumer verification are tracked separately by the repository quality process.