Closed mlaursen closed 5 years ago
@mlaursen Than you for all the great work with React MD!
I have been researching the topic of material-components-web today, the https://github.com/material-components/material-components-web-react is very small. Much more complete is unofficial implementation https://github.com/jamesmfriedman/rmwc The author has described the projects goals at https://jamesmfriedman.github.io/rmwc/methodology
Going typescript sounds great. Have you heard of flow types? https://flow.org/en/ https://github.com/flowtype/flow-typed/blob/master/README.md
thank you for making react-md possible in the first place
@mlaursen This is a great read! I 💯% agree with you on how important customizability and accessibility ♿️ are. If you want to keep having fun while learning, you are welcome on Material-UI side.
Sorry for the lack of updates -- I'm going to be closing this one if favor of the newer sticky issue #826 which has some more updates and the remaining todos
react-md progress
react-md has come a long way since starting out at v1.1.0 which was released December 2016. During this time, it has gained a lot more visibility and popularity getting ~4.3k downloads per week and 45 contributors (but not always active). Unfortunately my contributions have dropped by a lot during these last months due to being overworked with full time job, real life events, and side projects. So to help get things going again, I am going to be laying out a new roadmap to get things going and hopefully encourage more contributions.
Right now, the issue list keeps growing without an end in sight which makes it hard to feel motivated to work and fix on something. I also have not been keeping up with actively labeling, commenting, and thinking through issues so it is harder for people that would like to contribute to be able to find a good place to start.
Brief History
react-md was created because I wanted to learn Javascript, React, Sass/SCSS, CSS, and accessibility as well as a cool project to work out. I found out about the material design guidelines and checked out the 2 big react implementations of these in react:
At the time, material-ui was working with all inline styles which I found terrible to work with and react-toolbox did all their styles with css-modules. react-toolbox was closer to what I was wanting to work with, but I didn't feel like there was enough customization/easy enough for me to learn with my existing knowledge.
At this point, I decided to learn everything and write my project from scratch since I didn't think it would ever take off. The first pass of react-md was to match the material design specs as closely as possible and add basic accessibility into it. This was really great if you wanted something to "look like Google" or another typical material design website, but it made adding custom branding really hard. To help with this, I released 1.1.0 which helped set the material design styles to be
!default
so they could be overridden, but it still made things a pain and couldn't update everything.Now I started realizing all the problems that went into how I designed the components the first time and it is very hard to customize things without needing to re-write them when using react-md. For example, one annoying thing is just trying to create a custom dialog in react-md; it is really not possible if you do not want to use the general layout of the dialog. The reason this happened is because I had 0 real world use cases or examples of using react-md.
During this 2 year development, Google has also been actively updating and creating material-components-web which adds the base styles and framework-independent javascript required to get a material design website rolling. They have also started work on material-components-web-react, but the progress seems to be really slow.
There have also been some other feature requests like Flow and Typescript support which have come in, but right now I am only actively supporting Typescript.
material-components-web/material-components-web-react
I still think that it will be better to get users to migrate over to the Google's official implementation instead of mine, but I still want to learn and play with this library so I'll keep going. My library might be faster than the official material-components-web-react implementation, but who knows?
Goals
Now that I have been working on this for awhile, I want to redefine and list out the goals for this project. These are personal goals that I believe to be the most important.
Customization
As listed above, things are tied way too tightly to material design. It is a neat design ideology, but that doesn't mean it should be applied 100% to every single app that is ever created. This will be really hard since customization is always difficult to do with all the different use cases, but I can start thinking about this now to help make it easier as time goes on.
Accessibility
Accessibility is going to be the second biggest thing I want to come out of this library as it will give me a step-up compared to the others. They have recently started adding accessibility support, but I want to stay a step ahead. Some things in the future I want to add are more accessibility helpers and following the accessibility specs a bit better so that screen readers can immediately get updated with information as needed. I'll go into more details about this later. The other thing I would like to try adding is some sort of color/contrast accessibility helper in SCSS or JS that can help warn about contrast problems. I want to search for existing solutions before implementing my own though.
Contributions
I need to figure out a better way to make my project easier to contribute to as well as making people want to contribute. I've probably turned down a few PRs that could have been great additions because of some small details. In addition, I've tied everything to my own name (website, github, npm), so it might not be as "exciting" as a contributor to contribute to something right under my name.
Roadmap
So with all that said, here are my plans without any deadlines yet.
Drop < React@16.3 and deprecations
I can reduce the bundle size by a pretty decent amount if I can drop all the old deprecation warnings that have been added starting with the v1.0.0 release. I'll need to be careful and write a changelog/migration guide while removing them.
I can also stop patching React API changes from 15 -> 16 to reduce the bundle size and remove the old unsafe way to render portals
Typescript Support
Right now, Typescript is an afterthought and I keep on needing the active Typescript users to open PRs to fix my bad typing. To help solve this, I've decided to finally start learning Typescript and rewrite the components using Typescript by default. This will allow for the definition files to automatically be created when compiled to
commonjs
orcommonjs + es6 modules
as well as having more sight on how components are used and how the typescript definitions should be defined. Since this will take a long time, this will lead to part 2 of this step.modularize react-md
Another big problem with react-md right now is that ES6 modules and tree shaking does not work (#587). This is actually a huge problem in how I setup my code structure and import different files and is not an easy fix. This leads me to want to follow material-components-web and their modularized structure.
@react-md/accessibility
A module for only accessibility helpers. So this would be things like
AccessibleFakeButton
,FocusContainer
,Listbox
,ScreenReaderAlert
, etc.@react-md/avatar
A module for just avatars.
@react-md/autocomplete
A module just for autocompletes. This will also include updating the keyboard and accessibility behavior so that the using the up and down arrow keys will not actually focus the element, it will only apply a selected state. This will fix some of the keyboard problems happening.
@react-md/badge
A module just for badges.
@react-md/bottom-navigation
A module only for bottom navigations.
@react-md/button
A module only for displaying buttons. Part of this initial change is to change how the different material design button specs are applied. To make things less confusing, buttons are going to be raised by default since the
<button>
tag looks raised to be with default browser styles (to me). I'm up for doing flat by default if there are more desires for that.@react-md/card
A module for rendering cards. This will include the different card parts required.
@react-md/chip
A module for rendering chips.
@react-md/data-table
This one is still a bit iffy to me how I want to do it. I might create another basic
@react-md/table
module that will just provide:Table
TableHeader
TableBody
TableFooter
TableRow
TableCell
and then the
data-table
package that will add additional functionality to tables like creating selectable rows, adding fixed headers and footers, etc.@react-md/dialog
I want to change this up a bit and maybe also create
@react-md/modal
. Right now, the dialogs are set up to requiretitle
and some other props to automatically add accessibility and labeling things, but it makes it a pain to create a dialog with a different layout. The plan right now is to exportDialog
- the static dialog container that only renders childrenDialogContainer
- a wrapper for theDialog
that will only render theDialog
when the visibility istrue
DialogHeader
DialogTitle
DialogContent
DialogFooter
DialogActions
@react-md/divider
A simple package for only rendering dialogs.
@react-md/drawer
The drawer needs to get remade a bit to make the
navItems
easier to update as well as adding better mini variant display.@react-md/expansion-panel
This will just export the
ExpansionList
andExpansionPanel
components.@react-md/file-input
This will just export some more customizations for the
FileInput
andFileUpload
components.@react-md/font-icon
@react-md/svg-icon
@react-md/icon-separator
@react-md/icons
These three are related.
@react-md/font-icon
will only export theFontIcon
component and base icon styles.@react-md/svg-icon
will only export theSVGIcon
component and any additional styles needed for svgs only. Finally,@react-md/icons
will just be a simple build script that will compile all the open source svg icons from material design icons to create SVGIcon implementations with both spritemap and inline-svg support.@react-md/grid
This might be renamed
layout
later, but who knows. This will export the styles for grids and theGridList
,Grid
, andCell
components.@react-md/ink
This will be an updated ink implementation. When this is done, it should fix the existing ink issues and allow for easier ways to disable ink.
@react-md/link
Add default link styles and a way to work with react-router.
@react-md/list
This will contain the
List
,ListItem
, andListItemControl
components. I'll need to make sure thatListItem
isn't as ridiculous to use right now and add easier react-router support.@react-md/magic
(not really, maybe positioning or layover)This will be for the more complex components that determine how to render a fixed element on the page. Right now this is only the Layover component.
@react-md/media
This is pretty good as is, but needs to add support for not enforcing aspect ratios better so that the native aspect ratio can be preserved for better at-a-glance thumbnail sizing.
@react-md/menu
This should be the
Menu
,DropdownMenu
, andMenuButton
components. With this pass, I will need to add support for portaling the menu for better integration with react-virtualized.@react-md/navigation-drawer
I might end up renaming this to
Layout
or something else, but haven't decided. When this is updated, there should be better media queries implemented and easier ways to determine device size.@react-md/paper
Simple module for elevation/box-shadow. I might rename this to
@react-md/elevation
.@react-md/picker
@react-md/date-picker
@react-md/time-picker
These 3 are related again and lots of bugs related to them (good write-up #677). This should add easier ways to format the dates.
@react-md/progress
This is pretty good so far. It should eventually support a horizontal LinearProgress, but that won't be for a bit. When re-making this, I should also check to see if there is a more performant way to create the circular progress. #697
@react-md/portal
This component isn't as helpful as it used to be now that React has created the
createPortal
API, but this is still nice if you need to dynamically create portals and creating new DOM nodes to insert them in.@react-md/resize
This will be about general resize event listeners for the page, or specific elements.
ResizeObserver
- track resizes for specific elementsResizeListener
- normalize window resize behavior across all browsers and devices #684@react-md/select-field
I need to update this in a lot of ways, but I'll start by fixing the keyboard handlers a bit just like the autocomplete.
@react-md/selection-control
The biggest update for this group of components is that I now plan to make the icons only happen through styles instead of adding another icon inline to determine the "checked" state. This will make it so the
Radio
component actually works without using a selected state wrapper (like theSelectionControlGroup
. It will make it a bit harder when using svg icons, but it isn't too bad. More details later.@react-md/slider
This is pretty decent right now. Eventually add better vertical support, but won't happen for awhile.
@react-md/snackbar
When remaking this one, I want to follow the accessibility rules better. #459
@react-md/subheader
A simple module for subheaders. There isn't too much in this one.
@react-md/tabs
Well... This one sucks. I also haven't given it much thought yet as I don't have to create tabs in work yet. When it gets closer to this component re-write and fix, I might have more details. There are just a lot of problems with tabs right now.
@react-md/text-field
This will just be for creating the text field component. Something that might be helpful is to create another module for labels, errors, and messages for form fields. Maybe go with
@react-md/form-controls
or something like how bootstrap did it.@react-md/toolbar
Toolbar is pretty decent right now since you can ignore the strictness of it by only using the
children
.@react-md/tooltip
I want to re-write tooltips to be portalable or maybe even portal by default to get a lot of rendering issue bugs out of the way. I am hesitant to make them portal by default since there were a lot of bugs in the first pass of react-md for that. Hopefully my experience and use cases have increased since then and I can think of reasonable defaults.
@react-md/typography
This will be completely new and one of the easier ones to create. This will implement a helpful
Text
component that will just render a text string or wrap with an html element and apply the correct class names. Here is my first implementationThe biggest change about this is that I will be removing all html tag typography styles. The h1, h2, h3, h4, h5, h6, p, and caption will no longer have styles applied by default. In addition, every single element will not gain the font-family. You will need to add
md-typography
onto thehtml
tag, or manually applymd-typography
to elements. This is more to match how material-components-web works.react-md
Finally, there should still be a base
react-md
project that is just a concatenation of all the modules listed above so that you still have the option of being lazy and just doing:But... why?
Since this is a ridiculous rework and will take time, the modularization seems like a great idea to me. While I am remaking these components, I am able to individually release these sub-packages with so that users that want the latest and greatest can get them asap. It also means that the general users won't notice anything new until I finally get to releasing the next major version of the base
react-md
. I think that the modularized approach will help make things seem like they are going faster.create-react-md-app
We won't get too serious here, but would be nice to have something like
create-react-app
andcreate-next-app
but for react-md. To get started, I will just go with how create-react-app does it and do the few additions in the old examples folder. So we would have a create-react-app but updated a bit.The first implementation would basically be
create-react-app --scripts-version=react-scripts-react-md
and a completed version of the with-create-react-app exampleThe second implementation would be the typescript version.
It would be cool if I eventually made it like
create-react-app
where it'll find one of the examples in the examples folder and pull that down, but that'll be way down the road.Component Roadmap (somewhat in order?)
Increasing Contributions
This one will be a bit tough to come up with a solution for. I think I'll have to start with re-writing the contributing examples and guide to make it easier to pick up. There are also a lot of weird things that happen with my documentation server that need to be fleshed out.
Eventually I might want to also look into creating a react-md github user/company to move the project to as well as moving away from my mlaursen.com domain, but I still would like this to feel like my personal project.
Documentation Updates
I would eventually like to start supporting multiple languages for the examples and prop types, but that should be way down the road. With the re-write, I would at least like a skeleton for how I could implement the translations down the road.
In addition, I would like to update the code examples. I should either link to the entire folder on Github for the example or start using the Tabs component to make an "in-browser" IDE so that it is easier to see all the files at a glance that were used.
Finally, I would like to add a "live editor" page that will allow users to play around with all the components in react-md as well as all the documentation-only components/utils. I think first pass will just be linking to the react-md issue template codepen and let them play there.
Timelines
This section is still to come. Trying to get motivated again, so doing it in small steps.
If anyone reads this and has any better suggestions or big red flags, feel free to comment and let me know. This is a big project and I'm mostly going on personal preference so I could be thinking about things wrong. I could also be missing the immediate features that the general user of this library want, so please let me know.