v2 Status

I’ll try to keep this one more updated than the last project status issue I created and add some more development notes as things get closer and alpha/beta releases are published

Current Development State

Below is a list of all the packages that are expected to be made to as well as some already finished and completed packages. The items below that are checked should be at a “safe” state and probably won’t change much before the official v2 release.

• @react-md/alert
• @react-md/app-bar
• @react-md/avatar
• @react-md/autocomplete - ~In progress (80% done)~ Mostly done. Need to update it to be able to work without the useFixedPositioning hook for better mobile support.
• @react-md/badge
• @react-md/bottom-navigation - Not started, might integrate with @react-md/app-bar
• @react-md/button
• @react-md/card
• @react-md/chip
• @react-md/dialog
• @react-md/divider
• @react-md/elevation
• @react-md/expansion-panel
• @react-md/form
• @react-md/icon
• @react-md/layout - Need to implement the mini variants and add tests. Scoped for later release
• @react-md/link
• @react-md/list
• @react-md/material-icons
• @react-md/media
• @react-md/menu
• @react-md/overlay
• @react-md/pickers - Not started. Definitely last thing I’ll do (if I decide to support date and time pickers again)
• @react-md/portal
• @react-md/progress
• @react-md/sheet
• @react-md/slider - Not started
• ~@react-md/sizing~ removed and moved into @react-md/utils
• @react-md/states
• @react-md/tab
• @react-md/table
• @react-md/theme
• @react-md/tooltip
• @react-md/transition
• @react-md/tree
• @react-md/typography
• @react-md/utils
• ~@react-md/wia-aria - Kind of done for now. Same as utils and add more hooks/utils as development continues~ removed and moved into @react-md/utils

General removals / renaming:

• Toolbar -> AppBar (@react-md/app-bar package)
• Drawer -> Sheet (@react-md/sheet package)
• Inks -> Ripple (@react-md/states package)
• NavigationDrawer -> Layout (@react-md/layout package)
• Subheader -> Text and ListSubheader (@react-md/typography and @react-md/list packages)

What’s the biggest change?

I’ll be providing a lot more Sass mixins to help generate styles as well as:

• “automatic” color contrast fixes using the rmd-theme-tone mixin
• theming utility functions and mixins for each package
• creating theming mixins for each package so that the padding, margin, and colors can be quickly swapped around in each package
• using CSS variables for live theming changes as well as some helper components to handle the CSS Variable changes for you
• built in RTL support along with mixins to manage it for you in your app
• Sass variables are now accessible in JS via the dist/scssVariables file that each package will export
• Better dynamic theme support
• Better dark theme support (documentation site will be starting in Dark theme)
• Much better typescript type definitions since I am writing everything in Typescript from the ground up.
• Keyboard Only Focus effects as well as an easy way to hook into this yourself
• Fixed typography, typography helper components, and no longer pulluting the global tags with react-md styles
• Pre-compiled material icon components in the @react-md/material-icons package
• Fixing the accessibility claims I had in v1
• Smaller bundle size and slightly better performance (estimated)

Documentation

What’s next?

Lots of documentation. I’ve been reworking the documentation site a lot to hopefully make it easier to see examples and understand the component usage. Most of the examples in v2 will be extremely simple and only showing the simple use cases. More complex examples will be added as separate apps or in different routes so that the main focus is on the components themselves.

Changelogs and README

I will also need to finish up the README.md in each package to add better details as well as finish writing the CHANGELOG.md so that the changes are documented.

Component Documentation

Next, I’ll need to figure out how to get useful documentation out of Typescript and/or TypeDoc. Part of my documentation site rewrite was to make things easier to digest since I noticed that there was a log of information, but most of it was worthless or only helpful in uncommon situations. Since v2 was re-written in Typescript, I can no longer use react-docgen to generate the component API documentation and I feel like TypeDoc’s default output is even worse than the v1 documentation site with unhelpful and unused information.

I’ve tried a few things like the react-docgen-typescript, writing my own typedoc compiler, manual documentation, etc but I wasn’t happy with any solution since it left me with:

