search

aws-amplify / amplify-js

A declarative JavaScript library for application development using cloud services.
https://docs.amplify.aws/lib/q/platform/js
Apache License 2.0
9.42k stars 2.12k forks source link

RFC: Amplify UI Component Library Refactor #3279

Closed jordanranz closed 4 years ago

jordanranz commented 5 years ago

This issue is a Request For Comments (RFC). It is intended to elicit community feedback regarding a proposed change to the Amplify JS UI components. Please feel free to post comments or questions here.

Current state of Amplify UI Components

Amplify JS currently provides a library of UI components intended to help developers leverage Amplify categories such as API, Auth, Storage, Interactions and XR. These UI components are implemented in different modules based on a particular frontend framework. Currently these frameworks include:

The components provided by these modules are implemented in each respective JavaScript framework with duplicated logic. UI components are loosely styled using the Amplify UI style guide with some shared and some duplicated CSS. UI components are customizable but this functionality is limited and lacks parity between frameworks.

The Problem

This framework-specific approach has led to a variety of maintenance and extensibility challenges, including but not limited to:

The Proposed Solution

Overview

Currently, we plan to implement an Amplify UI design system using Web Components generated by StencilJS. We plan to refactor the current framework-specific component logic to alternatively use the logic implemented inside of web components from this design system.

Additionally, we will utilize CSS-in-JS to create a more flexible customization and theming strategy for components. We are evaluating the use of Emotion to build this strategy into our web components.

This approach has a number of benefits associated with it, including but not limited to:

Design Requirements

Related Github Issues

Customizable components

Component improvements

Related milestone: https://github.com/aws-amplify/amplify-js/milestone/13

ajhool commented 5 years ago

Note: all experience has been with the React components.

I'm glad to see that the team will refactor these components.

  1. Please try to add SSR compatibility into any new additions to Amplify. It does not need to actually render on the server, but please ensure that it does not break SSR. Currently the React Authenticator component breaks SSR and requires fragile workarounds

  2. The documentation is currently too sparse and unorganized. The documentation is all example-based and I've had trouble finding an explanation a simple, plain reference for the various props. The Authenticator props and design choices, in particular, are strange and unintuitive, so that component has been frustrating to work with despite being (arguably) the most important UI in any application.

  3. Typescript instead of javascript

  4. The Authenticator component requires passing in Components to the "hide" prop (eg. <Greetings />, <Loading />). It would be nice to just be able to pass in strings, (eg. ["loading", "greetings"]).

  5. Perhaps this is a more broad critique, but sometimes Amplify/AWS moves at break-neck speed to add features horizontally while leaving behind inexplicable functionality holes in core components. For instance, issue #104 (enable sign up using only email + password) hasn't been addressed in a year in a half. This framework has support for Alexa voice commands, but not login with email + password, that's hard to understand.

  6. Currently, the "Sign Up" Authenticator panel does not include the federated login buttons, but I believe that it should. Standard modern auth flow is to show the "Sign Up" panel as the default and encourage users to sign up with social login. If a user already has an account, they click the "I already have an account" button at the bottom.

jordanranz commented 5 years ago

Hey @ajhool,

Thank you for the feedback.

  1. Creating a smooth interaction for SSR is one of design requirements for this project. I have added this to the design requirements listed above. Using both StencilJS and Emotion should help us achieve this goal.

  2. Documentation will definitely be refactored over the course of this project. One big improvement we are looking to make comes with introducing the use of Storybook to our documentation. This will provide a lot more clarity to a user on how to use the component API and also even allow them to test the functionality our components.

  3. There is a design requirement to make this happen: "Components should be Typescript-compatible with well-defined and understandable typings". StencilJS generated web components are typed out-of-the-box, so this should be fairly straightforward with the current development plan.

  4. I will make note of this feedback and refer to it when building the new Authenticator web component. Passing a string array is a good idea but maintaining a string to component mapping might not be the most scalable option. Definitely something to look into more.

  5. Noted. This feedback is more focused toward the library/organization but we will definitely take this into account moving forward. Also FYI there is a PR for that specific callout: https://github.com/aws-amplify/amplify-js/pull/3103 :)

  6. Good comments and feedback. We can evaluate this when creating the new Authenticator component. Maybe have this order configurable where you can choose the order of your Authenticator flow (i.e Sign-up first, with a "I already have an account" link or Sign-in first, with an account sign up link).

ajhool commented 5 years ago

Thanks for the response and I look forward to contributing towards Storybook integration and Typescript compatibility, these are excellent tools!

Would it be helpful if I created a Storybook integration for the existing UI components? If so, would the team accept the use of typescript to build the storybook?

jordanranz commented 5 years ago

We would greatly appreciate the contribution of Storybook integration with our existing UI components and accept the use of Typescript to build this!

If this is something you would like to contribute, you can open a new issue to track this feature request/implementation and reference this RFC.

clementAC commented 5 years ago

Same note as @ajhool

Hi,

I agree with ajhool on all the points.

The doc is really great for a beginner with lot of exemples but once you try to make more complex uses cases there are some important points and props that are not documented. And searching in source code is quite annoying. Storybook or a similar product could be a good solution

I also agree on the amplify lib development "break-neck" thing. Sometimes I'm completely wondering why a feature is not implemented whereas it's a typical use case for a website. For instance, user administration, choose on wich s3 bucket I want to upload my files (default one or another one) and lot more and i'm not talking about visual components. I know that amplify is created for simplifying aws services access and adoption (and it manage to do it) but if the classical use cases are not taken into account then the point is completelly missed and sometimes amplify is making the service access more "frictional".

Everytime amplify is updated I'm wondering what have changed. With this new approach it could be an excellent idea to implement a changelog system. It will sure avoid some side effects du to upgrading the library in the future.

During the last month amplify have changed a lot and I think this proposition of refactoring is a great news for amplify developers and users.

ajhool commented 5 years ago

~Have started a storybook integration here: https://github.com/ajhool/amplify-js . If anybody is available from the Amplify team for a quick realtime chat this week to help me get oriented, I'd really appreciate it. After that, it should be ("should") relatively straightforward to build stories for each component~

buggy commented 5 years ago

@jordanranz What's the timeline on this like? I'm wondering if it's worth continuing with #2436?

jordanranz commented 5 years ago

@buggy, Shooting for end of the year release. I think your PR is definitely still worth it. I do not plan on removing aws-amplify-react and a lot of the work that has been done in that PR will be reused as we will continue to use those React components as wrappers.

jkeys-ecg-nmsu commented 5 years ago

@jordanranz @ajhool I think the tag "pending-triage" says it all. I'm asking for features all the time, as is much of the Amplify dev community. (I've also not yet contributed to the codebase directly. =/ ) My company is in its start-up cycle trying to make stuff that doesn't exist yet, so we tend to work around what isn't stable or working instead of relying on it being fixed in the next iteration.

Perhaps Amplify could break the traditional AWS mold by releasing a roadmap? This might also encourage more contributions from the community.

jordanranz commented 5 years ago

Thanks for the feedback @jkeys-ecg-nmsu. I think presenting more RFCs like this one is a step in the right direction for exposing a more public roadmap. We have also discussed presenting more granular roadmap items to the community but haven't settled on the best way to do this.

This being said, I don't want to stray too far off topic from the RFC being presented. I would love to hear more feedback about specific component customizations that Amplify UI users need or would like to be improved.

homerjam commented 5 years ago

Please focus on auth - the rest are nice to have, non-essential components. Look at Auth0 for an example of how slick you can make auth.

Please make the documentation framework agnostic.

Please add a note to the documentation about the lack of feature parity between the current frameworks and the timeline for the refactor.

