RFC: Docs Component Definition Section #28325
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Perf Analysis (
|
| Scenario | Render type | Master Ticks | PR Ticks | Iterations | Status |
|---|---|---|---|---|---|
| FluentProviderWithTheme | virtual-rerender | 71 | 66 | 10 | Possible regression |
All results
| Scenario | Render type | Master Ticks | PR Ticks | Iterations | Status |
|---|---|---|---|---|---|
| Avatar | mount | 620 | 587 | 5000 | |
| Button | mount | 302 | 303 | 5000 | |
| Field | mount | 1058 | 1074 | 5000 | |
| FluentProvider | mount | 663 | 639 | 5000 | |
| FluentProviderWithTheme | mount | 75 | 77 | 10 | |
| FluentProviderWithTheme | virtual-rerender | 71 | 66 | 10 | Possible regression |
| FluentProviderWithTheme | virtual-rerender-with-unmount | 71 | 74 | 10 | |
| InfoButton | mount | 11 | 10 | 5000 | |
| MakeStyles | mount | 857 | 854 | 50000 | |
| Persona | mount | 1657 | 1653 | 5000 | |
| SpinButton | mount | 1295 | 1319 | 5000 |
|
This pull request is automatically built and testable in CodeSandbox. To see build info of the built libraries, click here or the icon next to each commit SHA. Latest deployment of this branch, based on commit 471a09a:
|
📊 Bundle size reportUnchanged fixtures
|
Asset size changes
Baseline commit: 915acd693ae5c9ad8995d0cb952e804e9fd3e120 (build) |
🕵 fluentuiv9 No visual regressions between this PR and main |
🕵 fluentuiv9 No visual regressions between this PR and main |
|
@tudorpopams is going to review this on behalf of @microsoft/cxe-prg and @microsoft/fluentui-react-build |
|
I will do a more thorough audit to find out the consequence on implementing this across all components. |
levithomason
requested review from
behowell,
khmakoto and
sopranopillow
as code owners
|
@miroslavstastny will review on behalf of @microsoft/teams-prg |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Current Issue
Our React v9 stories currently include a lot of boilerplate and configuration in addition to the base functionality provided by the component. This makes it difficult for consumers to understand what React v9 components are providing and what they can do with them.
Consumers visually scan our docs, look at often customized implementations of our components, and get the wrong impression. They sometimes think we offer overly specialized components for Office cases only. It is not clear what part of our stories are provided by v9 itself vs which parts are provided by the customized story implementation details.
Example, Card specifically was reported to me as "not fitting our use cases at all" by more than one partner. This is because the Card examples appear to be very specific Office cards. However, the v9 card is simply a container component with minimal styles. It also includes a couple layout slots and a horizontal/vertical variation. It fits a vast number of card cases, but our current docs do not show the base Card capabilities. We only show Office implementations of the cards.
Proposal
The proposal to fix this issue is to provide two "types" of stories:
Definition Stories
Goal: Teach the user what the component does as quick as possible
How:
Separately, we should consider highlighting the anatomy in use in the story, see #28326 for a prototype, namely it should:
This PR
A visual prototype of the a mostly complete Card definition story is provided for demonstration only. The story file should be ignored as it would be split into multiple files. The definition stories would also be organized under some area apart from the usage stories. However, the prototype is sufficient for visually showing how a set of "definition stories" would step through the API for a given component.
How to test: http://localhost:3000/?path=/docs/components-card-card--definition#definition
Related Issue(s)
Visual Reference
Key aspects: