storybook: add next gen docs format mdx; code documentation and clean…

…up; more tests
davidcalhoun · Nov 21, 2019 · 0cb7a6d · 0cb7a6d
1 parent 5bd8d22
commit 0cb7a6d
Show file tree

Hide file tree

Showing 18 changed files with 5,080 additions and 2,088 deletions.
diff --git a/.storybook/addons.js b/.storybook/addons.js
diff --git a/.storybook/config.js b/.storybook/config.js
@@ -1,3 +1,11 @@
-import { configure } from '@storybook/react';
+import { configure, addParameters } from '@storybook/react';
+import { DocsPage, DocsContainer } from '@storybook/addon-docs/blocks';
 
-configure(require.context('../src', true, /\.stories\.js$/), module);
+addParameters({
+  docs: {
+    container: DocsContainer,
+    page: DocsPage,
+  },
+});
+
+configure(require.context('../src', true, /\.stories\.(js|mdx)$/), module);
diff --git a/.storybook/presets.js b/.storybook/presets.js
@@ -0,0 +1,3 @@
+module.exports = [
+  "@storybook/addon-docs/react/preset"
+];
diff --git a/.storybook/webpack.config.js b/.storybook/webpack.config.js
@@ -26,14 +26,10 @@ module.exports = async ({ config, mode }) => {
         }
       }
     ],
-    include: path.resolve(__dirname, '../src'),
-  });
-
-  // Needed for addon-storysource
-  config.module.rules.push({
-    test: /\.stories\.jsx?$/,
-    loaders: [require.resolve('@storybook/source-loader')],
-    enforce: 'pre',
+    include: [
+      path.resolve(__dirname, '../src'),
+      path.resolve(__dirname, '../node_modules/@storybook/addon-info'),
+    ]
   });
 
   return config;

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -33,8 +33,8 @@
     "@babel/plugin-proposal-export-default-from": "^7.5.2",
     "@babel/preset-env": "^7.6.3",
     "@babel/preset-react": "^7.6.3",
-    "@storybook/addon-storysource": "^5.2.6",
-    "@storybook/react": "^5.2.5",
+    "@storybook/addon-docs": "^5.2.6",
+    "@storybook/react": "^5.2.6",
     "@testing-library/dom": "^6.10.0",
     "@testing-library/jest-dom": "^4.2.0",
     "@testing-library/react": "^9.3.0",

diff --git a/src/HoverSlideshow.js b/src/HoverSlideshow.js
@@ -3,8 +3,23 @@ import PropTypes from "prop-types";
 import useHoverSlideshow from "./useHoverSlideshow";
 import styles from "./HoverSlideshow.css";
 
