Page per section #835

bitionaire · 2018-02-21T14:48:17Z

Added routing variant that will show sections & components in isolated mode (when pagePerSection is set to true in the config part), starting with the first section or component for the index page.

There are some minor changes and tweaks in comparison to PR #768. Instead of showing the first component per default, I set the first section or component as the default. I assume most of the larger styleguides start with some kind of Intro or Getting started section anyways.

This PR should address #494.

What do you think about it?

…ster' of github.com:bitionaire/react-styleguidist into feature/allow-to-show-one-component-per-page

…ed few tweaks

codecov-io · 2018-02-21T14:57:36Z

Codecov Report

Merging #835 into master will increase coverage by 0.04%.
The diff coverage is 100%.

Impacted Files	Coverage Δ
scripts/schemas/config.js	`86.2% <ø> (ø)`	⬆️
loaders/styleguide-loader.js	`100% <ø> (ø)`	⬆️
...rc/rsg-components/ComponentsList/ComponentsList.js	`100% <100%> (ø)`
src/utils/getRouteData.js	`100% <100%> (ø)`	⬆️
src/utils/renderStyleguide.js	`76.92% <100%> (+1.92%)`	⬆️
...omponents/ComponentsList/ComponentsListRenderer.js	`100% <100%> (ø)`	⬆️
src/rsg-components/slots/index.js	`100% <100%> (ø)`	⬆️
.../rsg-components/TableOfContents/TableOfContents.js	`94.11% <100%> (ø)`	⬆️
src/rsg-components/StyleGuide/StyleGuide.js	`86.66% <100%> (+3.33%)`	⬆️

sapegin · 2018-02-21T17:51:23Z

Awesome, thanks for picking it up! I haven't looked into the code yet, let's finalize the API first.

Instead of showing the first component per default, I set the first section or component as the default. I assume most of the larger styleguides start with some kind of Intro or Getting started section anyways.

I thinks that's a great idea!

What do you think about making the option a string instead of a boolean with values always, never, static-only, with the latter as a default value? static-only will show one component in dev mode and all in the static build, I believe that would be most convenient for the majority of users.

SaraVieira · 2018-02-21T18:13:33Z

Hi @bitionaire!

This is awesome! This is just what I needed to solve a major problem in our styleguide! Anxiously awaiting for this to get merged!

bitionaire · 2018-02-21T18:54:11Z

What do you think about making the option a string instead of a boolean with values always, never, static-only, with the latter as a default value? static-only will show one component in dev mode and all in the static build, I believe that would be most convenient for the majority of users.

Sure, maybe there are even more modes we didn't think of yet. Good point! 👍
I also noticed that the page doesn't scroll to top after #!/ route changes. I'll fix that, too.

bitionaire · 2018-02-21T20:52:32Z

I just added a few commits, and pagePerSection may be defined as a function. static-only may look like pagePerSection: () => (process.env.NODE_ENV !== 'production').

I added window.scrollTo(0,0) in componentDidUpdate of StyleGuide.js. The location of this code seems really hacky, and it does not work for all use-cases (e.g. scrolling down and navigating to the same section won't trigger the execution), but I'm not sure where to put it. I'll think about a better solution. If you have any ideas, I'm open to any suggestions :)

tizmagik · 2018-02-23T18:17:36Z

Looking forward to this! 🙏

sapegin

Thanks again for the PR! A few small remarks.

sapegin · 2018-02-23T19:07:20Z

src/rsg-components/ComponentsList/__snapshots__/ComponentsList.spec.js.snap

+  >
+    <Styled(Link)
+      className=""
+      href="blank#button"


Is this correct value? Looks like a non-isolated link.

Good catch! I missed that in my refactoring

sapegin · 2018-02-23T19:08:46Z

src/rsg-components/StyleGuide/StyleGuide.js

@@ -44,6 +47,15 @@ export default class StyleGuide extends Component {
 		};
 	}

