React-md: v2 Status

[mlaursen]

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.

• [x] @react-md/alert
• [x] @react-md/app-bar
• [x] @react-md/avatar
• [x] @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.
• [x] @react-md/badge
• [x] @react-md/bottom-navigation - Not started, might integrate with
  @react-md/app-bar
• [x] @react-md/button
• [x] @react-md/card
• [x] @react-md/chip
• [x] @react-md/dialog
• [x] @react-md/divider
• [x] @react-md/elevation
• [x] @react-md/expansion-panel
• [x] @react-md/form
• [x] @react-md/icon
• [ ] @react-md/layout - Need to implement the mini variants and add tests. Scoped for later release
• [x] @react-md/link
• [x] @react-md/list
• [x] @react-md/material-icons
• [x] @react-md/media
• [x] @react-md/menu
• [x] @react-md/overlay
• [ ] @react-md/pickers - Not started. Definitely last thing I'll do (if I
  decide to support date and time pickers again)
• [x] @react-md/portal
• [x] @react-md/progress
• [X] @react-md/sheet
• [ ] @react-md/slider - Not started
• [x] ~@react-md/sizing~ removed and moved into @react-md/utils
• [x] @react-md/states
• [x] @react-md/tab
• [x] @react-md/table
• [x] @react-md/theme
• [x] @react-md/tooltip
• [x] @react-md/transition
• [x] @react-md/tree
• [x] @react-md/typography
• [x] @react-md/utils
• [x] ~@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]

As of today, https://react-md.dev should now be setup to host the new documentation site. Still lots of work remaining though:

• full mobile support
• ~fixing some demos and~ adding demos
• ~fixing some random errors appearing in prod (looks like bad build?)~
• fixing documentation that was just random thoughts
• ~unable to use navigation on mobile Firefox~ (also the mobile tap highlight still appears here...)
• etc

[markdon]

Looking forward to a new react-md to try out 😉

[mlaursen]

Notes to self for v2.1.0 release (or beyond):

I'll need to look into a different way of separate the scss files in these packages. I'm not sure if it's due to nextjs, but compilation times are extremely slow (min 10 seconds, but normally 20+ seconds). My best guess is that file resolution for these imports is slow especially with separating it into multiple files. My next best guess is that it's related to me doing all this "validation" for the scss variables and color comparisons with the rmd-theme-tone function which might really be overkill anyways for this project now that dev-tools have contrast checkers built-in.

Some possible workarounds for the issues above:

• write a script that joins all the scss files together as one in the base react-md package since the majority of users will probably just install that instead of the 20+ separate packages. The file should just join all the _variables.scss files, followed by _functions and then _mixins in order as a single file.
• remove the rmd-theme-tone stuff and just let developers use dev-tools instead to fix color contrast issues

I'll also need to look into simplifying the css variables and shorten their names a bit. There's really no reason to have super long names like: --rmd-form-text-padding-offset-top (or whatever) other than readability. If I'm "enforcing" a mixin/function to update theme variables, there could be simple lookups for human readable names to short css variable name. Or instead of having mixins and functions, I just define css variable constants that can be used like:

$rmd-text-padding-var: '--rmd-tpv';

.my-class {
  #{$rmd-text-padding-var}: 2rem;
}

I'll also need to re-think about what are actually useful to be set to css variables. I've mostly been doing colors and padding/margin, but I've done almost every normal variable as a css variable as well. It's most likely overkill and over-engineered.

Edit: The more I think about it, the more I like having the variable constants instead of the functions/mixins with validation. Seems easier and more straightforward. All the additional validation and map of all the css variables can be removed.

[mlaursen]

I released v2.0.0-alpha.9 this weekend which includes some of the work for the new alerts (Snackbars + Toasts) as well as the new grid system. Unfortunately, I did some breaking changes by moving bem from @react-md/theme to @react-md/utils, but I haven't really updated the docs for that and I doubt I have users on these alpha versions yet.

