Addon-docs: Proposal to link interfaces

[atanasster]

In typescript projects, some (legacy) components accept large interfaces into a single prop name. In this case the prop table is really not very helpful as it shows only the top level property. I understand this is not a top priority, but just to keep it on file, can we have an option to 'link' embedded properties.

example of a prop table https://atanasster.github.io/grommet-controls/?path=/docs/charts-chartjs-barchart--main

it has only two props:

options: IChartjsOptions;
data:IChartjsData;

It would be more helpful to be able to link or expand the IChartjsOptions interface to actually see the available properties.

[shilman]

I like this idea. It reminds me of: #7479

I'm wondering if we can solve this in a generic way, where we provide a unified design for a set of hooks (in the traditional sense of the term, not in the react sense) that can transform display data at the last minute.

Also related: @Aaron-Pool has put together a really nice hook for inline component rendering #7929. It's a little different use case, but probably falls into same category.

[atanasster]

if @Aaron-Pool is into it, we can work on this together. One issue to overcome initially is that react-docgen-typescript does not follow up linked types, so we will probably need to send them a PR.

[Aaron-Pool]

I'm not entirely sure how react-docgen works, but can't it work with jsdoc? I know that the typescript typdef doc block supports this, which may help in documenting option object style props.

I think editing the storybook prop doc block to support this would be pretty easy, given it had the right data. The major endeavor here would be any upstream work in the react-docgen-typescript library. If it doesn't support the nested properties documentation linked above.

[atanasster]

I am not much of an expert on react-docgen-typescript, but it uses comments in the code to generate the property descriptions. Also I think it has specific support for React.FC generics, but then I haven't used jsdoc and it might also support it?
In any case, if this request becomes a thing, I will look more into react-docgen-typescript

[stale]

Hi everyone! Seems like there hasn't been much going on in this issue lately. If there are still questions, comments, or bugs, please feel free to continue the discussion. Unfortunately, we don't have time to get to every issue. We are always open to contributions so please send us a pull request if you would like to help. Inactive issues will be closed after 30 days. Thanks!

[github-actions]

Automention: Hey @elevatebart @JeroenReumkens, you've been tagged! Can you give a hand here?

[adhiravishankar]

Is there a way to do this within the MDX formatting? Even if there isn't a way to do this with CSF format and for nested interfaces, I think that having an MDX way to add this would be ideal because it would allow us to include it manually as well. In my use case, I don't need it with the parent. I need mine separately that I can link to via CSF or MDX (either one is fine), but I do want it separate to make it simpler.

[SimeonRolev]

This would be very useful. With something like this, I only get the name of the interfaces in the Controls/Docs panels. Reusing types/interfaces in multiple places is a pretty common use case. Has anyone came up with a workaround?

interface First = {
    first_one: boolean,
    first_two: string
}

interface Second =  {
    second_1: number,
    second_2: () => void
}

interface Props = {
    first: First,  // <---
    second: Second,  // <---
    regular: boolean
}

export const Component: FunctionComponent<Props> = ({ first, second, regular }: Props): React.ReactElement => { ... }