New: Collapsible sections (styleguidist#1487)

Closes styleguidist#1436

New config option `tocMode` to allow collapsible table of contents sections. Possible values are:

- `collapse`: All sections are collapsed by default
- `expand`: Sections cannot be collapsed in the Table Of Contents

Author: Barthélémy Ledoux

docs/Configuration.md

@@ -58,6 +58,17 @@ Type: `String` or `Array`, optional
 
 Your application static assets folder will be accessible as `/` in the style guide dev server.
 
+#### `tocMode`
+
+Type: `String` default: `expand`
+
+Defines if the table of contents sections will behave like an accordion:
+
+- `collapse`: All sections are collapsed by default
+- `expand`: Sections cannot be collapsed in the Table Of Contents
+
+Collapse the sections created in the sidebar to reduce the height of the sidebar. This can be useful in large codebases with lots of components to avoid having to scroll too far.
+
 #### `compilerConfig`
 
 Type: `Object`, default:

examples/sections/docs/Components.md

@@ -4,6 +4,6 @@ Ut veniam sit pariatur deserunt non officia. Esse commodo proident quis culpa es
 
 List of components:
 
-- [Buttons](#/Components?id=buttons)
-- [Fields](#/Components?id=fields)
-- [Others](#/Components?id=others)
+- [Buttons](#/Components?id=section-buttons)
+- [Fields](#/Components?id=section-fields)
+- [Others](#/Components?id=section-others)

examples/sections/styleguide.config.js

@@ -3,6 +3,7 @@ const path = require('path');
 module.exports = {
 	title: 'React Style Guide Example',
 	pagePerSection: true,
+	// tocMode: 'collapse',
 	sections: [
 		{
 			name: 'Documentation',

src/client/rsg-components/ComponentsList/ComponentsList.spec.tsx

@@ -7,6 +7,7 @@ import Context from '../Context';
 const context = {
 	config: {
 		pagePerSection: true,
+		tocMode: 'collapse',
 	},
 };
 
@@ -159,3 +160,72 @@ it('should ignore items without visibleName', () => {
 		'http://localhost/#button',
 	]);
 });
+
+it('should show content of items that are open and not what is closed', () => {
+	const components = [
+		{
+			visibleName: 'Button',
+			name: 'Button',
+			slug: 'button',
+			content: <div data-testid="content">Content for Button</div>,
+		},
+		{
+			visibleName: 'Input',
+			name: 'Input',
+			slug: 'input',
+			content: <div data-testid="content">Content for Input</div>,
+		},
+	];
+
+	const { getAllByTestId, getByText } = render(
+		<Provider>
+			<ComponentsList
+				items={components}
+				useRouterLinks
+				hashPath={['Components']}
+				useHashId={false}
+			/>
+		</Provider>
+	);
+
+	getByText('Button').click();
+
+	expect(
+		Array.from(getAllByTestId('content')).map(node => (node as HTMLDivElement).innerHTML)
+	).toEqual(['Content for Button']);
+});
+
+it('should show content of initialOpen items even if they are not active', () => {
+	const components = [
+		{
+			visibleName: 'Button',
+			name: 'Button',
+			slug: 'button',
+			content: <div data-testid="content">Content for Button</div>,
+		},
+		{
+			visibleName: 'Input',
+			name: 'Input',
+			slug: 'input',
+			content: <div data-testid="content">Content for Input</div>,
+			initialOpen: true,
+		},
+	];
+
+	const { getAllByTestId, getByText } = render(
+		<Provider>
+			<ComponentsList
+				items={components}
+				useRouterLinks
+				hashPath={['Components']}
+				useHashId={false}
+			/>
+		</Provider>
+	);
+
+	getByText('Button').click();
+
+	expect(
+		Array.from(getAllByTestId('content')).map(node => (node as HTMLDivElement).innerHTML)
+	).toEqual(['Content for Button', 'Content for Input']);
+});

src/client/rsg-components/ComponentsList/ComponentsList.tsx

@@ -4,7 +4,7 @@ import ComponentsListRenderer from 'rsg-components/ComponentsList/ComponentsList
 import getUrl from '../../utils/getUrl';
 
 interface ComponentsListProps {
-	items: Rsg.Component[];
+	items: Rsg.TOCItem[];
 	hashPath?: string[];
 	useRouterLinks?: boolean;
 	useHashId?: boolean;
@@ -16,20 +16,26 @@ const ComponentsList: React.FunctionComponent<ComponentsListProps> = ({
 	useHashId,
 	hashPath,
 }) => {
-	const mappedItems = items.map(item => ({
-		...item,
-		shouldOpenInNewTab: !!item.href,
-		href: item.href
-			? item.href
-			: getUrl({
-					name: item.name,
-					slug: item.slug,
-					anchor: !useRouterLinks,
-					hashPath: useRouterLinks ? hashPath : false,
-					id: useRouterLinks ? useHashId : false,
-			  }),
-	}));
-	return <ComponentsListRenderer items={mappedItems} />;
+	const mappedItems = items
+		.map(item => {
+			const href = item.href
+				? item.href
+				: getUrl({
+						name: item.name,
+						slug: item.slug,
+						anchor: !useRouterLinks,
+						hashPath: useRouterLinks ? hashPath : false,
+						id: useRouterLinks ? useHashId : false,
+				  });
+
+			return {
+				...item,
+				href,
+			};
+		})
+		.filter(item => item.visibleName);
+
+	return mappedItems.length > 0 ? <ComponentsListRenderer items={mappedItems} /> : null;
 };
 
 ComponentsList.propTypes = {

src/client/rsg-components/ComponentsList/ComponentsListRenderer.tsx

@@ -4,7 +4,6 @@ import cx from 'clsx';
 import Link from 'rsg-components/Link';
 import Styled, { JssInjectedProps } from 'rsg-components/Styled';
 import { useStyleGuideContext } from 'rsg-components/Context';
-import { getHash } from '../../utils/handleHash';
 
 const styles = ({ color, fontFamily, fontSize, space, mq }: Rsg.Theme) => ({
 	list: {
@@ -39,50 +38,55 @@ const styles = ({ color, fontFamily, fontSize, space, mq }: Rsg.Theme) => ({
 });
 
 interface ComponentsListRendererProps extends JssInjectedProps {
-	items: Rsg.Component[];
+	items: Rsg.TOCItem[];
 }
 
 export const ComponentsListRenderer: React.FunctionComponent<ComponentsListRendererProps> = ({
 	classes,
 	items,
+}) => {
+	return (
+		<ul className={classes.list}>
+			{items.map(item => (
+				<ComponentsListSectionRenderer key={item.slug} classes={classes} {...item} />
+			))}
+		</ul>
+	);
+};
+
+const ComponentsListSectionRenderer: React.FunctionComponent<Rsg.TOCItem & JssInjectedProps> = ({
+	classes,
+	heading,
+	visibleName,
+	href,
+	content,
+	shouldOpenInNewTab,
+	selected,
+	initialOpen,
 }) => {
 	const {
-		config: { pagePerSection },
+		config: { tocMode },
 	} = useStyleGuideContext();
 
-	const visibleItems = items.filter(item => item.visibleName);
-
-	if (!visibleItems.length) {
-		return null;
-	}
-
-	// Match selected component in both basic routing and pagePerSection routing.
-	const { hash, pathname } = window.location;
-	const windowHash = pathname + (pagePerSection ? hash : getHash(hash));
+	const [open, setOpen] = tocMode !== 'collapse' ? [true, () => {}] : React.useState(!!initialOpen);
 	return (
-		<ul className={classes.list}>
-			{visibleItems.map(({ heading, visibleName, href, content, shouldOpenInNewTab }) => {
-				const isItemSelected = windowHash === href;
-				return (
-					<li
-						className={cx(classes.item, {
-							[classes.isChild]: (!content || !content.props.items.length) && !shouldOpenInNewTab,
-							[classes.isSelected]: isItemSelected,
-						})}
-						key={href}
-					>
-						<Link
-							className={cx(heading && classes.heading)}
-							href={href}
-							target={shouldOpenInNewTab ? '_blank' : undefined}
-						>
-							{visibleName}
-						</Link>
-						{content}
-					</li>
-				);
+		<li
+			className={cx(classes.item, {
+				[classes.isChild]: !content && !shouldOpenInNewTab,
+				[classes.isSelected]: selected,
 			})}
-		</ul>
+			key={href}
+		>
+			<Link
+				className={cx(heading && classes.heading)}
+				href={href}
+				onClick={() => setOpen(!open)}
+				target={shouldOpenInNewTab ? '_blank' : undefined}
+			>
+				{visibleName}
+			</Link>
+			{open ? content : null}
+		</li>
 	);
 };
 

src/client/rsg-components/Context/Context.ts

@@ -2,7 +2,7 @@ import React from 'react';
 
 const StyleGuideContext = React.createContext<StyleGuideContextContents>({
 	codeRevision: 0,
-	config: {} as Rsg.ProcessedStyleguidistConfig,
+	config: {} as Rsg.SanitizedStyleguidistConfig,
 	slots: {},
 	displayMode: 'collapse',
 });
@@ -16,7 +16,7 @@ export interface SlotObject {
 
 export interface StyleGuideContextContents {
 	codeRevision: number;
-	config: Rsg.ProcessedStyleguidistConfig;
+	config: Rsg.SanitizedStyleguidistConfig;
 	slots: Record<string, (SlotObject | React.FunctionComponent<any>)[]>;
 	displayMode: string;
 }

src/client/rsg-components/Link/LinkRenderer.tsx

@@ -23,6 +23,7 @@ interface LinkProps extends JssInjectedProps {
 	className?: string;
 	href?: string;
 	target?: string;
+	onClick?: () => void;
 }
 
 export const LinkRenderer: React.FunctionComponent<LinkProps> = ({

src/client/rsg-components/StyleGuide/StyleGuide.tsx

@@ -112,7 +112,11 @@ export default class StyleGuide extends Component<StyleGuideProps, StyleGuideSta
 					homepageUrl={HOMEPAGE}
 					toc={
 						allSections ? (
-							<TableOfContents sections={allSections} useRouterLinks={pagePerSection} />
+							<TableOfContents
+								sections={allSections}
+								useRouterLinks={pagePerSection}
+								tocMode={config.tocMode}
+							/>
 						) : null
 					}
 					hasSidebar={hasSidebar(displayMode, config.showSidebar)}