Addon-docs: DocsPage and doc blocks #7119

shilman · 2019-06-18T06:14:40Z

Issue: #7101

~~This is based on Addon-docs: Basic skeleton, UI viewMode handling #7107 so wait until that's merged before reviewing~~
Also depends on ~~Addon-docs: Module story format & framework param #7110~~ and Addon-docs: Source loader library #7117 but can be reviewed without merging those

What I did

This PR adds DocsPage and all the doc blocks. It's a big one, but hopefully the code is pretty simple-minded.

In summary:

lib/components/src/blocks/* - pure components that have their own stories in official-storybook
addons/docs/src/blocks/* - container components that do various tricks to get stuff out of the context/etc. to provide data to the pure components
hook up this code into examples through DocsPage which automatically generates pages for each "kind"

NOTES:

It won't support Source block until Addon-docs: Source loader library #7117 source loading & "Docs preset" PR integrates the two.
It won't support Props block until Addon-docs: Module story format & framework param #7110 provides framework parameter
It won't infer inline stories for react until Addon-docs: Module story format & framework param #7110 provides framework parameter

How to test

Inspect doc blocks stories in official storybook
Inspect "docs" tab in official storybook
Inspect "docs" tab in vue example

cd examples/official-storybook
yarn storybook

cd ../vue-kitchen-sink
yarn storybook --no-dll

vercel · 2019-06-18T06:14:48Z

This pull request is automatically deployed with Now.
To access deployments, click Details below or on the icon next to each push.

Latest deployment for this branch: https://monorepo-git-7101-doc-blocks.storybook.now.sh

tmeasday · 2019-06-18T12:04:17Z

@shilman can you ping me when this is ready to review (or else you could change the base temporarily)

shilman · 2019-06-18T15:29:23Z

@tmeasday This is ready to review now

tmeasday

Hard to review all of this but it seems generally high quality. Anything in particular you wanted me to look at?

addons/docs/src/blocks/Description.tsx

addons/docs/src/blocks/DocsContainer.tsx

addons/docs/src/blocks/DocsContext.ts

lib/components/src/blocks/IFrame.tsx

lib/components/src/blocks/PropsTable/PropsTable.stories.tsx

tmeasday · 2019-06-19T07:24:29Z

I’m not so sure it will.. let’s try it?

…

On 19 Jun 2019, 5:18 PM +1000, Michael Shilman ***@***.***>, wrote: @shilman commented on this pull request. In lib/components/src/blocks/PropsTable/PropsTable.stories.tsx: > +import { PropsTable, PropsTableError } from './PropsTable'; +import { DocsPageWrapper } from '../DocsPage'; +import * as rowStories from './PropRow.stories'; + +export default { + Component: PropsTable, + title: 'Docs|PropTable', + decorators: [storyFn => <DocsPageWrapper>{storyFn()}</DocsPageWrapper>], +}; + +export const error = () => <PropsTable error={PropsTableError.NO_COMPONENT} />; + +export const empty = () => <PropsTable rows={[]} />; + +const { row: stringRow } = rowStories.string().props; +const { row: numberRow } = rowStories.number().props; it works. i think exporting data will be cleaner tho! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

tmeasday

LGTM!

addons/docs/src/blocks/DocsContext.ts

ndelangen · 2019-06-21T13:16:08Z

It doesn't recover from errors:

Reproduction path:

Navigate docs-mode
Navigate to an story that throws and error
Navigate to a functioning story

addons/docs/src/blocks/Story.tsx

addons/docs/src/blocks/DocsPage.tsx

ndelangen · 2019-06-21T11:05:48Z

addons/docs/src/blocks/DocsPage.tsx

+  expanded = true,
+}) => (
+  <>
+    {expanded && <h3>{name}</h3>}


Should this be configurable at all?

why not just always show this?

Is creating a different docBlock for "showing all stories" not a better api?

configurability is the root of all evil

ndelangen · 2019-06-21T11:07:25Z

addons/docs/src/blocks/DocsPage.tsx

@@ -0,0 +1,136 @@
+import React from 'react';
+
+import { parseKind } from '@storybook/router';


Would be nice to rename this at some point, to something a little more descriptive of what is actually does.

addons/docs/src/blocks/Description.tsx

ndelangen · 2019-06-21T13:26:25Z

lib/components/src/blocks/DocsPage.tsx

+
+const DocsPage: React.FunctionComponent<DocsPageProps> = ({ title, subtitle, children }) => (
+  <>
+    {title && <Title>{title}</Title>}


Don't we have shared typography components?

or should have them

lib/components/src/blocks/PropsTable/PropRow.tsx

ndelangen · 2019-06-21T13:52:48Z

lib/components/src/blocks/PropsTable/PropsTable.tsx

@@ -0,0 +1,155 @@
+import React from 'react';


reuse for markdown tables?

Can we set tables in a horizontal scroller container so mobile users can scroll to view the entire thing?

I think it currently makes up the entire viewport scrollable horizontally

ndelangen · 2019-06-21T14:00:35Z

lib/components/src/blocks/Source.stories.tsx

+<MyComponent boolProp scalarProp={1} complexProp={{ foo: 1, bar: '2' }}>
+  <SomeOtherComponent funcProp={(a) => a.id} />
+</MyComponent>
+`.trim();


these trims are causing the bad indenting, because the formatter expects the whitespace from template literals.

ndelangen · 2019-06-21T14:02:36Z

lib/components/src/blocks/Typeset.tsx

+}));
+
+export interface TypesetProps {
+  fontSizes: number[];


Wouldn't a font-face / font-family prop makes sense here?

shilman added feature request in progress addon: docs labels Jun 18, 2019

shilman added this to the 5.2.0 milestone Jun 18, 2019

shilman requested review from alterx, danielduan, igor-dv, ndelangen, tmeasday and usulpro as code owners June 18, 2019 06:14

shilman mentioned this pull request Jun 18, 2019

Addon-docs: Review and merge #7101

Closed

21 tasks

shilman added 3 commits June 18, 2019 16:13

Doc blocks pure components

4ef48b1

Doc blocks container components

5b851b8

Add DocsPage to official-storybook

effc071

vercel bot deployed to staging June 18, 2019 08:15 View deployment

shilman added 2 commits June 18, 2019 16:56

Addon-docs: Fix no theme bug

8f6e608

Addon-docs: add to vue example

90b7e45

shilman requested a review from alexandrebodin as a code owner June 18, 2019 08:56

vercel bot temporarily deployed to staging June 18, 2019 08:57 Inactive

Update snapshots

8399136

vercel bot deployed to staging June 18, 2019 09:02 View deployment

Merge branch 'next' into 7101-doc-blocks

e424c66

vercel bot temporarily deployed to staging June 18, 2019 15:15 Inactive

Fix typo

dc4b7f0

vercel bot deployed to staging June 18, 2019 15:16 View deployment

Update yarn.lock

8caaf2f

vercel bot deployed to staging June 18, 2019 21:45 View deployment

shilman removed the in progress label Jun 19, 2019

Merge branch 'next' into 7101-doc-blocks

01f4143

vercel bot deployed to staging June 19, 2019 01:03 View deployment

tmeasday reviewed Jun 19, 2019

View reviewed changes

lib/components/src/blocks/PropsTable/PropsTable.stories.tsx Show resolved Hide resolved

Merge branch 'next' into 7101-doc-blocks

6f5d685

vercel bot requested a deployment to staging June 19, 2019 03:23 Pending

vercel bot deployed to staging June 19, 2019 03:34 View deployment

shilman mentioned this pull request Jun 19, 2019

Addon-docs: MDX support #7145

Merged

3 tasks

shilman mentioned this pull request Jun 20, 2019

Docs mode with --docs flag #7154

Merged

Doc blocks review cleanup

f1d7579

vercel bot deployed to staging June 20, 2019 07:01 View deployment

tmeasday approved these changes Jun 21, 2019

View reviewed changes

addons/docs/src/blocks/DocsContext.ts Show resolved Hide resolved

Add docgen commments for each of the doc block components

bb301f8

vercel bot deployed to staging June 21, 2019 11:23 View deployment

ndelangen reviewed Jun 21, 2019

View reviewed changes

Doc blocks: improve typescript types

043fca7

vercel bot deployed to staging June 21, 2019 16:55 View deployment

shilman mentioned this pull request Jun 21, 2019

Addon-docs: Naming consistency for Story blocks #7164

Closed

Use styled headings

f48201e

vercel bot temporarily deployed to staging June 21, 2019 17:16 Inactive

Docgen migration notes

9e63c85

vercel bot temporarily deployed to staging June 21, 2019 17:23 Inactive

PropsRow: Added hover text for required asterisk

723037d

vercel bot deployed to staging June 21, 2019 17:34 View deployment

shilman mentioned this pull request Jun 21, 2019

CSF: Recover from errors #7165

Closed

shilman merged commit d579617 into next Jun 21, 2019

ndelangen deleted the 7101-doc-blocks branch June 24, 2019 08:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Addon-docs: DocsPage and doc blocks #7119

Addon-docs: DocsPage and doc blocks #7119

shilman commented Jun 18, 2019 •

edited

vercel bot commented Jun 18, 2019 •

edited

tmeasday commented Jun 18, 2019

shilman commented Jun 18, 2019

tmeasday left a comment

tmeasday commented Jun 19, 2019 via email

tmeasday left a comment

ndelangen commented Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

ndelangen Jun 21, 2019

		@@ -0,0 +1,136 @@
		import React from 'react';

		import { parseKind } from '@storybook/router';

Addon-docs: DocsPage and doc blocks #7119

Addon-docs: DocsPage and doc blocks #7119

Conversation

shilman commented Jun 18, 2019 • edited

What I did

How to test

vercel bot commented Jun 18, 2019 • edited

tmeasday commented Jun 18, 2019

shilman commented Jun 18, 2019

tmeasday left a comment

Choose a reason for hiding this comment

tmeasday commented Jun 19, 2019 via email

tmeasday left a comment

Choose a reason for hiding this comment

ndelangen commented Jun 21, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shilman commented Jun 18, 2019 •

edited

vercel bot commented Jun 18, 2019 •

edited