I personally don't care for customisation too much - I think these components should focus on being reliable, universal and accessible. I'd like to be able to drop them in whilst prototyping and for them to 'just work'.

shicholas commented 5 years ago

hey @homerjam, shameless shout-out - I took some time and solved Auth w/ Cognito User Pools & AWS AppSync for React apps if you're interested.

If you are, please check out https://design.1337lawyers.com/?path=/story/authentication--setup and lmk how I can improve it. It uses Formik to wrap Auth calls, and exports a CurrentUserConsumer that uses the React context API to give you information about your current Cognito user when/where you need it.

homerjam commented 5 years ago

Thanks @shicholas! I made progress also, I eventually managed to get persisted federated sign in working with Nuxt (SSR) using a combination of Amplify, AppSync and deprecated Cognito libraries. Though having been through all that we're now dropping Amplify in favour of Prisma which I hope will be a better experience.

shicholas commented 5 years ago

nice sounds good. haha I hope Vue & React converge one day. There's good ideas in both and it'd be cool if it was all the same.

cliffordh commented 5 years ago

@homerjam what were your reasons for going with Prisma

undefobj commented 5 years ago

@cliffordh @shicholas @homerjam - This issue is for the team to get feedback on the RFC to improve the UI components for Amplify. If you have unrelated concerns/feedback/questions could you please move them to another issue or forum? Thanks much.

yareyaredesuyo commented 5 years ago

Yeah, Signup/Login UI customization is major problem (this maybe related to Cognito team?). It maybe great to implement Auth UI like UI Components.

The rest of things is trivial.

mbbillz commented 4 years ago

Semi related to #3358 & #3348 - it would be nice to be able to optionally exclude styles. When using the Authenticator component (aws-amplify-react), the styles that get included (which I do not use as am using custom components) take up nearly half of my final CSS 😞.

j0b0sapi3n commented 4 years ago

@mbbillz I have this exact same problem.

behivetech commented 4 years ago

I wish I was looking into this framework when this RFC came out; however, from my experience so far, which is fairly new and trying to figure this library out... instead of trying to build out all these forms for all the scenarios in React which has huge limitations such as wanting to use Material Design styled components instead of what's provided and having to build out an entire component with all the functionality just to replace the SignUp component for instance, why not go with an AuthProvider component where things like signUp, signIn, etc. functions along with other needed values from the provider's state can just be pulled out of the provider with useContext. This way only one component needs to be managed and documented. This leaves the rest of the UI for styling, special needs in functionality, etc. left to the user's discretion.

mbbillz commented 4 years ago

@bruqui's solution sounds really neat!

behivetech commented 4 years ago

It's not far off from what the combo of React Apollo and @apollo/react-hooks do really. In fact, following that pattern all together would probably be the most ideal by also providing different kinds of hooks that seem to make the most sense for the provider component.

m8schmit commented 4 years ago

Hi, following the discussion here : https://github.com/aws-amplify/amplify-js/issues/4515#issuecomment-575290910

can you add this to your things to do on amplify-ui : currently you use var() to handle colors but the css variables aren't supported by IE11.

