New: Accept styles config as a function (#1490)

* accept styles as a function

* fix error

* update typings

* add test for function

* remove console.log

* fix typings

* avoid using custom styles

* update documentation

* update customized example

* add cooment in example

* typo in documentation

Co-Authored-By: Artem Sapegin <[email protected]>

* force rebuild for testing

Author: Barthélémy Ledoux

docs/Configuration.md

@@ -599,12 +599,29 @@ Folder for static HTML style guide generated with `styleguidist build` command.
 
 #### `styles`
 
-Type: `object`, optional
+Type: `Object` or `Function`, optional
 
 Customize styles of any Styleguidist’s component.
 
 See example in the [cookbook](Cookbook.md#how-to-change-styles-of-a-style-guide).
 
+> **Note:** Using a function allows access to theme variables as seen in the example below. See available [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/client/styles/theme.ts). The returned object folows the same format as when configured as a litteral.
+
+```javascript
+module.exports = {
+  styles: function(theme) {
+    return {
+      Logo: {
+        logo: {
+          // we can now change the color used in the logo item to use the theme's `link` color
+          color: theme.color.link
+        }
+      }
+    }
+  }
+}
+```
+
 #### `template`
 
 Type: `Object` or `Function`, optional.
@@ -690,22 +707,22 @@ Function that modifies code example (Markdown fenced code block). For example, y
 
 ```javascript
 module.exports = {
-	updateExample(props, exampleFilePath) {
-		const { settings, lang } = props
-		if (typeof settings.file === 'string') {
-			const filepath = path.resolve(
-				path.dirname(exampleFilePath),
-				settings.file
-			)
-			const { file, ...restSettings } = settings;
-			return {
-				content: fs.readFileSync(filepath, 'utf8'),
-				settings: restSettings,
-				lang,
-			}
-		}
-		return props
-	}
+  updateExample(props, exampleFilePath) {
+    const { settings, lang } = props
+    if (typeof settings.file === 'string') {
+      const filepath = path.resolve(
+        path.dirname(exampleFilePath),
+        settings.file
+      )
+      const { file, ...restSettings } = settings
+      return {
+        content: fs.readFileSync(filepath, 'utf8'),
+        settings: restSettings,
+        lang
+      }
+    }
+    return props
+  }
 }
 ```
 

docs/Cookbook.md

@@ -266,6 +266,23 @@ module.exports = {
 
 > **Note:** Use [React Developer Tools](https://github.com/facebook/react) to find component and style names. For example a component `<LogoRenderer><h1 className="rsg--logo-53">` corresponds to an example above.
 
+> **Note:** Use a function instead of an object for [styles](Configuration.md#styles) to access all heme variables in your custom styles.
+
+```javascript
+module.exports = {
+  styles: function(theme) {
+    return {
+      Logo: {
+        logo: {
+          // we can now change the color used in the logo item to use the theme's `link` color
+          color: theme.color.link
+        }
+      }
+    }
+  }
+}
+```
+
 ## How to change the layout of a style guide?
 
 You can replace any Styleguidist React component. But in most of the cases you’ll want to replace `*Renderer` components — all HTML is rendered by these components. For example `ReactComponentRenderer`, `ComponentsListRenderer`, `PropsRenderer`, etc. — [check the source](https://github.com/styleguidist/react-styleguidist/tree/master/src/client/rsg-components) to see what components are available.

examples/customised/styleguide.config.js

@@ -11,24 +11,24 @@ module.exports = {
 		border: '#e0d2de',
 		font: ['Helvetica', 'sans-serif'],
 	},
-	styles: {
-		Playground: {
-			preview: {
-				paddingLeft: 0,
-				paddingRight: 0,
-				borderWidth: [[0, 0, 1, 0]],
-				borderRadius: 0,
-			},
-		},
-		Markdown: {
-			pre: {
-				border: 0,
-				background: 'none',
+	styles: function styles(theme) {
+		return {
+			Playground: {
+				preview: {
+					paddingLeft: 0,
+					paddingRight: 0,
+					borderWidth: [[0, 0, 1, 0]],
+					borderRadius: 0,
+				},
 			},
-			code: {
-				fontSize: 14,
+			Code: {
+				code: {
+					// make inline code example appear the same color as links
+					color: theme.color.link,
+					fontSize: 14,
+				},
 			},
-		},
+		};
 	},
 	getComponentPathLine(componentPath) {
 		const name = path.basename(componentPath, '.js');

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

@@ -8,7 +8,7 @@ export interface JssInjectedProps {
 }
 
 export default function StyleHOC<P extends JssInjectedProps>(
-	styles: Styles
+	styles: (t: Rsg.Theme) => Styles<string>
 ): (WrappedComponent: ComponentType<P>) => ComponentType<Omit<P, keyof JssInjectedProps>> {
 	return (WrappedComponent: ComponentType<P>) => {
 		const componentName = WrappedComponent.name.replace(/Renderer$/, '');

src/client/styles/__tests__/createStyleSheet.spec.ts

@@ -7,6 +7,8 @@ const customThemeMaxWidth = 9999;
 
 const customStyleBorderColor = '#ABCDEF';
 
+const customThemeLinkColor = '#CCCAAA';
+
 const testComponentName = 'TestComponentName';
 const testRuleName = 'testRule';
 
@@ -21,10 +23,12 @@ const styles = ({ color, borderRadius, maxWidth }: Rsg.Theme) => ({
 });
 
 const config = {
+	hello: 0,
 	theme: {
 		color: {
 			base: customThemeColor,
 			border: customThemeBorderColor,
+			link: customThemeLinkColor,
 		},
 		maxWidth: customThemeMaxWidth,
 	},
@@ -37,6 +41,20 @@ const config = {
 	},
 };
 
+const configWithStylesAsAFunction = {
+	hello: 1,
+	...config,
+	styles: (locTheme: Rsg.Theme) => {
+		return {
+			[testComponentName]: {
+				[testRuleName]: {
+					borderColor: locTheme.color.link,
+				},
+			},
+		};
+	},
+};
+
 describe('createStyleSheet', () => {
 	it('should use theme variables', () => {
 		const styleSheet = createStyleSheet(styles, config, testComponentName);
@@ -60,4 +78,15 @@ describe('createStyleSheet', () => {
 
 		expect(style['border-color']).toBe(customStyleBorderColor);
 	});
+
+	it('should override config theme variables with config styles as a function', () => {
+		// remove cache from memoize since we changed config
+		if (createStyleSheet && createStyleSheet.cache && createStyleSheet.cache.clear) {
+			createStyleSheet.cache.clear();
+		}
+		const styleSheet = createStyleSheet(styles, configWithStylesAsAFunction, testComponentName);
+		const style = (styleSheet.getRule(testRuleName) as any).style;
+
+		expect(style['border-color']).toBe(customThemeLinkColor);
+	});
 });

src/client/styles/createStyleSheet.ts

@@ -1,15 +1,23 @@
 import merge from 'lodash/merge';
 import memoize from 'lodash/memoize';
-import { Styles } from 'jss';
+import { Styles, StyleSheet } from 'jss';
 import jss from './setupjss';
 import * as theme from './theme';
 
-export default memoize((styles, config: Rsg.StyleguidistConfig, componentName) => {
-	const mergedTheme: Rsg.Theme = merge({}, theme, config.theme);
-	const mergedStyles: Partial<Styles<string>> = merge(
-		{},
-		styles(mergedTheme),
-		config.styles && config.styles[componentName]
-	);
-	return jss.createStyleSheet(mergedStyles, { meta: componentName, link: true });
-});
+export default memoize(
+	(
+		styles: (t: Rsg.Theme) => Styles<string>,
+		config: Rsg.StyleguidistConfig,
+		componentName: string
+	): StyleSheet<string> => {
+		const mergedTheme: Rsg.Theme = merge({}, theme, config.theme);
+		const customStyles =
+			typeof config.styles === 'function' ? config.styles(mergedTheme) : config.styles;
+		const mergedStyles: Partial<Styles<string>> = merge(
+			{},
+			styles(mergedTheme),
+			customStyles && customStyles[componentName]
+		);
+		return jss.createStyleSheet(mergedStyles, { meta: componentName, link: true });
+	}
+);

src/scripts/schemas/config.ts

@@ -275,7 +275,7 @@ const configSchema: Record<StyleguidistConfigKey, ConfigSchemaOptions<Rsg.Styleg
 		default: 'styleguide',
 	},
 	styles: {
-		type: 'object',
+		type: ['object', 'function'],
 		default: {},
 		example: {
 			Logo: {

src/typings/RsgStyles.d.ts

@@ -4,6 +4,7 @@ import { TransformOptions } from 'buble';
 import { Handler, DocumentationObject, PropDescriptor } from 'react-docgen';
 import { ASTNode } from 'ast-types';
 import { NodePath } from 'ast-types/lib/node-path';
+import { Styles } from 'jss';
 
 declare global {
 	namespace Rsg {
@@ -73,7 +74,7 @@ declare global {
 			sortProps(props: PropDescriptor[]): PropDescriptor[];
 			styleguideComponents: Record<string, string>;
 			styleguideDir: string;
-			styles: Styles;
+			styles: Styles | ((theme: Theme) => Styles);
 			template: any;
 			theme: Theme;
 			title: string;