[docs]: improve Storybook prop table for `Slot<T>` type

[spmonahan]

trafficstars

Library

React Components / v9 (@fluentui/react-components)

Describe the feature that you would like added

I'd like to prop table documentation for props that are of type Slot<T> to be better.

For example, this is the documentation for Avatar's icon slot

This is the type in source: Slot<'span'>

I propose that:

1. The Storybook prop table show the type as written in source (e.g., Slot<'span'>)
2. All prop docs for slots link to Fluent UI's slot documentation

This will make the docs cleaner and easier to understand and point readers in the right direction so they can learn about Fluent's slot API.

Have you discussed this feature with our team

@hotell, @spmonahan

Additional context

This came us as a result of #26976 Related:

• #27908

Validations

• [X] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[JustSlone]

We should tackle this, documentation will become more important in the future.

If someone has time to pick this up and make this focused fix, feel free. Note that you'll want to sync with @tudorpopams regarding the Fluent 2 website.

Otherwise we can tie this up as part of a storybook improvement initiative that we'll schedule explicitly.

[spmonahan]

I think @ling1726 has some insight into the work required for this change.

If this is a lot of work perhaps a good simple(r?) first step is to include a link to the slot documentation at the top of every prop table?

[MichaelGoulding]

I came here from #26976. Without looking through closed issues, I wouldn't know how to disable or handle primary button clicks on SplitButton.

[microsoft-github-policy-service[bot]]

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.

[bsunderhus]

I have some info on how this happens

Here's a minimal example of type inferences happening behind the scene on TS compiler side.

type X = {
  a: 'a',
  b: 'b',
  c: 'c'
} | null | undefined

// if you hover over you'll see x:X
declare const x: X

// if you hover over you'll see that instead of having nonNullableX: NonNullable<X>
// TS has inferred the new constructing type because it had to find out what would be the intersection between
// 'X' and everything but `null` and `undefined`
// so if you hover over you'll see a new type! nonNullableX: {
//     a: 'a';
//     b: 'b';
//     c: 'c';
// }
declare const nonNullableX: NonNullable<X>

TS basically has to calculate what would be the new type (in the example case, it calculates the intersection between X and everything but null and undefined and due to this calculation a new type is generated and that type is the one that becomes available. The same goes for the types on the Storybook table)

To solve this problem on our case (at least if we want to solve on TS side of it) we'd have to stop manipulating our types declarations so much on a slot declaration (every time we use infer or create an intersection we will trigger TS to recalculate the resulting type). This is not trivial, but it's doable.

[bsunderhus]

This is not a documentation issue. it's a TS issue on Slot API, the storybook docgen is only reflecting this problem