docs(public-docsite-v9): add documentation for base state hooks and authoring patterns#35891
docs(public-docsite-v9): add documentation for base state hooks and authoring patterns#35891dmytrokirpa wants to merge 2 commits intomicrosoft:masterfrom
Conversation
…uthoring patterns
📊 Bundle size report✅ No changes found |
|
Pull request demo site: URL |
Hotell
left a comment
Hotell
left a comment
There was a problem hiding this comment.
needs some tweaks, overall looks good, ty
|
|
||
| Visit the **[Styling handbook](https://github.com/microsoft/fluentui/blob/master/docs/react-v9/contributing/rfcs/react-components/styles-handbook.md)** for a comprehensive styling guide, as this article only introduces basics to get you started quickly. | ||
|
|
||
| If you need to build a custom component architecture (not just style existing components), see [Base state hooks](?path=/docs/concepts-developer-base-state-hooks--docs). |
There was a problem hiding this comment.
this should probably be a blockquote right like you did in apps/public-docsite-v9/src/Concepts/AdvancedStylingTechniques.mdx ?
| - Keep user `className` precedence by appending existing slot class names last. | ||
| - Validate all states visually (`:hover`, `:active`, `:focus-visible`, disabled). | ||
| - Test keyboard and screen reader behavior after custom rendering changes. | ||
| - Prefer small wrappers (`useXxxState`, `useXxxStyles`, `renderXxx`) for maintainability. |
There was a problem hiding this comment.
can we come up with something better than xxx ?
|
|
||
| ### Stability and API lifecycle | ||
|
|
||
| Base state hooks use the `_unstable` suffix and are intended for advanced consumers who can absorb lower-level API evolution over time. |
There was a problem hiding this comment.
not sure what are we saying with this one ? that we are going to do BC for them (" can absorb lower-level API evolution over time" ?
can we re-phrase this to align with existing patterns ? eg. "we follow our _unstable suffix pattern etc etc..."
| }); | ||
| ``` | ||
|
|
||
| #### 2) Full example: replacing slot logic and conditionally omitting slot rendering |
There was a problem hiding this comment.
maybe we can narrow down to only 1 example, the only "major" diff with 1st example seems to be the conditional slot rendering, probably can keep only this 2nd example as showcase
|
|
||
| They let you reuse Fluent UI behavior primitives (ARIA patterns, keyboard handling, semantic structure) while owning rendering and styling completely. | ||
|
|
||
| For most apps, the styled component APIs are still the right default. |
There was a problem hiding this comment.
we should re-phrase this one to something like:
"For Fluent DS extensions existing component composition hooks are the right default."
|
|
||
| ## Base state hooks | ||
|
|
||
| Base state hooks are an advanced, opt-in API for teams building custom component libraries that significantly diverge from Fluent 2 visual design. |
There was a problem hiding this comment.
there is no notion of "Fluent 2" in our docs so this might be confusing to users. can we improve this ?
|
|
||
| ## Base state hooks | ||
|
|
||
| Base state hooks are an advanced, opt-in API for teams building custom component libraries that significantly diverge from Fluent 2 visual design. |
There was a problem hiding this comment.
lets unify here, low level vs advanced api, we should probably go with former ?
|
|
||
| ### Quick decision guide | ||
|
|
||
| Use styled components (`Button`, `Input`, etc.) when you want: |
There was a problem hiding this comment.
we should probably compare agains existing hooks instead of full fedged components ? it feels missleading
2 participants
This pull request introduces comprehensive documentation for "Base state hooks" in Fluent UI React v9, clarifying their purpose, use cases, and authoring patterns. It also adds cross-references to this new documentation from related customization and styling concept pages, making it easier for developers to understand when and how to use base state hooks versus other customization options.