search

mlaursen / react-md

React material design - An accessible React component library built from the Material Design guidelines in Sass
https://react-md.dev
MIT License
2.33k stars 302 forks source link

v2 Status #826

Closed mlaursen closed 4 years ago

mlaursen commented 5 years ago

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.

General removals / renaming:

What's the biggest change?

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

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:

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:~

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 commented 5 years ago

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

markdon commented 5 years ago

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

mlaursen commented 5 years ago

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:

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 commented 5 years ago

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 commented 4 years ago

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:

stickfigure commented 4 years ago

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 commented 4 years ago

@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 commented 4 years ago

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:

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

mlaursen commented 4 years ago

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:

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 commented 4 years ago

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:

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:

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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:

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 commented 4 years ago

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:

mlaursen commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

Hey @zachsa,

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

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 commented 4 years ago

The Grid List looks very helpful

mlaursen commented 4 years ago

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

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 commented 4 years ago

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:

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

$ 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 commented 4 years ago

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.

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 commented 4 years ago

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:

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