metabuilder/frontends/qt6/MaterialMapping.md

# Material UI → QML Mapping

This reference ties every Material UI component that the Next.js frontend currently consumes to the closest QML equivalent from `frontends/qt6/qmllib/Material` or the built-in Qt Quick Controls primitives. Where we haven’t implemented a dedicated wrapper yet, the “QML counterpart” points at the Qt Quick Control that can be used to achieve the same structure and feel.

| Material UI component | QML counterpart | Notes |
| --- | --- | --- |
| Accordion / AccordionSummary / AccordionDetails | `QtQuick.Controls` `ExpandableList` (custom `MaterialAccordion` planned) | Use `ColumnLayout` + `MouseArea` to expand/collapse; we mimic this in templates. |
| Alert / AlertTitle | `Material.MaterialAlert` | Custom `Rectangle` + `Text` + optional icon slot. |
| AppBar / Toolbar | `Material.MaterialAppBar` / `Material.MaterialToolbar` | Fixed `Rectangle` with `RowLayout`; exposes elevation and brand slot. |
| Avatar / AvatarGroup | `Material.MaterialAvatar` | Circular `Image`/`Rectangle`; we’ll build grouping helper if needed. |
| Badge / Chip | `Material.MaterialBadge` / `Material.MaterialChip` | Already wired; badges accept accent/dense/outlined variants (and optional `iconSource`). |
| Box / Container | `Material.MaterialBox` | Simple layout container that mirrors Material spacing defaults. |
| Breadcrumbs | `Material.MaterialBreadcrumbs` | Horizontal `RowLayout` of text/buttons separated by dividers. |
| Button / ButtonProps | `Material.MaterialButton` | Supports contained, outlined, and icon-enabled styles with ripple and disabled handling. |
| Card / CardContent / CardHeader / CardActions / CardMedia | `Material.MaterialCard` + `Box`/`ColumnLayout` | Cards already exist with padding/border/elevation tokens. |
| Checkbox | `QtQuick.Controls` `CheckBox` | Styled using Material palette in `MaterialTheme`. |
| ChipProps | `Material.MaterialChip` | Accepts `text` + optional prefix/utility slots. |
| CircularProgress | `Material.MaterialCircularProgress` | `BusyIndicator`-based circle, colored via palette. |
| Collapse | `QtQuick.Controls` `Collapsible` / `MaterialAccordion` | Controlled container h/t `MaterialAccordion` behavior. |
| Container | `Material.MaterialContainer` | Width-constraining `Rectangle` that honors layout margins. |
| CssBaseline | `Material.MaterialCssBaseline` | Background/typography reset that sets root window colors. |
| Dialog / DialogActions / DialogContent / DialogTitle | `Material.MaterialDialog` | Wraps `QtQuick.Controls.Dialog` + slot for actions, sections, icons. |
| Divider | `Material.MaterialDivider` | Simple horizontal line with palette color. |
| Drawer | `Material.MaterialDrawer` | `Drawer` from Qt Quick Controls with custom surface look. |
| FormControl / FormControlLabel / FormHelperText / FormLabel | `Material.MaterialFormField` | Label + helper text wrappers around `Material.MaterialTextField`. |
| Grid | `QtQuick.Layouts.GridLayout` | `Material.MaterialGrid` simply forwards to `GridLayout` with spacing defaults. |
| IconButton | `Material.MaterialIconButton` | Icon+button with circular touch target and ripple. |
| InputAdornment | `Material.MaterialInputAdornment` | `RowLayout` that positions adornments next to text fields. |
| InputBase / TextField / TextFieldProps | `Material.MaterialTextField` | Material text field with outlined background, focused border, and caret colors. |
| InputLabel | `Material.MaterialInputLabel` | Styled `Text` placed above inputs. |
| LinearProgress | `Material.MaterialLinearProgress` | `Rectangle` with animated gradient track. |
| Link | `Material.MaterialLink` | `Text` with underline + hover opacity + `MouseArea`. |
| List / ListItem / ListItemButton / ListItemIcon / ListItemText | `Material.MaterialList` set of `Repeater` + `Material.MaterialListItem` | Compose vertical menus with icons and text. |
| Menu / MenuItem | `Material.MaterialMenu` / `Material.MaterialMenuItem` | Wraps Qt Quick `Menu` so you can customize menu labels/icons. |
| Pagination / PaginationItem | `Material.MaterialPagination` | Row of buttons that mirror Next.js `Pagination` styles. |
| Paper | `Material.MaterialPaper` | Surface `Rectangle` that uses `surface` palette + outline. |
| Popover | `Material.MaterialPopover` | `Popup` with arrow and surface coloring. |
| Radio / RadioGroup | `QtQuick.Controls` `RadioButton` plus `Material.MaterialRadioGroup` | `RowLayout` that keeps buttons themed. |
| Select / SelectChangeEvent | `Material.MaterialSelect` | `ComboBox` shim with label/input slot. |
| Skeleton | `Material.MaterialSkeleton` | Animated gradient `Rectangle` for loading placeholders. |
| Slider / SliderProps | `Material.MaterialSlider` | `QtQuick.Controls.Slider` with palette colors. |
| Snackbar | `Material.MaterialSnackbar` | Bottom-aligned `Rectangle` that slides in/out. |
| Stack | `Material.MaterialStack` | Chooses `ColumnLayout`/`RowLayout` depending on orientation property. |
| Switch / SwitchProps | `Material.MaterialSwitch` | Toggle control built on `QtQuick.Controls.Switch` with dark background. |
| Tab / Tabs | `Material.MaterialTabBar` + `Material.MaterialTabContent` | TabView analog with indicator built from `Rectangle`. |
| Table / TableHead / TableBody / TableRow / TableCell / TableContainer / TableFooter | `Material.MaterialTable` | Basic grid using `Repeater` + `RowLayout` + `ColumnLayout` replicating header/body separation. |
| TabsProps | `Material.MaterialTabBar` | Accepts orientation/scroll props. |
| Theme / ThemeProvider / useTheme | `Material.MaterialPalette` / `Material.MaterialTheme` | Singleton palette plus helper `QtObject` for derived colors. |
| ToggleButton / ToggleButtonGroup | `Material.MaterialToggleGroup` | `RowLayout` of `Material.MaterialButton` toggles with `exclusive` property. |
| Toolbar | `Material.MaterialToolbar` | Horizontal container used inside navigation bars. |
| Tooltip / TooltipProps | `Material.MaterialTooltip` | Floating `Rectangle` with arrow and text, anchored to host. |
| Typography | `Material.MaterialTypography` | `Text` wrapper providing Material font weights/sizes. |
| Breadcrumbs (2nd mention) | `Material.MaterialBreadcrumbs` | See above for horizontal nav. |
| DividerProps / MenuProps / PopoverProps etc. | Prop-driven wrappers that forward to QML `Rectangle`/`Menu` etc. | We expose `property alias` to match MUI API surface. |
| useMediaQuery / useScrollTrigger / useTheme | Signals exposed via `Material.MaterialResponsive` helpers | Provide screen width bindings and scroll watchers for `AppBar`. |

Additional Qt Quick Controls (Tabs, Dialog, Menu, Drawer, Slider, Switch, RadioButton, ComboBox, TableView, ProgressBar, MenuBar, etc.) can be composed directly when the Material-specific wrapper doesn’t exist yet. File a follow-up when you need a dedicated component and we’ll implement it inside `qmllib/Material`.

This mapping is kept up to date whenever a new Material UI pattern is added to the Next.js surface, so the Qt6 team knows which QML primitives to extend for a faithful replica.