The grid system now uses the CSS grid instead of a flexbox grid with the Grid and GridCell components and there's support to opt-out of the weird material-design thing of 4 columns on mobile, 8 on tablet, and 12 on desktop. There's also another GridList component which allows for a different grid system (flex) that is _almost_ like grid-template-columns: repeat(auto-fit, minmax(AMOUNT, 1fr)); where it attempts to render as many columns as possible based on a max cell width instead of a min. The grid-template-columns example is built-in to the Grid component if you want to try that stuff out.

Quick link: https://react-md.dev/packages/utils/demos#material-grid-example-title

These should be available for codesandboxes as well to play around with. I might change them up a bit more as I play with it more.

[mlaursen]

It's progressing, but still a bit slowly...

I finished up the new keyboard movement API which I still can't tell if I like or not yet due to being a bit over engineered. There's now the main useFocusMovement for the cases where movement should actually trigger custom element.focus() behavior (Ex: Menus) and the more complex useActiveDescendantMovement where movement should not trigger new focus events and it is described by updating the aria-activedescendant attribute on a node (Ex: Select/Listbox). There will also be a growing list of a11y presets which can be used going forward and showing the progress of supported widgets/a11y.

The Menu component (DropdownMenu) was updated to use this pretty hackily and should be fixed at some point, but I think release v2 is a higher priority than fixing this right now... Otherwise, I completed most of the new non-native Select component so that more custom styles can be applied to an accessible <select>. There are still a couple of touch points I need to fix before I release the v2.alpha.10 release (scrolling active item on mount into view, more tests, more documentation, etc), but it should be live now on the documentation site with the simple example and the more complex customizing the option example.

Once I finish up the Listbox implementation used within the Select, I can also finish the Autocomplete since I was really just waiting on the final Listbox component to finish it up (I have some stashed changes that implements most of it other than the keyboard movement stuff).

So the remaining work to do before the v2 release:

• Finish listbox/select implementation and documentation
• Finish autocomplete
• Update @react-md/tree package to use the new useActiveDescendantMovement
• Finish @react-md/chip
• Finish @react-md/table
• Finish @react-md/tab (I have a stash of started work, but probably only 10% complete)
• Start and complete @react-md/layout
• Determine if it's worthwhile to include @react-md/expansion-panel, @react-md/slider, @react-md/bottom-navigation, and @react-md/pickers in the initial v2 release. (I'm leaning towards no for @react-md/pickers and @react-md/bottom-navigation right now since pickers will probably take a ridiculous amount of time and bottom navigation isn't super used right now)

[stickfigure]

The progress is exciting! I'm a big fan of expansion panels, but if v1 and v2 can coexist I can just transition those components last.

Thanks for all the hard work on this.

[mlaursen]

@stickfigure Good to know about the want for expansion panels! Part of the problem with how react-md is setup right now is that I can't gauge the usage/popularity of specific components to help prioritize them. Splitting it up was meant to solve this a little bit, but I have a feeling people will still just use the combined react-md dependency instead.

I'll check how much work it is to remake the expansion panels -- the biggest blocker was fixing the accessibility and keyboard movement for an Accordion widget, but the new keyboard movement API should work amazingly to fix that. When I get a bit closer, I'll check in on the material design specs again to see if anything has changed for the expansion panel and get a better estimate of work to complete.

I _think_ v1 and v2 can work together and will have a guide available here for that. I haven't fully tested it though so still a work in progress. I know the biggest problems will be with the typography and "base" styles that v1 applied to all DOM elements :( (should never have done that). My goal is to also update v1 to disable/rework styles a bit if it can detect if v2 is included as well (maybe global variable check)

[mlaursen]

Completed most of the listbox/select and autocomplete functionality. Quick links to Select examples and AutoComplete examples (oof. server error on AutoComplete link). Still requires a bit more polish though.

Unfortunately, I forgot about how android devices trigger 3-8 resize events when the soft keyboard appears (which causes the autocomplete menu to hide) so I have a bit more work to do for mobile support. I have a couple ideas of fixing this in the useResizeListener hook, but probably only going to spend a couple more hours trying to fix this since it's lower priority. There also might be some oddities with iOS as well with the soft keyboard that I can't remember right now. It's possible to workaround this issue by enabling the disableHideOnResize and disableHideOnScroll props for the time being, but I'm planning on fixing this before the final v2 release.

