From 06d1f9235c40f15b162509f369a1ee1ec5782e7d Mon Sep 17 00:00:00 2001 From: Rob Date: Sat, 17 Jan 2026 01:58:52 -0500 Subject: [PATCH] possible docs for v6 --- CHANGELOG.md | 60 ++++++++ documentation/upgrade-v6.md | 284 ++++++++++++++++++++++++++++++++++++ 2 files changed, 344 insertions(+) create mode 100644 documentation/upgrade-v6.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 8adfc6c2..58897eea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,66 @@ title: Changelog ## 6.0.0 (Unreleased) +This release updates the bindings to support `@mui/material` v6. See the [MUI v6 migration guide](https://mui.com/material-ui/migration/migration-v5/) for details on upstream changes. + +### Breaking Changes + +- :boom: `Grid` refactored for MUI v6's new Grid2 component + - Now imports from `@mui/material/Grid2` + - Removed `item` and `zeroMinWidth` props (items are now implicit in Grid2) + - Replaced `xs`, `sm`, `md`, `lg`, `xl` props with a single `size` prop using `GridSize.t` + - Added `offset` prop using `GridOffset.t` + - Use `GridLegacy` for the deprecated v1 Grid behavior + +- :boom: `LoadingButton` removed from `@rescript-mui/lab` + - Loading functionality is now built into the standard `Button` component + - Use `Button` with `loading`, `loadingIndicator`, and `loadingPosition` props instead + +- :boom: `Typography.color` is now a dedicated enum type + - Values: `Primary`, `Secondary`, `Success`, `Error`, `Info`, `Warning`, `TextPrimary`, `TextSecondary`, `TextDisabled` + - The `paragraph` prop is now deprecated (use `component` prop instead) + - `variantMapping` fields now use `string` instead of `variant` type + +- :boom: `Autocomplete.inputChangeReason` extended with new values + - Added `Blur`, `SelectOption`, and `RemoveOption` variants + +- :boom: `Stack.direction` now uses `StackDirection.t` for responsive breakpoint support + - Previously was `array` + +### New Features + +- :rocket: Add `loading`, `loadingIndicator`, and `loadingPosition` props to `Button` + - Button loading styles added to `classes` and `Overrides` + +- :rocket: Add `slots` and `slotProps` types to many components for improved customization + - Accordion, AccordionSummary, Alert, Autocomplete, Avatar, AvatarGroup, Backdrop, Badge, BottomNavigationAction, Breadcrumbs, CardActionArea, CardHeader, Checkbox, Drawer, FormControlLabel, InputBase, ListItemText, Menu, MobileStepper, Modal, OutlinedInput, Popover, Radio, Rating, Slider, Snackbar, SpeedDial, SpeedDialAction, StepContent, StepLabel, SwipeableDrawer, Switch, TablePagination, TableSortLabel, TextField, Tooltip + +- :rocket: Add responsive value types with breakpoint support + - `GridSize.t`, `GridSpacing.t`, `GridDirection.t`, `GridOffset.t`, `GridColumns.t`, `StackDirection.t` + - Support for value, array, or breakpoint object forms + +- :rocket: Add `justifyItems` and `justifySelf` to `System.props` + +- :rocket: Add flexbox/grid values to `System.Value.t` + - Alignment: `SpaceBetween`, `SpaceAround`, `SpaceEvenly`, `Left`, `Right` + - Direction: `Row`, `RowReverse`, `Column`, `ColumnReverse` + - Wrap: `Nowrap`, `Wrap`, `WrapReverse` + +- :rocket: Add `GridLegacy` component for backwards compatibility with Grid v1 + +- :rocket: Add `AvatarGroup.renderSurplus` prop + +### Bug Fixes + +- :bug: Fix slot `@as` decorators to match MUI v6 lowercase naming + - Badge, Modal, Backdrop slots now use lowercase keys (`root`, `badge`, `backdrop`) + - Breadcrumbs keeps uppercase `CollapsedIcon` to match MUI's exception + +### Internal + +- :house: Split `System.props` into `propsWithoutColor` and `props` for Typography color handling +- :house: Add automated npm publish workflow + ## 5.1.3 - :bug: Add a few more missing props to `Box`, `Link`, `ListSubHeader`, `Tab`, `TextField` and `Typography`. diff --git a/documentation/upgrade-v6.md b/documentation/upgrade-v6.md new file mode 100644 index 00000000..982476e3 --- /dev/null +++ b/documentation/upgrade-v6.md @@ -0,0 +1,284 @@ +# Upgrading to v6.0.0 + +This guide helps you migrate from `@rescript-mui/material` v5.x to v6.0.0, which adds support for `@mui/material` v6. + +> **Prerequisites**: This guide assumes familiarity with [MUI v6 breaking changes](https://v6.mui.com/material-ui/migration/upgrade-to-v6/). We focus on the ReScript binding changes. + +## Grid → Grid2 + +The `Grid` component now uses MUI's new Grid2 implementation. This is the most significant breaking change. + +### Removed props + +- `item` - Grid items are now implicit (no longer needed) +- `zeroMinWidth` - Use `minWidth: 0` in sx prop instead + +### Changed props + +The breakpoint-specific size props (`xs`, `sm`, `md`, `lg`, `xl`) are replaced with a single `size` prop: + +**Before (v5):** + +```rescript + + + + + +``` + +**After (v6):** + +```rescript + + + + + +``` + +### Size values + +The `GridSize.t` type supports multiple forms: + +```rescript +// Single value for all breakpoints +size=Int(6) +size=Auto +size=Grow // replaces `true` + +// Responsive object +size=Object({xs: Int(12), sm: Int(6), md: Int(4)}) + +// Array form +size=Array([Int(12), Int(6), Int(4)]) +``` + +### New offset prop + +Grid2 adds support for offsets: + +```rescript + + // Centered 6-column item + +``` + +### Using GridLegacy + +If you need time to migrate, use `GridLegacy` which preserves the v5 API: + +```rescript + + + + + +``` + +## LoadingButton → Button + +The `LoadingButton` component from `@rescript-mui/lab` has been removed. Use the standard `Button` with loading props instead. + +**Before (v5):** + +```rescript + + {"Submit"->React.string} + +``` + +**After (v6):** + +```rescript + +``` + +### Loading prop type + +The `loading` prop uses a dedicated type for three-state behavior: + +```rescript +type loading = + | True // Show loading indicator, disable button + | False // Normal state, loading wrapper rendered + | Null // Normal state, no loading wrapper (default) +``` + +### Loading position and indicator + +```rescript + +``` + +## Typography + +### Color prop + +The `color` prop is now a dedicated enum instead of accepting system values: + +**Before (v5):** + +```rescript +... // worked +... // also worked +``` + +**After (v6):** + +```rescript +... +... +... +``` + +Available values: `Primary`, `Secondary`, `Success`, `Error`, `Info`, `Warning`, `TextPrimary`, `TextSecondary`, `TextDisabled` + +### Deprecated paragraph prop + +The `paragraph` prop is deprecated. Use `component` instead: + +**Before:** + +```rescript +... +``` + +**After:** + +```rescript +... +``` + +## Stack + +### Direction prop + +The `direction` prop now uses `StackDirection.t` for responsive support: + +**Before (v5):** + +```rescript +... +``` + +**After (v6):** + +```rescript +// Single direction +... + +// Responsive +... +``` + +## Autocomplete + +### Extended inputChangeReason + +The `inputChangeReason` type has new variants: + +```rescript +type inputChangeReason = + | Blur // new + | Clear + | Input + | Reset + | SelectOption // new + | RemoveOption // new +``` + +Update any pattern matches on this type. + +## Slots and SlotProps + +Many components now have `slots` and `slotProps` for customization. This is the preferred way to customize internal elements in MUI v6. + +```rescript + +``` + +Components with new slots/slotProps: + +- Accordion, AccordionSummary +- Alert, Autocomplete +- Avatar, AvatarGroup +- Backdrop, Badge +- BottomNavigationAction, Breadcrumbs +- CardActionArea, CardHeader, Checkbox +- Drawer, FormControlLabel +- InputBase, ListItemText +- Menu, MobileStepper, Modal +- OutlinedInput, Popover, Radio, Rating +- Slider, Snackbar +- SpeedDial, SpeedDialAction +- StepContent, StepLabel +- SwipeableDrawer, Switch +- TablePagination, TableSortLabel +- TextField, Tooltip + +## AvatarGroup + +### New renderSurplus prop + +Customize how the "+X" surplus indicator is rendered: + +```rescript + {`+${surplus->Int.toString}`->React.string}} +> + ... + +``` + +## System props + +### New flexbox props + +`justifyItems` and `justifySelf` are now available: + +```rescript +... +``` + +### New System.Value.t variants + +Additional alignment and flex values: + +```rescript +// Alignment +SpaceBetween, SpaceAround, SpaceEvenly, Left, Right + +// Flex direction +Row, RowReverse, Column, ColumnReverse + +// Flex wrap +Nowrap, Wrap, WrapReverse +``` + +## Quick migration checklist + +- [ ] Update `@mui/material` to v6 +- [ ] Replace `Grid` usage with new `size` prop API (or switch to `GridLegacy`) +- [ ] Remove `item` prop from Grid items +- [ ] Replace `LoadingButton` with `Button` + loading props +- [ ] Update `Typography.color` to use new enum values +- [ ] Update `Stack.direction` to new type +- [ ] Update any `Autocomplete.inputChangeReason` pattern matches +- [ ] Consider adopting `slots`/`slotProps` for component customization