(@ericclemmons, tell me if it's enough or if i have to open a specific issue and link it here. )

Thanks !

Rafcin commented 4 years ago

This probably isn't right but as of now I think in terms of signup/signin forms aren't all bad. The default auth ui sucks but you can easily make your own! I Found using formik works well for auth forms, it's simple where you can make checks for basic things like "is it an email" or "is it a zipcode", but what I think would be nice is a way to check something like isValidPassword() for when you login because while the auth form handles all this, not all people want to use it. In my case I use filepond for uploading files, and I can't do that with the auth form, so these tiny details would be nice.

Or add a component that's highly customizable.

A side suggestion would be to change the community channel Glitter to something like Slack. One major problem is if you want to search something it's almost impossible on Glitter. Some things on the wiki are not up to date or complex and when someone explains it it's impossible to find and or the chat is dead and no one really has a solution. I think Slack or some other program would be nice and it would allow us to easily communicate, possibly track issues from Slack or discuss problems and solutions with AWS devs and the community.

mayteio commented 4 years ago

Is there a list of issues related to this RFC, or is it still in discussion? I'd love to start contributing and it would be awesome if related issues could be triaged with a label for it and good-first-issues too.

ProdigySim commented 4 years ago

We used amplify-react, then amplify-react-native, and then built a custom UI for the next project.

There are so few AmplifyJS API calls needed for each auth component that I'd rather see good documentation on how to set up an "Authenticator" yourself. Handling auth state changes + specific API calls to do Signin, forgot password, etc.

Building a signin form is not hard. Handling Amplify's auth flows properly is. Help us model our UI in the correct form, but don't make us try to customize a premade one.

jordanranz commented 4 years ago

Amplify UI Component (Preview)

Hello all,

Wanted to provide an update on the status for this project and give an overview of the phases we are planning on releasing in the near future. As mentioned above in this RFC the problems we wanted to solve for this project included:

Phase 1

In Phase 1 of this project we will seek to solve or at least alleviate all of the problems listed above. To achieve this we will be releasing a brand new web component library and new libraries for each of the frameworks that we currently support. The framework libraries will include React, Angular, and Vue and these will be generated based off of the code in the core web components library. The original component libraries offered in the current release of amplify-js will go into maintenance mode and we will no longer be adding features to these libraries. For customers using the original React, Angular, or Vue component libraries, we will be providing migration guides for those looking to migrate to using the new components. Phase 1 is complete when we are at feature parity with the original UI component libraries.

Here is a breakdown of the new libraries being added:

Framework Package Version
React @aws-amplify/ui-react version
Angular @aws-amplify/ui-angular version
Vue @aws-amplify/ui-vue version
Web Components @aws-amplify/ui-components version

The amplify-authenticator component is currently available for preview using the tag ui-preview. For more information about using the new amplify-authenticator component and getting started with the Amplify UI Component library check out the README here.

For feedback and feature requests related to this preview release please open a new issue in our issue queue and add the label: Amplify UI Components. Also, feel free to comment below on this RFC.

Phase 2

Once our new UI component libraries are at feature parity with the original libraries, we will move on to Phase 2. In this phase we will be looking to address the comments and requests presented in this RFC. I really like the ideas presented here especially the one about offering an AuthProvider “renderless” component mentioned in @bruqui‘s comment. Interactive and better documentation as @ajhool mentioned is also something we will be looking to support.

In addition to addressing the comments in this RFC, we will also be doing a retro on the issues and feature requests in our queue related to UI components. This milestone will be used to track the progress for these.

Phase 2 may also include new components from other Amplify categories like Predictions or API. If anyone would like to contribute ideas to what components you’d like to see added in the future please post it in this RFC or open a new feature request with the Amplify UI Components label!

Thank you!

The feedback that you all give is extremely helpful and gives us a better understanding of what people want us to build. Go ahead and try out the new component libraries and let us know what you think.

jordanranz commented 4 years ago

The Phase 1 of the post I made above has been released for the Auth category components!

Here is the blog post: https://aws.amazon.com/blogs/mobile/amplify-framework-announces-new-rearchitected-ui-component-and-modular-javascript-libraries/

Here is our new preview Docs: https://docs.amplify.aws/ui

We will now be working on adding additional category support for Storage, API, etc. and then moving on to Phase 2. I am going to close this RFC now. Thank you everyone for the feedback on this Issue!

Cheers 🍻

github-actions[bot] commented 3 years ago

This issue has been automatically locked since there hasn't been any recent activity after it was closed. Please open a new issue for related bugs.

Looking for a help forum? We recommend joining the Amplify Community Discord server *-help channels or Discussions for those types of questions.