I think I'm going to reorder the remaining work as follows:

• try a few more fixes for soft keyboards "incorrectly" triggering resize events
• update the @react-md/tree package to finish keyboard a11y
• release v2.0.0-alpha.10
• fix and finish @react-md/sheet to use dialog a11y and additional configuration needed for the layout package
• create main @react-md/layout package that handles initial setup and all the different context providers with sensible defaults
• release v2.0.0-alpha.11
• start work for @react-md/tab
• release v2.0.0-alpha.12
• start work for @react-md/expansion-panel
• release v2.0.0-alpha.13
• finish @react-md/table
• finish @react-md/chip
• release v2.0.0-alpha.14
• leave @react-md/slider, @react-md/bottom-navigation, and @react-md/pickers for a later v2 release unless other watcher chime in.
• fix useResizeListener hook for ignoring soft keyboard if I didn't finish it by now
• determine if help text/error text is MVP for v2 on text fields/selects
• release v2.0.0-beta.0
• finish more testing and start looking more into generating documentation
• release v2.0.0-rc1
• release v2.0.0

Some things I think that would be great for later releases:

• think a bit more about an easy way to handle controlled/uncontrolled components (i'm generally forcing controlled components right now or iffy support for both)
• moving the "hover mode" functionality for tooltips into @react-md/utils and generalize it so that any component can hook into this. It'll be great for dropdown menus.
• fix the @react-md/menu package to no longer hackily use the keyboard movement API
• implement an easy way to change the default icons on all components with an IconProvider or something (have to create custom wrappers right now which is slightly annoying)
• integrate @react-md/tooltip into more components by default
• integrate pagination, async filtering (API calls), and accessible loading into the AutoComplete

[mlaursen]

Finishing up the @react-md/tree package took a bit longer than I thought it would since I forgot about the tree having access to all items and filtering out the "hidden" items during the render. This kind of went against the entire flow I had been thinking with the useKeyboardMovement, so I had to update the behavior a bit to work for filtered out items.

All said and done... I think it's turned out pretty well and a few demos/documentation are available here. I'll be adding two more demos to:

• show how to use a custom itemRenderer along with react-beautiful-dnd to make a drag-and-drop reorderable tree (this works even though react-beautiful-dnd doesn't support nested lists yet)
• creating a navigation tree/tree with links

So if things go well, I should release the v2.0.0-alpha.10 release Saturday when I've finished writing tests, remaining demos, and fixing the selected state not appearing on mobile until you blur the tree.

I can then start tackling the @react-md/sheet and @react-md/layout (!!) packages. Getting a bit closer to the final v2 release...

[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]

This update isn't super exciting, but I've worked on updating most of the documentation for how to actually use react-md v2. I added a whole bunch of guides that and fixed a lot of the installation instructions that used to exist. The good ol' Theme Builder is back as well (with no more screen flashes), but might need a few more improvements to help explain run-time vs compile time updates (maybe link to creating dynamic themes once I've written that instead). I also did some work on generating the "default" themes to be much quicker, so I can now generate the 2152 (or whatever the real number is) themes in about 1 min, 50 seconds instead of 3+hours (this is why I stopped at 8 themes). Probably overkill for all these themes though and should be reduced at some point. For reference, it's primaries.map(primary => secondaries.map(secondary => accents.map(accent => [createTheme(primary, secondary, accent, isLight), createTheme(primary, secondary, accent, isDark)])))

Otherwise, I added a few fixed for the Listbox/Select components (78af00f), added color a11y utils and fixed the default contrast ratio (6e92113), and a few changes for getting ready for tabs (06e0b18 883b11c).

The @react-md/tabs package is also probably 70% complete, but it's extremely verbose so I'm going to make the API better with an optional "controlled" version with React context that resembles how react-router does their Router + Route.

[mlaursen]

Completed the majority of the tabs functionality and went with a bit simpler of an idea than the Router + Route idea. https://react-md.dev/packages/tabs/demos There's also an example of how you can add swipeable tabs and why it's not part of the library (right now). I'm going to clean up the code a bit, test a bit more, and finish the documentation before moving on to the remaining @react-md/tables work. Once the tables are complete, I can add the SassDoc pages back and then move on to @react-md/expansion-panels. From there, it'll just be finishing up the @react-md/chip package, documentation, and figuring out if I left out major features or have outstanding bugs.

Darn. Looks like the swipeable example kind of breaks the default transitions. Might have to take another glance once I finish the other work.

[TriStarGod]

Please indicate on https://react-md.dev (preferably on all headers) that its for version 2. I was following https://react-md.dev/guides/installation and https://react-md.dev/guides/creating-a-new-app where the steps yarn add react-md that installed version 1.

[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

[mlaursen]

Sorry for the lack of updates due to holidays and vacation. I have done a lot more work and close to releasing the first beta (I released v2.0.0-alpha.12 on Saturday). Since the last check-in:

• Fixed the Dialog + Overlay portalling behavior
• Updated the base react-md package to also have a _variables.scss file in case you don't want to import everything from _mixins.scss
• Build speed performance changes in @react-md/dev-utils that changed the incremental build times from ~390s-500s to 170s-200s (clean build is ~340s while it was 700s before)
• Updated the base react-md package to now prebuild all color combination themes (2300+... I should figure out which ones are most used...) in about ~60s vs 3hours
• Started work for showing SassDoc again -- created a separate branch for this work since I realized I need some functionality from the @react-md/expansion-panel package which I haven't finished yet to complete
• Fixed the Tree component to scroll the active item into view when it is first focused (mostly mobile and keyboard behavior). Need to add scroll active into view on first mount as well though
• Added better keyboard focus behavior by re-implementing the default outline browser behavior but with box-shadow so it looks nicer and only in keyboard mode (opt-out-able)
• Fixed some link focus styles
• Fixed the Firefox only :focus styles for the <select> element: 5615ff5
• I got annoyed at icon usage and created an IconProvider that's built into the Configuration component as well to override all icon usage within react-md instead of having to create wrapper components each time: 014c13b
• Added an UnstyledButton component to the @react-md/button package: 313baf3
• Added a useIndeterminateChecked (naming is hard) hook for handling indeterminate checkboxes: d4946f7
• Updated the Listbox and Select components to allow a name attribute -- gets passed as data-name though: 4f43f8c
• Updated the @react-md/table api to be much more convenient (opinionated). https://react-md.dev/packages/table/demos
• Added the sticky headers to tables which is much better than in v1 since it's fully accessible without the weird hacks of multi-tables, margin offsets, padding, etc. Yay dropping IE11 support. This also allows for sticky cells horizontally instead of just headers/footers.

So what's remaining? I need to add a few more components to the table package for the other form components and/or update the documentation to show how you can add form elements and menus within tables. I'll also need to finish up the @react-md/chip package with the last few styling points and the work I started for the @react-md/expansion-panel package which is in a separate branch. From there, I'll start verifying that I haven't dropped support for anything major with the initial v2 release and go with the first beta. Once the beta has been released, it'll mostly be documentation updates and writing more tests since I've really just been relying on manual tests + typescript so far which isn't super great.

Since I've started getting to the scary part of side-projects where I'll start making excuses or finding "terrible" things that "need to be fixed" which will delay the release even more, I've started opening issues for these types of things so I remember not to solve them now and can be done at a later time. I'll be tagging them with the v2.? milestone. Hopefully things continue nicely and the first beta can be released before the end of January. I'm not sure how long it'll take for the official v2 release though since I'm still struggling with generating useful documentation from typedoc.

[mlaursen]

Completed the majority of the @react-md/expansion-panel package: demos. I think I'm going to rename the header prop to customHeader and headerChildren to just header after playing with it some more. It's also missing the secondaryLabel functionality right now, but not sure how important it is since it never worked well (in my opinion) on mobile.

Updated the positioning logic to support initial x and y values which allows for usage with pointer events. This lead to adding context menu support. Err.. Well playing with it again on a smaller desktop screen I might want to update it a bit more. It feels weird expanding past the cursor if the browser is too short.

I ended up changing how I do defaultProps and forwardRef since my first implementation doubled the React Dev Tools component tree with anonymous functions everywhere. The update should now show correctly named components without the anonymous wrappers. As part of this, I wrote a bunch of simple tests.

So this leaves finishing up the chip package and then releasing v2.0.0-beta.0 (switch from alpha. yay). From there, I think this is how I'm going to prioritize the remaining work for v2 release:

• write changelog for each package to help determine if there's missing functionality from v1 that I consider important
• finish sassdoc documentation to allow for the /sassdoc page for each package
• finish up some of the existing guides
• create a guide to fully explain the theming system in v2 since I think it's mostly just in my head right now
• get back into figuring out if typedoc is a good solution for documenting the component API and determine if having the /api route for each package is required for "successful" v2 release. I'd like to say it isn't since I've mostly been using the "Go to Definition" functionality in my text editor to determine component API while developing, but maybe that isn't a common flow or I should document that part more if I skip out on /api.
• release v2
• start scoping next minor releases for components/features that I didn't consider required for "successful" v2 release.

[mlaursen]

I think i finished the chip package and updated the demos accordingly. Also fixed some bugs with the autocomplete package (highlighting, keyboard movement with scrolling into view). Also fixed the custom keyboard movement to stop propagation since it lead to weird bugs when nested within complex components and some typescript definitions.

I released 2.0.0-alpha.14 which should hopefully be the last alpha version and have started working on writing the changelogs. I did say I was going to release the first beta by this point, but I'm a bit worried after finding the bugs with the autocomplete. If I don't find any terrible bugs or missing features while writing the first few changelogs, I think I'll release the first beta.

[zachsa]

Hi @mlaursen ,

Looking at the list of packages in the react-md.dev documentation and I see that there is no Grid / Cell components such as there were in V1. Will these be included in the V2 release? (or should I be handling responsive layout differently to wrapping in Grid/Cell components).

I am deeply appreciative of the work that you have put into this library! Thank you very much.

Looking forward to trying out V2!

[mlaursen]

Hey @zachsa,

The Grid/Cell components are actually available in the utils package.

• Material Grid Example
• Simple Grid List - this is a new "grid" system with columns being derived on max cell width and container width - I need to fix this a bit for OS that display scrollbars though

I think I'll have to update the documentation site a bit since I went package-based instead of component-based like V1. I'm hoping it'll be a bit better once I re-implement search and typedoc. These probably should have gone in layout instead, but it seemed best within utils for right now.

[zachsa]

The Grid List looks very helpful

[mlaursen]

Sorry for the lack of updates -- it's been quite busy lately and vacation. Since the last check-in:

• Starting writing changelogs for all the packages (think 15 out of 33 are completed)
• Fixed the GridList to work better on higher pixel density screens
• Found out I forgot to implement the text field messaging (errors, help text) and implemented a FormMessage component for allowing these help and error states to be read immediately by screen readers -> Simple Form Help and Error Messages
  
  
  
  • the API isn't super nice right now and I ended up wasting a bit of time trying to implement something with form validity. I ended up stopping for now since I spent too much effort on it but keeping it on the wip/validity branch to come back to later. I think it would probably be better to research more into existing libraries for form validation and add examples for that instead of reinventing the wheel especially since I have very minimal experience working with forms
  
  
• renamed some variables in the progress and transition packages for consistency
• other small bug fixes

Other notable changes:

I started the move of v1 from https://react-md.mlaursen.com to https://react-md.dev/v1 which should be live now. I'm planning on adding a message within the next few weeks to https://react-md.mlaursen.com about the move and then start redirecting after a month or so after that message is added. (Main reason for the migration is cheaper hosting and removing my name from the website)

Finally, added the SassDoc pages back which should be live: Form SassDoc for example.. Something that might be helpful is that the new SassDoc pages have a toggle to show the default compiled value for variables as well as some examples. I just need to create a combined SassDoc page like before at some point and re-implement the color preview within code blocks, but pushing it back since changelogs are more important.

So going forward, I'll keep writing the changelogs and determine if there's any other big features that have been missed in v2. I think all the packages I've documented so far have no major/blocking missing features but I'll post a combined list in this issue once it's all been documented.

[mlaursen]

I've completed all except for 5 of the changelogs now (alert, autocomplete, layout, app-bar, and card) but I have an idea about what's been changed. There are some missing features from v1, but I'm not sure how important they are so I'll list them out here:

• some of the styling functionality was removed if using the get*Style or get*ClassName props on a few components
• the menu components no longer support controlling the visibility with a visible prop
  
  
  
  • this also means the visible prop was removed from the AutoComplete
  
  
• the AutoComplete no longer supports value prop
  
  
  
  • this one seems kind like a blocker for v2 since I ran into some issues implementing the documentation site's search functionality with this
  
  
• the AutoComplete doesn't have a nice way to render non-searchable items
  
  
  
  • this is another thing I consider a blocker
  
  
• the layout package is missing the mini variants and some customization props
• dropped support for DatePicker, TimePicker, and Slider
  
  
  
  • this was expected and I am planning on implementing these after the initial v2 release
  
  
• removed the FileUpload component since I don't think it was actually useful
• alerts/snackbars can no longer be triggered without react hooks
  
  
  
  • this is an iffy one for me and might take some more research if it's considered a blocker
  
  
• dropped support for the BottomNavigation since it is now built-in to the AppBar
• removed the Version component/string since it was really only used for the documentation site
• removed the MenuTab component since it never really worked as intended, but should be easy to implement yourself if desired with the new components.
• removed the ListItemControl component so there's no built-in functionality for checkbox, radio, and switches with list item styles
• removed the TableCardHeader and TablePagination components
  
  
  
  • not sure how useful these were. The TablePagination never really worked as expected and can probably be re-implemented with the new sticky positioning of rows/cells in tables
  
  
• removed the EditDialogColumn functionality
  
  
  
  • this can be easily added back with the new FixedDialog and TextField component if it was actually used
  
  

I'll try to finish up the last 5 changelogs by the end of the week and re-evaluate the missing features. Right now, I feel _okay_ with most of this but I'd be happy to hear any other feedback if people are still watching this thread. Otherwise, if I did my logging correctly (edit: I did not count correctly at first) from the UMD bundles... here's some new functionality and highlights

• 134 exported components instead of 74 (excluding icons)
  
  
  
  • here's how I compared: react-md@v1 and react-md@v2
  
  
  • 1911 exported components if you include the default material icons with SVGIcon and FontIcon
  
  
  • actually added a default Link component for some default styles
  
  
• 49 new utility react hooks
• full Typescript support and all "documentation" should be available through your editor's "go-to-definition" functionality
• lots of temporary elements now automatically render themselves within the viewport: (menu, tooltip, fixed dialogs, etc)
  
  
  
  • this functionality is also available with a new hook: useFixedPositioning
  
  
• all components have been updated to act as "Native DOM elements" so that the ref is forwarded
• supports RTL languages by default
• lots of accessibility fixes and keyboard support
  
  
  
  • fixes "focus loss" when focus changed within temporary elements like menus and dialogs
  
  
• new theme api with CSS variables support
• all the default scss variables and their values are available through JS if you like css-in-js solutions
• lots of new utility mixins and functions along with built-in a11y color contrast ratio support (does slow down scss builds a lot within webpack builds though)
• easier to override styles since all styles should be overridable if defined after the react-md styles have been included
• no longer affects global elements with typography by default
• code splitting actually appears to work as expected with v2
• new interaction modes to apply styles only if the user is interacting with touch, mouse, or keyboard (means keyboard mode only focus styles by default)
• less distracting ripple behavior that now only appears on "click" (touch/enter/space/mousedown)
• quicker transitions by default which makes the app appear faster
• no longer requires weird workaround to work with react-router and updates not persisting to child components
• top-level configuration for icons, focus behavior, ripple effects, nested dialogs, etc
• much better table configuration and API that uses position: sticky for sticky columns
• additional customization for determining the current app size with mixins and components as well as hooks to access the current app size anywhere in your app
• another grid system
• interestingly enough, the gzip size of the UMD bundle has decreased from 101kb to 55b
  
  
  
  • this just doesn't seem correct though. react-md@v1 has a non-gzip size of 387 kB while react-md@v2 is 1.11 MB since it has all the additional icons. I guess switching from class components to functional components and the repetition make it compress better? this isn't in my knowledge scope
  
  
• the min and max css bundle sizes have decreased from 13.5 kB to 61 B - 76 B
  
  
  
  • once again, doesn't feel completely right. react-md@v1 has a non-gzip size of 98.9 kB while react-md@v2 is 116kB
  
  
• looks like there was a difference in the gzip and byte formatter libs I was using between v1 and v2. Running them both through v2 returns expected results:

$ dev-utils libsize --debug
v2 size
The gzipped UMD bundle size is:
 - dist/umd/react-md.production.min.js 55 B

The min and max gzipped CSS bundle sizes are:
 - dist/css/react-md.red-lime-100-light.min.css 61 B
 - dist/css/react-md.blue_grey-deep_orange-100-light.min.css 76 B


v1 size
The gzipped UMD bundle size is:
 - v1/dist/umd/react-md.min.js 47 B

The min and max gzipped CSS bundle sizes are:
 - v1/dist/css/react-md.blue-red.min.css 56 B
 - v1/dist/css/react-md.deep_orange-light_green.min.css 71 B

Phew. That makes more sense that there is a lib size increase.

[mlaursen]

All the changelogs should be completed except for the layout package and my previous message still reflects the missing features. I do think I'll need to add the support for the mini variants and additional customization to the layout package since it looks like I hacked this together just to get something renderable for the documentation site :/ Unfortunately this week will be a pretty busy at work so I'll probably be a bit burnt out and won't get to the @react-md/layout changes until this weekend or next week.

That being said, I do think I'm okay with having the missing functionality from the other packages added in a later release and have released 2.0.0-beta.0.

Additional notes:

I _did_ do a few breaking changes the last couple of days.

• menu's will no longer close when the browser is resized or the user scrolls the page. If you want this functionality, you'll need to enable the closeOnResize/closeOnScroll props instead (used to be disableCloseOnResize/disableCloseOnScroll)
• renamed these props on the autocomplete to match menus: disableHideOnResize/disableHideOnScroll -> closeOnResize/closeOnScroll
• changed the AppBar to have a single height prop instead of dense/prominent/derived. Valid values are: "none", "normal", "dense", "prominent", "prominent-dense" where "none" is basically height: auto
• renamed useCheckboxState to useChecked

I also fixed some of the SassDoc documentation to be be able to see how variables and mixins are used in other packages, added the first draft for using the sass exports to explain general conventions, fixed some keyboard focus behavior with the Sheet component, fixed the sandboxes to work when there were aliased folders, and other random documentation.

[mlaursen]

After thinking it over for awhile, my current goal is to release v2 June 13, 2020 or June 15, 2020 (June 13 aligns with https://react-md.mlaursen.com redirecting to https://react-md.dev/v1 permanently). Up until then, I am going to:

• ~see if I can finish removing react-transition-group as a dependency (only 2-4 more hours though)~ Save for a later time. This refactor is just because I do not like the new nodeRef API for getting around the findDOMNode issue and that most of the transition functionality has been ported as hooks into react-md
• start creating issues in GitHub for additional features and missing functionality in the initial v2 release and tag them with the v2.? milestone
• ~start closing current GitHub issues that were marked with v2 and comment about how it was fixed or implemented~ All have been included with the v2 PR
• ~create the full and combined release notes and publish somewhere in the documentation site~ Available once the v2 PR is closed and will be on a new blog page
• proof read current documentation site for any improvements
• ~give generating the component documentation another try with typedoc, react-docgen, or react-docgen-typescript~

Hopefully everything goes well and v2's new API/Components/Styling pros outweigh the cons of the missing functionality from v1.