Docs: Add Writing Stories in TypeScript docs guide #23711
Conversation
kylegach
added
documentation
patch:yes
kylegach
force-pushed
the
writing-stories-in-typescript
branch
from
ebcac82
to
9c87ffb
Compare
kylegach
force-pushed
the
writing-stories-in-typescript
branch
from
9c87ffb
to
78df445
Compare
kasperpeulen
removed
the
patch:yes
kylegach
force-pushed
the
writing-stories-in-typescript
branch
from
78df445
to
e7f654a
Compare
docs/writing-stories/typescript.md
Outdated
| <div class="aside"> | ||
|
|
||
| 鈩癸笍 We are not yet able to provide additional type safety using the `satisfies` operator with Angular and Web components. | ||
|
|
||
| <details> | ||
| <summary>More info</summary> | ||
|
|
||
| Both Angular and Web components utilize a class plus decorator approach. The decorators provide runtime metadata, but do not offer metadata at compile time. | ||
|
|
||
| As a result, it appears impossible to determine if a property in the class is a required property or an optional property (but non-nullable due to a default value) or a non-nullable internal state variable. | ||
|
|
||
| For more information, please refer to [this discussion](github.com/storybookjs/storybook/discussions/20988). | ||
|
|
||
| </details> |
There was a problem hiding this comment.
@kylegach while previewing this locally, it reads a bit weird and adds a bit of confusion with the amount of information you're trying to present. A couple of options we could here:
1- Condense the information in a single paragraph without the aside and provide the link for the relevant discussion (don't forget to update the link as it throws a 404).
2 - Push this aside into a troubleshooting section visible only for the frameworks (i.e., Angular and Web Components) with some word adjustments
There was a problem hiding this comment.
I fixed the link (thanks for the catch!). But I still like the current approach better than either of those options.
- The aside makes it immediately clear to the affected users that
satisfiesis not available. - Rather than just taking our word for it, the "More info" provides the why.
- While this could be an anchor link to a conditionally rendered troubleshooting section, that seemed far more clunky than a details disclosure.
- I don't think we should combine the initial message with what's in "More info", because that is too much information to present upfront.
docs/writing-stories/typescript.md
Outdated
|
|
||
| ## Framework specific tips | ||
|
|
||
| Template-based frameworks such as Vue and Svelte typically require editor extensions to enable syntax highlighting, autocomplete, and type checking. Here are a few tips to help you set up the ideal environment for them. |
There was a problem hiding this comment.
Mind taking a second pass at this and restructuring the documentation a bit, as this is going to be applied only for Vue and Svelte; it seems that the heading seems a bit redundant when a user is already previewing the documentation for any of those frameworks.
There was a problem hiding this comment.
Thanks for the push toward simplicity!
docs/writing-stories/typescript.md
Outdated
|
|
||
| <!-- prettier-ignore-end --> | ||
|
|
||
| ### Optional type parameter |
There was a problem hiding this comment.
Can you elaborate on the need for this heading when the text within it relates to the above? Couldn't it be removed and the text below adjusted to provide the information explicitly? More even as we're teaching users to use this pattern in all the examples we provide, and adding this may add some confusion simply by referencing it as optional.
What do you think?
There was a problem hiding this comment.
When structuring docs, I try to think about what would be useful to link to later, as a reference. And an explanation of the type parameter would be a useful reference to provide for many of the conversations I've had.
That said, I appreciate your suggestion that the "Optional" part is emphasized too much. I tried to address that in my update.
docs/writing-stories/typescript.md
Outdated
| title: 'Writing stories in TypeScript' | ||
| --- | ||
|
|
||
| Writing your stories in [TypeScript](https://www.typescriptlang.org/) makes you more productive. You don't have to jump between files to look up component props. Your code editor will alert you about missing required props and even autocomplete prop values. Plus, Storybook infers those component types to auto-generate the [Controls](../api/doc-block-controls.md) table. |
There was a problem hiding this comment.
Could you take another pass at the introduction and condense it a bit to be more straight to the point, as the way it's written, it seems that we're repeating the same idea.
kylegach
changed the title
kylegach
force-pushed
the
writing-stories-in-typescript
branch
2 times, most recently
from
b64895e
to
b9441b9
Compare
- Use same snippets for all "custom args" examples - Add/update/remove snippets
- Simplify introduction - Fix links - Tweak "type parameter" heading & text - Fix typos - Simplify renderer-specific content structure
kylegach
force-pushed
the
writing-stories-in-typescript
branch
from
b9441b9
to
dbde31b
Compare
Closes #22595, closes #23362
What I did
/writing-stories/typescript) docs guideHow to test
writing-stories-in-typescriptChecklist
MIGRATION.MD
Maintainers
ci:normal,ci:mergedorci:dailyGH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found incode/lib/cli/src/sandbox-templates.ts["cleanup", "BREAKING CHANGE", "feature request", "bug", "build", "documentation", "maintenance", "dependencies", "other"]馃 Canary release
This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the
@storybookjs/coreteam here.core team members can create a canary release here or locally with
gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>