• missing documentation
• too much useless documentation
• couldn’t figure out how in the world AST works and how to extract documentation myself

SassDoc Documentation

My goal for the updated SassDoc will be to help make the pages more condensed and useful. I copied the SassDoc page generation from the SassDoc project, but it feels like most of the information provided (once again) is extra noise and way too spread out. A denser layout and removing a lot of the unused info by default will help a lot.

Part of my new build flow allows me to resolve SassDoc variables immediately, so the docs will be updated to be able to toggle between the “default” value which might reference variables, have if statements, other functions, etc and show what the default “compiled” value would be.

My general idea will be to create a dense variable table near the top of the page, followed by the themeing mixins and any general helper mixins the package provides. The mixins will end up having example usage as well that will output the generated CSS to help showcase the usage even more.

Code Sandboxes

~I checked out the material-ui website again and really dig their idea of generating code sandboxes for each of their examples so I decided to copy this idea. Unfortunately, I’ll need to wait for CompuIves/codesandbox-client#1629 before this can be live since I rely on the SASS_PATH/includePaths in v2.~

I implemented a workaround for now by creating “webpack” distributions of the scss files that are available at @react-md/PACKAGE/dist/scss/mixins.scss

More Updates

~Another step I’ll need to do is figure out how to host my new documentation site. I decided to try out next.js mostly for the new serverless support that was added, but it’s been so long since I’ve touched backend or AWS it seems too complicated right now. I’ll probably have to look into spinning up another small EC2 instance and host it there instead.~

I’ll be moving the documentation site from https://react-md.mlaursen.com to https://react-md.dev

~If you are interested in seeing the v2 code, usage, or how things are progressing, I’d recommend viewing:~

• ~the next branch~
• ~the documentation demos~
• ~the current packages~

Hopefully the development time for v2 hasn’t been too slow that made this library undesirable (but totally understandable) and the v2 changes will be exciting for other developers to use. I’ve personally be enjoying the new theming and typography that’s built in as well as the additional mixin support I’ve been adding.

[mlaursen]

I have completed the majority of the the sheet and layout packages. The installation page, the layout guide, or the layout readme might be a good place to start if you are interested in @react-md/layout part, otherwise the sheet demos page is a good starting point.

The new layout should be live now at https://react-md.dev and simplified the initial v2 app setup with the Configuration, Layout, and useLayoutNavigation exports. The Layout component appears to work with any routing library that provides the current pathname, but I probably have to do a bit more testing to be sure. If you’re interested in seeing how much boilerplate was removed because of this package, these two commits might be useful? 8a83d3e, 1c15a69.

The remaining work for the @react-md/layout component is:

• implementing the mini variant
• writing tests 😕
• publishing and finishing the “Layout guide”

The @react-md/layout package is a bit different than the reset in that you don’t want to actually use multiple Configuration components within your app since it initializes the AppSizeListener and throws an error if multiple instances of that component are mounted. I started creating a sandbox and a “guide” for using this package instead of having a live demo page, but I’ll need to wait until I’ve published this release to finish the sandbox/guide or think of a nicer way to add a “live” demo to the documentation site.

Some other changes that were implemented:

• added extreme convenience props for the Grid, GridCell, GridList, and GridListCell components that can automatically wrap each child in the correct Cell type (Grid and GridListCell) and/or clone the correct styles/className into each child. ad7d81f

Side note: I actually forgot to release the v2.0.0-alpha-10 that was just the @react-md/tree changes (whoops), so I’ll just release it with the layout and sheet changes as well.

Edit: ~Oof. Looks like I need to add support back again for AppSize when the SSR guesses incorrectly based on headers. Maybe it would be better to use display: none instead of returning null for incorrect media types?~ Fixed.

[mlaursen]

Ahh whoops… I think I was a bit too eager to update to point to v2. https://react-md.dev has been updated to show@v2 in the headers and included a link to the v1 site in a dropdown menu. I also updated the installation guides under /guides to state @next to help with some of that as well. Sorry about the confusion