RFC: Your proposal name here

---

contributors: @khmakoto @xugao @miroslavstastny @jurokapsiar @dzearing @levithomason @paulgildea

Summary

This RFC covers a proposal for a process to track and bring clarity to the engineering work required to build a Fluent UI Next component

Background

We have been working for a bit on convergence and leaning the towers between libraries formerly known as Stardust and Fabric. We've made good progress on defining the component model to use, and are now making progress on styling and theming components built upon it.

Problem statement

The larger problem we face is mostly one of time, scope, and focus. We need to deliver a substantial set of converged baseline components to partners that work in both Teams and Office applications. To succeed here we need to improve our focus and iteration speed.

We were planning to converge through building new converged components and folding them back into both /react-northstar and /react libraries. Folding these components, concepts, and utilities back into both libraries, however, is difficult, time consuming, and results in challenges for the Teams application.

In general, we realized that while possible, folding converged components back into /react-northstar and /react seemed like a distraction and an unnecessary step that just perpetuates the two separate libraries.

Proposal

We propose that instead of growing /react and /react-northstar to be similar over time, we simply focus on creating an independent set of converged components. These components can later fold into /react to ship to the masses, but the near-term focus should be on unblocking partners with independent components. These components are not a re-write, they will bring forward the work already done in Fabric and Stardust. They also will work well in existing Fabric or Stardust based applications. However, they also will function independently of either existing library, and not require a particular version of /react or /react-northstar.

Requirements

This independent set of components must support:

• A documented migration plan from existing /react and /react-northstar components
• Partners must be able to pickup and use new converged components without needing a particular version of /react or /react-northstar
• react-* packages cannot depend on either /react or /react-northstar
• Styling and theming stories are supported in both Teams and Office products and there is a path to address previously supported scenarios
• Improvements must be tangible when compared to previous offerings in at least one of the following ways:
  • Bundle size
  • First-render performance
  • Re-render performance
  • API cleanliness

Details

1. We will produce a new set of component specific @fluentui/react-* packages. This is like we did for react-button.
2. These components will be made available to partners for integration into early scenarios, often with our assistance.
3. We will make early use of these components to vet the model, iterating as we get feedback from partners.
4. We will publish information on these components on a documentation site (TBD). Along with the current status (Experimental, Preview, Stable).
5. [Optional] Once these components are stable, we can choose to fold them back into the /react suite package for distribution to broader consumers of @fluentui/react
   • Note: We don't have to close on this decision today, consuming individual packages has many benefits, if it works well for partners and 3rd parties we could always keep it. If it doesn't, it's easy to later fold these packages into a suite.

Visual representing this:

Things we'll stop

• We will stop integrating the new component, styling, and utilities into /react-northstar and /react
• We will stop using /react as the ship vechicle for converged components

Things we'll start

• We will focus and put a majority of our engineering effort on our converged utilities and components via /react-* packages
• We will start engaging with partners and support building components using converged components

Things we'll continue

• We will continue to support existing customers of /react and /react-northstar
• We will use /react as an eventual ship vehicle to reach the breadth of existing customers, but only once components are stable
• We will help and support migration from /react and /react-northstar to new /react-* components

Pros

• :+1: Removes unnecessary blockers and work to allow partners to build on top of or move to converged components
• :+1: Allows users of Fluent UI React to get an early preview of work
• :+1: Gives the team a clear goal to focus our efforts on
• :+1: Allows us to learn faster by working with products early on components and taking them to production without a broad library upgrade
• :+1: Allows us to identify things we need to modify to address key scenarios earlier in the production of components

Cons

• :-1: Several small packages may prove difficult to manage over time, especially regarding when to major-bump them
  • Issue here is that Major bumping shared utilities will force everything that depends on them to bump. This leads to unexpected and potentially confusing major bumps on packages that don't contain changes.
  • It's also would become difficult over time to communicate which versions of packages are compatible with each other
  • This con can be avoided by using Lockstep versioning on all packages and releasing them together
• :-1: To stay on the cutting edge requires customers to import from multiple packages

Open Issues or follow up

• We need a documentation solution. new UX docsite? storybook? northstar docs?
  • Storybook for inner dev loop and internal partners during bring up
  • New Fluent UI Website for public experience
• We need a story to migrate Teams 3rd party developers from /react-northstar to /react-*
  • Yep, we will need a story, not now though
• Can we align build for these components closer to repo in a box?
• Do we even need a suite package for converged components?
  • Seems like yes, not strictly required though
• We need a tracking wiki, storybook, or other way for partners to know which components are converged and which ones are on deck, or not in plan to be converged
• What about utilities/libs that will be shared by react-* packages ? How will we avoid adding confusing/ambiguous package names that might simply be a carbon copy of existing utilities that are shared by v8 and v0 ?
• Currently react-button depends on a set of v8 packages
  • We need to update it to not depend on v8 packages