+	componentDidUpdate(prevProps) {
+		// scroll to top of styleguide container when sections changed


Probably this will be a better place: https://github.com/styleguidist/react-styleguidist/blob/master/src/utils/renderStyleguide.js

Though you may need to cache current route.

I thought about that. It's way more efficient to watch on location changes, yet it would mean to replace the functional component something like an "App" component or to merge the logic with the StyleGuide.js. What do you think is the better way?

sapegin · 2018-02-23T19:10:56Z

src/rsg-components/StyleGuide/StyleGuide.js

-				hasSidebar={config.showSidebar && displayMode === DisplayModes.all}
+				toc={<TableOfContents sections={allSections} useIsolatedLinks={pagePerSection} />}
+				hasSidebar={
+					(pagePerSection && displayMode !== DisplayModes.example) ||


I guess it's time to move this condition to a function with a good comment ;-)

You're right

sapegin · 2018-02-23T19:12:58Z

src/utils/renderStyleguide.js

@@ -27,7 +28,9 @@ export default function renderStyleguide(
 	// all components accessible to all examples
 	globalizeComponents(allSections);

-	const { sections, displayMode } = getRouteData(allSections, loc.hash);
+	const { pagePerSection } = styleguide.config;
+	const renderPagePerSection = isFunction(pagePerSection) ? pagePerSection() : pagePerSection;


We should convert function to a boolean in config schema and later use boolean values, would be simpler.

But since we don't pass any dynamic data to this function, we probably don't need it. This would also work:

module.exports = { pagePerSection: process.env.NODE_ENV !== 'production' }

Sure. Just reverted the changes. So there's no need for an enum like always, never or static-only, right?

I think I could just add this as a default value in the next major release.

…o App

sapegin · 2018-02-28T07:56:18Z

src/index.js

 let codeRevision = 0;

 const render = () => {
 	// eslint-disable-next-line import/no-unresolved
 	const styleguide = require('!!../loaders/styleguide-loader!./index.js');
-	ReactDOM.render(renderStyleguide(styleguide, codeRevision), document.getElementById('app'));
+	ReactDOM.render(


I don't think it was necessary: it should rerender everything on hash change, so you can scroll in renderStyleguide.

I didn't want to introduce any kind of global variable; either the hash of the last location or a boolean that will indicate if an event listener for hashchange was already registered.
I think it'll be easier to handle the component (or event handler) lifecycle in the <App />. But it's your project so you decide. Should I revert the changes and add an event listener for the first time renderStyleguide will be called?

Yes, please. I think it makes this part much more complex then it was.

What kind of an event handler you want to add? There's a hashchange handler already that rerenders everything.

bitionaire · 2018-03-02T15:21:49Z

Allright, please have look 👍

sapegin

Thanks for the changes! Just a few small things left 🦄

sapegin · 2018-03-02T18:17:03Z

src/index.js

 let codeRevision = 0;

 const render = () => {
 	// eslint-disable-next-line import/no-unresolved
 	const styleguide = require('!!../loaders/styleguide-loader!./index.js');
-	ReactDOM.render(renderStyleguide(styleguide, codeRevision), document.getElementById('app'));
+	ReactDOM.render(renderStyleguide(styleguide, status), document.getElementById('app'));
+	if (get(window, 'location.hash', '').startsWith('#!/')) {


This needs a comment.

Would it be triggered on code updates too? Probably better to have a separate hashchange just for this.

I guess status instead of codeRevision wasn't intended.

sapegin · 2018-03-02T18:17:53Z

src/index.js

@@ -4,14 +4,19 @@ import './polyfills';
 import './styles';
 import ReactDOM from 'react-dom';
 import renderStyleguide from './utils/renderStyleguide';
+import { get } from 'lodash';


Please don't import whole Lodash on frontend. But I think you don't really need it here, are there any cases where location.hash won't be defined?

sapegin · 2018-03-02T18:19:24Z

src/rsg-components/ComponentsList/index.js

@@ -1 +1 @@
-export { default } from 'rsg-components/ComponentsList/ComponentsListRenderer';
+export { default } from './ComponentsList.js';


All component imports should be like rsg-components/ComponentsList/ComponentsListRenderer, see more info here: https://react-styleguidist.js.org/docs/development.html

sapegin · 2018-03-02T18:23:07Z

src/utils/getRouteData.js

 	}

 	return { sections, displayMode };
 }
+
+function getFirstSectionOrComponent(sections) {


Could you move this function before the default export and use an arrow function? That's the convention we use for such smallish functions.

bitionaire · 2018-03-02T19:00:02Z

I think we're getting close 🍻

sapegin · 2018-03-03T12:02:40Z

src/index.js

 let codeRevision = 0;

+/** Scrolls to origin when current window location hash points to an isolated view. */
+const scrollToOrigin = () => {
+	if (window.location.hash.startsWith('#!/')) {


I'm afraid startsWith won't work in IE11, everything else looks fine for me.

You're right! I replaced it with indexOf === 0

sapegin · 2018-03-04T09:30:10Z

Awesome, thanks! I'll try to make a release soon 🦄

bitionaire · 2018-03-09T09:56:44Z

Hey @sapegin,

I've added one change, can you have a look at that?
It's hard to define a correct behaviour for the IsolateButton if pagePerSection=true. Therefore I excluded the button from any toolbars for the slots object, based on the styleguide configuration.

@bitionaire

👋 **[Support Styleguidist](https://opencollective.com/styleguidist) on Open Collective** 👋 ## New features ### Page per section 🚧 This is a huge improvement for large style guides: now you can show only one component at a page instead of all components. ![](https://d3vv6lp55qjaqc.cloudfront.net/items/0W2q2K2s3n2k311O1J0y/Screen%20Recording%202018-03-22%20at%2010.06%20AM.gif) To enable: ```js module.exports = { pagePerSection: true }; ``` This is an experimental feature and we need your feedback to make it better and really useful. For example, right now there’s no isolated mode. So feel free to share your ideas [in issues](https://github.com/styleguidist/react-styleguidist/issues). (#835 by @bitionaire and @stepancar, closes #494 and #768) ### “Fork me” ribbon One more step to make Styleguidist usable for documenting open source projects: ![](https://d3vv6lp55qjaqc.cloudfront.net/items/1t331n2a3v0F2i290K0Z/Image%202018-03-22%20at%209.13.11%20AM.png) New config option to enable the ribbon, define the URL and change the label: ```js module.exports = { ribbon: { url: 'http://example.com/', text: 'Fork me on GitHub' } }; ``` And two new [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/styles/theme.js) to change colors: `color.ribbonBackground` and `color.ribbonText`. (#861 by @glebez and @wkwiatek, part of #195, closes #647) ### Options to change CLI output on server start and build Two new options, `printServerInstructions` and `printBuildInstructions`: ```js module.exports = { printBuildInstructions(config) { console.log( `Style guide published to ${ config.styleguideDir }. Something else interesting.` ); } }; ``` (#878 by @roblevintennis, closes #876) ### Option to modify props A new option, `updateDocs` to modify props before rendering. For example, you can load a component version number from a JSON file: ```js module.exports = { updateDocs(docs) { if (docs.doclets.version) { const versionFilePath = path.resolve( path.dirname(file), docs.doclets.version ); const version = require(versionFilePath).version; docs.doclets.version = version; docs.tags.version[0].description = version; } return docs; } }; ``` (#868 by @ryanoglesby08) ### Limited support for named exports Styleguidist used to require default exports for components. Now you can use named exports too, though Styleguidist still supports only one component per file. I hope this change will make some users happier, see more details [in the docs](https://react-styleguidist.js.org/docs/components.html#loading-and-exposing-components). (#825 by @marcdavi-es, closes #820 and #633) ### Allow arrays of component paths in sections More flexibility in structuring your style guide: ```js module.exports = { sections: [ { name: 'Forms', components: [ 'lib/components/ui/Button.js', 'lib/components/ui/Input.js' ] } ] }; ``` (#794 by @glebez, closes #774) ### Sort properties by `required` and `name` attributes This change should make props tables more predictable for the users. Instead of relying on developers to sort props in a meaningful way, Styleguidist will show required props first, and sort props in each group alphabetically. To disable sorting, use the identity function: ```javascript module.exports = { sortProps: props => props }; ``` (#784 by @dotcs) ## Bug fixes * Allow `Immutable` state in examples (#870 by @nicoffee, closes #864) * Change template container ID to prevent clashes (#859 by @glebez, closes #753) * Better props definitions with Flow types (#781 by @nanot1m)

sapegin · 2018-03-22T10:26:35Z

🎉 This PR is included in version 6.5.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

stepancar and others added 6 commits January 9, 2018 23:17

feat(*): allow to show one component per page

49631b2

fix(*): fix according sapegin recomendations

80135ba

docs(*): add docs for oneComponentPerPage prop

b546d05

test(*): add tests for oneComponentPerPage functionality

9a2f8cb

Merge branches 'feature/allow-to-show-one-component-per-page' and 'ma…

85158da

…ster' of github.com:bitionaire/react-styleguidist into feature/allow-to-show-one-component-per-page

Replaced 'oneComponentPerPage' with 'pagePerSection' property and add…

15975dc

…ed few tweaks

bitionaire added 3 commits February 21, 2018 17:04

Changed test name

b4a6780

Fixed section route

98931f4

Use isolated links extracted from props instead of context

48a585b

bitionaire added 5 commits February 21, 2018 21:28

Added option to configure pagePerSection as function

fca7e0c

Added scrollTo(0,0) on sections change

12d823c

Forward props correctly

fa0e3e8

Removed unintended change

b4f94fe

Fixed test

42396ca

bitionaire added 3 commits February 22, 2018 17:36

Added scroll tests

3f7c42a

Added getRouteData test for single section

fecaf2a

Coverage fix

ad76446

sapegin requested changes Feb 23, 2018

View reviewed changes

bitionaire added 5 commits February 23, 2018 21:22

Modifications by PR review

bfe0c46

Modifications by PR review

26c56cf

Splitted URL generation and renderer

dd74215

Replaced renderStyleguide SFC by <App /> and moved scrollTo logic int…

d2a38c0

…o App

Removed unused snapshot file

5eb2744

sapegin requested changes Feb 28, 2018

View reviewed changes

bitionaire added 2 commits March 2, 2018 14:10

Reverted changes

aaac44b

Added snapshot

c2984df

sapegin requested changes Mar 2, 2018

View reviewed changes

Fixes by PR review

5bd367f

sapegin requested changes Mar 3, 2018

View reviewed changes

Replaced startsWith with indexOf === 0

0c03a66

sapegin approved these changes Mar 4, 2018

View reviewed changes

sapegin added this to the 6.3.0 milestone Mar 4, 2018

Hide IsolateButton when pagePerSection is true

6c6e5a7

Merge branch 'master' into feature/page-per-section

55b81ef

sapegin merged commit 6055c2b into styleguidist:master Mar 21, 2018

brightWeen mentioned this pull request Mar 24, 2018

Supporting page per section vue-styleguidist/vue-styleguidist#98

Closed

This was referenced Jul 17, 2020

[Snyk] Security upgrade react-styleguidist from 6.0.33 to 6.5.0 Bhanditz/react-styleguidist#46

Open

[Snyk] Fix for 1 vulnerabilities Bhanditz/react-styleguidist#47

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Page per section #835

Page per section #835

bitionaire commented Feb 21, 2018

codecov-io commented Feb 21, 2018 •

edited

Loading

sapegin commented Feb 21, 2018

SaraVieira commented Feb 21, 2018

bitionaire commented Feb 21, 2018

bitionaire commented Feb 21, 2018

tizmagik commented Feb 23, 2018

sapegin left a comment

sapegin Feb 23, 2018

bitionaire Feb 23, 2018

sapegin Feb 23, 2018

bitionaire Feb 23, 2018 •

edited

Loading

sapegin Feb 23, 2018

bitionaire Feb 23, 2018

sapegin Feb 23, 2018

bitionaire Feb 23, 2018 •

edited

Loading

sapegin Feb 23, 2018 •

edited

Loading

sapegin Feb 28, 2018

bitionaire Feb 28, 2018

sapegin Feb 28, 2018

bitionaire commented Mar 2, 2018

sapegin left a comment

sapegin Mar 2, 2018

sapegin Mar 2, 2018

sapegin Mar 2, 2018

sapegin Mar 2, 2018

bitionaire commented Mar 2, 2018

sapegin Mar 3, 2018

bitionaire Mar 3, 2018

sapegin commented Mar 4, 2018

bitionaire commented Mar 9, 2018

sapegin commented Mar 22, 2018

		@@ -1 +1 @@
		export { default } from 'rsg-components/ComponentsList/ComponentsListRenderer';
		export { default } from './ComponentsList.js';

Page per section #835

Page per section #835

Conversation

bitionaire commented Feb 21, 2018

codecov-io commented Feb 21, 2018 • edited Loading

Codecov Report

sapegin commented Feb 21, 2018

SaraVieira commented Feb 21, 2018

bitionaire commented Feb 21, 2018

bitionaire commented Feb 21, 2018

tizmagik commented Feb 23, 2018

sapegin left a 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

bitionaire Feb 23, 2018 • edited Loading

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

bitionaire Feb 23, 2018 • edited Loading

Choose a reason for hiding this comment

sapegin Feb 23, 2018 • edited Loading

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

bitionaire commented Mar 2, 2018

sapegin left a 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

bitionaire commented Mar 2, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sapegin commented Mar 4, 2018

bitionaire commented Mar 9, 2018

sapegin commented Mar 22, 2018

codecov-io commented Feb 21, 2018 •

edited

Loading

bitionaire Feb 23, 2018 •

edited

Loading

bitionaire Feb 23, 2018 •

edited

Loading

sapegin Feb 23, 2018 •

edited

Loading