search

microsoft / fluentui

Fluent UI web represents a collection of utilities, React components, and web components for building web applications.
https://react.fluentui.dev
Other
18.59k stars 2.75k forks source link

Documentation is very confusing #13200

Closed Pearseak closed 3 years ago

Pearseak commented 4 years ago

I'm angular material web dev trying this fluent UI react but I found this framework is very confusing.

  1. What are the differences between Fluent UI React and Fluent UI Northstar? They have separate docs if they are sperate lib why bother putting them in the same readme.md or they aren't??? submodule?? I don't know.

  2. https://developer.microsoft.com/en-us/fluentui#/styles does not have any actual usage example and most of them don't even work if I just "npm install @fluentui/react" which is the only instruction in "Get started Web".It took me 2 days before I found out that I can't use Grid and I need to use Stack.

  3. Fabric core and Fluent UI are not interchangeable. Why do you put their docs together under web tag, it very irritates me because I don't know which part of them are not intersect

  4. I saw at least 3 different lib was import office-ui-fabric-react, @uifabric, @fluentui dude....seriously..

  5. how can I add animation to "Controls" should I use that class in motion docs? what about that react var? where should I put them? do they have token or I can just shove them in css file? or should I use standard css animation?

just a note from someone who came from different framework entirely

kaplas commented 4 years ago

I'd like to confirm @Pearseak 's observations. I looked into your Fluent/Fabric/whatever React controls in the spring, and thought I would like to use those in a project. Now when a suitable project started, everything regarding the documentation, what package to use, and so on seems really confusing.

ecraig12345 commented 4 years ago

Sorry about the delay, thought I'd responded to this one (we did talk about it internally) but I guess not.

  1. @fluentui/react version 7 is what used to be known as Office UI Fabric React. It's widely used in Microsoft products and some outside. @fluentui/react-northstar (sometimes also called Fluent UI React v0) is what used to be known as Stardust and is mostly used by Microsoft Teams and Teams add-ins. They're in the same repo because we're working on converging them. More on that here.

    If you're wondering which one to use, the short answer right now is that unless you're developing for Teams (or making a chat/video-centric experience) you should use @fluentui/react, due to its more stable API (@fluentui/react-northstar due to being v0 may have API breaks in monthly minor releases) and wide usage.

    Related to this, we have issue #13125 about updating imports in website examples to be from @fluentui/react, and #13283 about updating the wiki to point to the contributing docs specific to @fluentui/react-northstar. I also just made #13381 about updating the main repo readme with more info about the distinction and what to use when.

  2. Sorry about the confusing info on styling! This is definitely something we need to improve. I made #13380 about Stack vs grid and #13382 for more general issues.

  3. It's possible to use Fluent UI React and Fabric Core together, but I agree we should have clearer guidance about what to use when and the lack of feature parity. Made an issue #13383 about this.

  4. The different package names and scopes are essentially for historical reasons:

    • office-ui-fabric-react is the old name of the package now known as @fluentui/react. At one point all the code that's now in sub-packages lived here before it was converted to monorepo/multi-package structure.
    • @uifabric packages are the sub-packages of office-ui-fabric-react (now @fluentui/react) that we added after converting to monorepo structure, but before the Fluent UI rename. (We'd probably like to move these to @fluentui scope but this may not happen immediately--see #13384).
    • @fluentui is the new scope that we want all packages to live under. New sub-packages for @fluentui/react and the eventual converged library are being created under this scope, but it also contains some sub-packages which are currently more specific to @fluentui/react-northstar (generally these are the ones that live under packages/fluentui in the repo--this is a distinction we need to clarify better in the repo readme).
    • The examples on the website need to be updated to import from @fluentui/react rather than office-ui-fabric-react--there's a work item #13125 for this.

  5. We don't have a good story for adding animations to controls right now. This has been discussed under #9863 but was never resolved.

marcosteam commented 4 years ago

Yup, the document is very confused.I don't know how to get the point.

msft-fluent-ui-bot commented 3 years ago

Because this issue has not had activity for over 150 days, we're automatically closing it for house-keeping purposes.

Still require assistance? Please, create a new issue with up-to date details.