[RFC] Increasing focus and iteration speed in convergence - Lean the Towers v2.0

[JustSlone]

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

Summary

Convergence is a challenging task we have ahead of us. This RFC intends to simplify the task by reducing the scope of convergence giving us focus on what matters.

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 /react-northstar, 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:

• Easy migration 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 and Cons

• 👍 Removes unnecessary blockers and work to allow partners to build on top of or move to converged components
• 👍 Allows users of Fluent UI React to get an early preview of work
• 👍 Gives the team a clear goal to focus our efforts on
• 👍 Allows us to learn faster by working with products early on components and taking them to production without a broad library upgrade
• 👍 Allows us to identify things we need to modify to address key scenarios earlier in the production of components
• 👎 Several small packages may prove difficult to manage over time, especially regarding when to major-bump them
• 👎 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?
• We need a story to migrate Teams 3rd party developers from /react-northstar to /react-*
• Can we align build for these components closer to repo in a box?
• Do we even need a suite package?
• We need a tracking wiki so folks know which components are converged and which ones are on deck, or not in plan to be converged

[JustSlone]

Edited open issues:
From:

• We need a story to migrate teams app developers from /react-northstar to /react

To:

• We need a story to migrate Teams 3rd party developers from /react-northstar to /react-*
  • For 3rd parties we probably need a suite package to make things simple

[paulgildea]

Added tracking wiki open issue.

[layershifter]

Dependent packages

• react-* packages cannot depend on either /react or /react-northstar

Currently react-button depends on a set of v8 packages:

fluentui/packages/react-button/package.json

Lines 50 to 59 in be53c0f

	"@fluentui/react-compose": "^1.0.0-beta.9",
	"@fluentui/keyboard-key": "^0.2.12",
	"@fluentui/react-icons-mdl2": "^1.0.0-beta.8",
	"@fluentui/react-shared-contexts": "^1.0.0-beta.3",
	"@fluentui/react-theme-provider": "^1.0.0-beta.13",
	"@fluentui/theme": "^2.0.0-beta.10",
	"@fluentui/react-hooks": "^8.0.0-beta.8",
	"@fluentui/set-version": "^8.0.0-beta.0",
	"@fluentui/style-utilities": "^8.0.0-beta.10",
	"@fluentui/utilities": "^8.0.0-beta.8",

What is our plan there?

Shorthand API spec

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.

I think that we missed a piece related to high level APIs, for example shorthands. IMO, it worth to have a separate detailed spec for this API and cover previous changes that happened before to provide some context about taken decisions:

• fix(factories): handle ReactElement as primitive fluent-ui-react#1513 - we decided to handle strings and JSX elements in the same way
• feat(factories): use children in shorthands as render props fluent-ui-react#1951 - we came with children function instead of render()

There are missing details about rendered output in each case. It will be also nice to cover differences from Northstar implementation if they exist.

Sub components and slots

Is there a clear decision about slots? I see currently two patterns when we have all subcomponents and only slots:

fluentui/packages/react-cards/src/next/renderCard.tsx

Line 12 in be53c0f

return <slots.root {...slotProps.root}>{children}</slots.root>;

fluentui/packages/react-button/src/components/Button/renderButton.tsx

Lines 14 to 19 in be53c0f

	<slots.root {...slotProps.root}>
	{loading && <slots.loader {...slotProps.loader} />}
	{iconPosition !== 'after' && <slots.icon {...slotProps.icon} />}
	{!iconOnly && <slots.content {...slotProps.content} />}
	{iconPosition === 'after' && <slots.icon {...slotProps.icon} />}
	</slots.root>

This creates inconsistencies, for example:

<Card>
  <CardBody>Body</CardBody>
</Card>

// vs.

<Button>
  {/* there is no `ButtonContent` */}
</Button>

Shorthand collections

Another missing piece is an API for shorthand collections:

<List items={["1", "2"]} />

In short, I don't like it. It provides us simplicity when we need to manage sub-components but it complicates components' usage.

Performance hit

<Menu
  items={[{ key: "home", content: "Home" }, { key: "about", content: "About" }]}
/>

To replace About with About us all Menu should be re-rendered. If we compare it with:

<Menu>
  <MenuItem>Home</MenuItem>
  <MenuItem>About me</MenuItem> // this can be a custom component to isolate updates
</Menu>

Complexity hit

It's hard to replace components:

<Menu
  items={[{ key: "home", content: "Home", children: (Component, props) => <MyMenuItem {...props} /> }]}
/>

// vs.

<Menu>
  <MyMenuItem>Home</MyMenuItem>
</Menu>

Inconsistent state flow

Another thing that we have often seen in Teams that it's hard to build and integrate custom stateful components, for example:

function CustomToolbar() {
  const [bold, setBold] = React.useState(false);
  const [italic, setItalic] = React.useState(false);

  return (
    <Toolbar
      items={[
        {
          key: "bold",
          active: bold,
          content: "Bold",
          onClick: () => setBold(a => !a)
        },
        {
          key: "italic",
          active: italic,
          content: "Italic",
          onClick: () => setItalic(a => !a)
        }
      ]}
    />
  );
}

All items should be prebuild in a single place in this case. However, I would rather have:

function CustomToolbar() {
  return (
    <Toolbar>
      <BoldItem />
      <ItalticItem />
    </Toolbar>
  );
}

This is actually closer to slots in React Spectrum and sub components in Reach UI.

---

Overall, it will be also nice to have something like Reach UI Philosophy.

[ling1726]

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 ?