+/**
+ * TODO: support images array of objects, to support alt titles for each image.
+ */
+
+/**
+ * Cycles through an image slideshow on cursor/touch movement across an image.
+ */
 export default function HoverSlideshow(props) {
-	const { axis, images, width, height, style, ...otherProps } = props;
+	const {
+		axis,
+		images,
+		width,
+		height,
+		style,
+		className,
+		...otherProps
+	} = props;
 
 	let [
 		// Current image href, which will update on mousemove/touchmove
@@ -21,7 +36,7 @@ export default function HoverSlideshow(props) {
 			onTouchStart={updateHoverSlideshow}
 			onTouchMove={updateHoverSlideshow}
 			onTouchEnd={resetHoverSlideshow}
-			className={styles.container}
+			className={`${styles.container} ${className}`}
 			style={{
 				width,
 				height,
@@ -45,12 +60,29 @@ export default function HoverSlideshow(props) {
 }
 
 HoverSlideshow.propTypes = {
-	images: PropTypes.arrayOf(PropTypes.string)
+	/** ARIA label to add to container. */
+	"aria-label": PropTypes.string,
+	/** Axis to monitor cursor/touch "progress" on. */
+	axis: PropTypes.oneOf(["horizontal", "vertical"]),
+	/** Additional CSS classnames to add to the root container. */
+	className: PropTypes.string,
+	/** Height of the container, e.g. "100px" */
+	height: PropTypes.string,
+	/** Array of image hrefs. */
+	images: PropTypes.arrayOf(PropTypes.string),
+	/** ARIA role to add to image container. */
+	role: PropTypes.string,
+	/** Custom CSS style overrides. */
+	style: PropTypes.object,
+	/** Width of the container, e.g. "100px" */
+	width: PropTypes.string
 };
 
 HoverSlideshow.defaultProps = {
 	"aria-label": "Image slideshow",
 	axis: "horizontal",
+	className: "",
 	images: [],
-	role: "img"
+	role: "img",
+	style: {}
 };
diff --git a/src/HoverSlideshow.stories.js b/src/HoverSlideshow.stories.js
diff --git a/src/HoverSlideshow.stories.mdx b/src/HoverSlideshow.stories.mdx
@@ -0,0 +1,70 @@
+import {
+	Meta,
+	Story,
+	Preview,
+	Props,
+	Description
+} from "@storybook/addon-docs/blocks";
+import HoverSlideshow from "./HoverSlideshow";
+
+<Meta title="Demos|HoverSlideshow" component={HoverSlideshow} />
+
+# HoverSlideshow
+
+<br />
+
+## Description
+
+<Description of={HoverSlideshow} />
+
+## Props
+
+<Props of={HoverSlideshow} />
+
+## Preview
+
+<Preview>
+	<Story name="default (horizontal axis)">
+		<HoverSlideshow
+			aria-label="Muybridge horse gallop slideshow"
+			width="410px"
+			height="308px"
+			images={[
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/01.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/02.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/03.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/04.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/05.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/06.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/07.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/08.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/09.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/10.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/11.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/12.jpg"
+			]}
+		/>
+	</Story>
+	<Story name="vertical axis">
+		<HoverSlideshow
+			axis="vertical"
+			aria-label="Muybridge horse gallop slideshow"
+			width="410px"
+			height="308px"
+			images={[
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/01.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/02.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/03.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/04.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/05.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/06.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/07.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/08.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/09.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/10.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/11.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/12.jpg"
+			]}
+		/>
+	</Story>
+</Preview>
diff --git a/src/HoverSlideshowAnimated.css b/src/HoverSlideshowAnimated.css
@@ -1,5 +1,6 @@
 .container {
 	position: relative;
+	display: inline-block;
 }
 
 .imageContainer {

diff --git a/src/HoverSlideshowAnimated.js b/src/HoverSlideshowAnimated.js
@@ -4,6 +4,13 @@ import { CSSTransition, TransitionGroup } from "react-transition-group";
 import useHoverSlideshow from "./useHoverSlideshow";
 import styles from "./HoverSlideshowAnimated.css";
 
+/**
+ * Cycles through an image slideshow on cursor/touch movement across an image.  Uses CSS transitions to achieve a crossfade effect.
+ *
+ * Note: this component depends on the optional peer dependency `react-transition-group`, which can be installed with this command:
+ *
+ * ```npm i --save react-transition-group```
+ */
 export default function HoverSlideshowAnimated(props) {
 	const { images, style, className, href, width, height } = props;
 	let [
@@ -24,10 +31,12 @@ export default function HoverSlideshowAnimated(props) {
 				onMouseMove={updateHoverSlideshow}
 				style={{
 					width,
-					height
+					height,
+					...style
 				}}
+				className={`${ styles.container } ${ className }`}
 			>
-				<TransitionGroup className={styles.container}>
+				<TransitionGroup>
 					<CSSTransition
 						timeout={300}
 						classNames={{
@@ -53,12 +62,22 @@ export default function HoverSlideshowAnimated(props) {
 }
 
 HoverSlideshowAnimated.propTypes = {
+	/** Additional CSS classnames to add to the root container. */
+	className: PropTypes.string,
+	/** Height of the container, e.g. "100px" */
+	height: PropTypes.string,
+	/** Optional href to add to anchor wrapper. */
+	href: PropTypes.string,
+	/** Array of image hrefs. */
 	images: PropTypes.arrayOf(PropTypes.string),
+	/** Custom CSS style overrides. */
 	style: PropTypes.object,
-	className: PropTypes.string,
-	href: PropTypes.string
+	/** Width of the container, e.g. "100px" */
+	width: PropTypes.string
 };
 
 HoverSlideshowAnimated.defaultProps = {
-	images: []
+	className: "",
+	images: [],
+	style: {}
 };
diff --git a/src/HoverSlideshowAnimated.stories.js b/src/HoverSlideshowAnimated.stories.js
diff --git a/src/HoverSlideshowAnimated.stories.mdx b/src/HoverSlideshowAnimated.stories.mdx
@@ -0,0 +1,49 @@
+import {
+	Meta,
+	Story,
+	Preview,
+	Props,
+	Description
+} from "@storybook/addon-docs/blocks";
+import HoverSlideshowAnimated from "./HoverSlideshowAnimated";
+import { createNumberedArray } from "./utils";
+
+<Meta title="Demos|HoverSlideshowAnimated" component={HoverSlideshowAnimated} />
+
+# HoverSlideshowAnimated
+
+<br />
+
+## Description
+
+<Description of={HoverSlideshowAnimated} />
+
+## Props
+
+<Props of={HoverSlideshowAnimated} />
+
+## Preview
+
+<Preview>
+	<Story name="default">
+		<HoverSlideshowAnimated
+			aria-label="Muybridge horse gallop slideshow"
+			width="410px"
+			height="308px"
+			images={[
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/01.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/02.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/03.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/04.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/05.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/06.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/07.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/08.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/09.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/10.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/11.jpg",
+				"https://raw.githubusercontent.com/davidcalhoun/react-hover-slideshow/master/static/12.jpg"
+			]}
+		/>
+	</Story>
+</Preview>