Docs: Add ArgTypes API reference

[kylegach]

Closes #17681

What I did

• Remove previous ArgTypes guide
• Add/update relevant snippets
• Move CSF page out of Stories sub-section in TOC
  • Remove now-empty Stories sub-section

How to test

1. Follow the steps in the contributing instructions for this branch, api-reference-arg-types
   • There are a lot of embedded snippets, so this step is critical!
2. Check for:
   a. Completeness
   - Is every property documented fully?
   b. Correctness
   - Types
   - Required or not
   - Default values
   - Descriptions
   - Example snippets
   c. Consistency in structure

Checklist

• Make sure your changes are tested (stories and/or unit, integration, or end-to-end tests)
• Make sure to add/update documentation regarding your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Maintainers

• If this PR should be tested against many or all sandboxes,
  make sure to add the ci:merged or ci:daily GH label to it.
• Make sure this PR contains one of the labels below.

["cleanup", "BREAKING CHANGE", "feature request", "bug", "documentation", "maintenance", "dependencies", "other"]

[kylegach]

This is the same table as in the old argtypes.md, organized more sensibly.

[kylegach]

Highlighting this TODO, for which I need an answer, please.

[shilman]

TLDR: The type field is semantic and the table.type.summary is what's shown in the UI.

It's a little convoluted and I hope we can streamline this in 8.0.

1. The component is analyzed using some kind of docgen (react-docgen/compodoc/etc.) All of these tools have different formats.
2. Those all get summarized in the type field. Users can also specify the type field themselves, in case docgen got it wrong, or there is no docgen for your particular framework/renderer.
3. Storybook uses the type field to auto-generate the control field (which can also be manually overwritten/refined)
4. Storybook also uses the type field to autogenerate the table.type.summary/details fields for display (which can also be manually overwritten/refined)

There are two ways of specifying type:

// longhand
export default {
  argTypes: { 
     foo: { type: { name: 'number' } },
  }
}

// shorthand
export default {
  argTypes: { 
     foo: { type: 'number' },
  }
}

Why not just use the shorthand? Well, there is some support for structured types like Object/Array. This was overengineered in retrospect since we don't take advantage of that data yet. We will in the future, but I don't know when. If I could turn back time, I would just use the shorthand.

Also worth noting that we're planning on introducing an even shorter shorthand in 7.2 which will look like:

export default {
  argTypes: {
     foo: 'number',
     bar: 'action', // <= this is new
  } 
}

We'll probably create an RFC for this change. The rationale behind it is a bit complex but it has to do with performance, story portability, etc. (making it easier to not have to run docgen at all in some cases). Should not affect the current docs, but just wanted to give the full picture that this will be changing soon.

[chakAs3]

Why not just use the shorthand? Well, there is some support for structured types like Object/Array. This was overengineered in retrospect since we don't take advantage of that data yet. We will in the future, but I don't know when. If I could turn back time, I would just use the shorthand.

I agree with you @shilman for a long time it was confusing for me, I thought it is a new API. I think we need to normalize and simplify the API, and it should be always an option to override values.

Another important point @shilman, should we separate the docgen plugins, right you are kind of normalizing react and vue, the caveat here is not all renderers have the same architecture

[kylegach]

Thank you for the detailed answer! 👏

Updates pushed in 55bfceb.

[chakAs3]

Hi @kylegach is this just for react or agnostic ?

[chakAs3]

this PR is important for me. we may be depending on each other, with my last 2 PRs that deal with ArgTypes even if it is just docs

[kylegach]

@chakAs3 —

Hi @kylegach is this just for react or agnostic ?

It's intended to be agnostic. The argTypes API itself is definitely agnostic. The snippets demonstrating how to use it should be available for all necessary renderers (because the demonstrate using the meta, they're available for Angular, Web Components, and "common", which should cover everything else).

[kylegach]

@chakAs3 —

this PR is important for me. we may be depending on each other, with my last 2 PRs that deal with ArgTypes even if it is just docs

Thanks for the heads up and your review! If you link them here, I'm happy to take a look to confirm whether we need to be concerned about any overlap.

[chakAs3]

Hi @kylegach this is the PR #22912,
I want to make sure I can get the correct Arg Types from most renderers, there is no breaking change tho. if the control types are not supplied by the renderer it will fall the old behavior.
I need your input and probably @MichaelArestad . design wise

[kylegach]

@chakAs3 — Interesting! Looks like all that will be necessary docs-wise is a new row in the table of allowable control types. Thanks!

[chakAs3]

@chakAs3 — Interesting! Looks like all that will be necessary docs-wise is a new row in the table of allowable control types. Thanks!

Yes, it is union control, so now you switch between allowable controls, I pick the one you want in case you have an Arg of type union ( number | string | boolean | ....) may be we need to limit the number or come up with a layout that can accommodate numerous controls.

[jonniebigodes]

Thanks for addressing the feedback so promptly. Appreciate it. I'm good with it.

[jonniebigodes]

As the defaultValue is deprecated, probably not a bad idea to reference it as such and point directly to the section or remove it. WDYT?

[jonniebigodes]

Thanks for addressing the feedback so promptly. Appreciate it. All good on my end