refactor: Move hooks to Storybook, #135

src/docs/3-icons.stories.mdx

@@ -8,17 +8,6 @@ import Icon from '../Icon';
 
 5app's SVG icons as React components, powered by styled-components.
 
-## Adding new icons
-
-1. Add new SVG icons to `/src-icons/svg`
-2. Add any new icons as an export inside of `src/icons/index.js`
-3. To make new icons available from the `<Icon />` component, define a `string` name for them in the icon map in `src/Icon/iconMap.js`
-4. Add new icons to this Storybook page for documentation (you'll find it inside of `/src/docs`)
-
-Once that's done, run `npm run build-icons` to convert the SVGs to standalone React components inside of [src/icons](/src/icons).
-
-After that, you can follow the normal instructions for updating/publishing this repo found in the base5-UI Introduction.
-
 ## Overview
 
 <Canvas>
@@ -103,3 +92,14 @@ After that, you can follow the normal instructions for updating/publishing this
 	<Icon name="user" />
 	<Icon name="x" />
 </Canvas>
+
+## Adding new icons
+
+1. Add new SVG icons to `/src-icons/svg`
+2. Add any new icons as an export inside of `src/icons/index.js`
+3. To make new icons available from the `<Icon />` component, define a `string` name for them in the icon map in `src/Icon/iconMap.js`
+4. Add new icons to this Storybook page for documentation (you'll find it inside of `/src/docs`)
+
+Once that's done, run `npm run build-icons` to convert the SVGs to standalone React components inside of [src/icons](/src/icons).
+
+After that, you can follow the normal instructions for updating/publishing this repo found in the base5-UI Introduction.

src/useAriaFeedProps/index.js

@@ -10,8 +10,7 @@ import {useRef} from 'react';
  * @param {object} options
  * @param {bool} options.isLoading - Indicate whether new items are being added to the feed
  * @param {bool} options.totalItemCount - Provide the total number of available items in the feed
- * @returns {Function} props.getWrapperProps
- * @returns {Function} props.getItemProps
+ * @returns {object} An object containing the prop getter functions `{getWrapperProps, getItemProps}`
  */
 
 function useAriaFeedProps({isLoading, totalItemCount = -1}) {

src/useBackLink/BackLinkProvider.js

@@ -141,7 +141,8 @@ BackLinkProvider.propTypes = {
 		.isRequired,
 	/**
 	 * A "dependency array" of values that tell the component whether or
-	 * not the current location should be added to the history array.
+	 * not a new entry should be added for the current location.
+	 * A new entry will be added only if one or more of the array's items have changed.
 	 * All requirements & limitations of `React.useEffect` dependency arrays apply here, too.
 	 */
 	track: PropTypes.array.isRequired,

src/useBackLink/README.mdx → src/useBackLink/README.stories.mdx

@@ -1,13 +1,15 @@
----
-name: useBackLink
-menu: Hooks
----
+import {Meta, ArgsTable} from '@storybook/addon-docs/blocks';
 
-import {Props} from 'docz';
-import BackLinkProvider from './BackLinkProvider';
+import useBackLink, {BackLinkProvider} from './';
+
+<Meta title="Hooks/useBackLink" component={useBackLink} />
 
 # useBackLink
 
+```jsx
+import useBackLink, {BackLinkProvider} from 'base5-ui/useBackLink';
+```
+
 `useBackLink` is a hook that returns a link to the previous page that the user has visited (if available). It can track the user's history across multiple hierarchy levels to avoid circular navigation issues, and allows navigating "up" a page level instead of only "back" to the last page viewed.
 
 ## The problem
@@ -139,4 +141,4 @@ Note that the location passed to `BackLinkProvider` **must not** include the 'wa
 
 ## BackLinkProvider props
 
-<Props isToggle of={BackLinkProvider} />
+<ArgsTable of={BackLinkProvider} />

src/useBreakpoints/README.mdx → src/useBreakpoints/README.stories.mdx

@@ -1,12 +1,15 @@
----
-name: useBreakpoints
-menu: Hooks
----
+import {Meta, ArgsTable} from '@storybook/addon-docs/blocks';
 
-import {Playground} from 'docz';
+import useBreakpoints, {BreakpointsProvider} from './';
+
+<Meta title="Hooks/useBreakpoints" component={useBreakpoints} />
 
 # useBreakpoints
 
+```jsx
+import useBreakpoints, {BreakpointsProvider} from 'base5-ui/useBreakpoints';
+```
+
 A hook that returns an object containing the state of the current theme's media query breakpoints.
 This can be useful when you need to render different markup depending on the user's screen width.
 

src/useChartist/README.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+import useChartist from './';
+
+<Meta title="Hooks/useChartist" component={useChartist} />
+
+# useChartist
+
+```jsx
+import useChartist from 'base5-ui/useChartist';
+```
+
+A simple hook for using [Chartist.js](http://gionkunz.github.io/chartist-js/) in React.
+
+See below for a simplified example, or view the sources of [SimpleChart](https://github.com/5app/base5-ui/tree/master/src/SimpleChart) or [SimpleGauge](https://github.com/5app/base5-ui/tree/master/src/SimpleGauge) for real-world usage examples.
+
+## Example
+
+```jsx
+function MyChart({labels, data, options}) {
+	const chartRef = useRef(null);
+
+	useChartist(chartRef, {
+		type: 'Line',
+		data: {
+			labels,
+			series: [data],
+		},
+		options,
+		preserveAspectRatio: 'none',
+	});
+
+	return <ChartContainer ref={chartRef} />;
+}
+```

src/useEventListener/README.mdx → src/useEventListener/README.stories.mdx

@@ -1,10 +1,15 @@
----
-name: useEventListener
-menu: Hooks
----
+import {Meta, ArgsTable} from '@storybook/addon-docs/blocks';
+
+import useEventListener from './';
+
+<Meta title="Hooks/useEventListener" component={useEventListener} />
 
 # useEventListener
 
+```jsx
+import useEventListener from 'base5-ui/useEventListener';
+```
+
 A simple hook that adds a global event listener & cleans up after it when the component unmounts.
 
 An options object can be added as a third parameter. Available options are:

src/useFocusOnMount/README.mdx → src/useFocusOnMount/README.stories.mdx

@@ -1,16 +1,19 @@
----
-name: useFocusOnMount
-menu: Hooks
----
+import {Meta, Canvas, Story, ArgsTable} from '@storybook/addon-docs/blocks';
 
-import {Playground, Props} from 'docz';
 import Button from '../Button';
 import Stack from '../Stack';
 
 import Dialog from './DemoExample';
+import useFocusOnMount from './';
+
+<Meta title="Hooks/useFocusOnMount" component={useFocusOnMount} />
 
 # useFocusOnMount
 
+```jsx
+import useFocusOnMount from 'base5-ui/useFocusOnMount';
+```
+
 A hook that will focus a chosen element when the component it is in is mounted, and crucially, will move focus back to where it was before when the component unmounts.
 
 This is useful for moving focus into non-modal dialogs (for modal dialogs, please use the Modal component).
@@ -54,23 +57,27 @@ function Dialog({onClose}) {
 }
 ```
 
-<Playground>
-	{() => {
-		const [hasDialog, setHasDialog] = React.useState(false);
-		return (
-			<Stack spacing="s">
-				<Button
-					icon="eye-open"
-					isActive={hasDialog}
-					onClick={() => setHasDialog(prev => !prev)}
-				>
-					Show non-modal dialog
-				</Button>
-				{hasDialog && <Dialog onClose={() => setHasDialog(false)} />}
-			</Stack>
-		);
-	}}
-</Playground>
+<Canvas>
+	<Story name="Dialog example">
+		{() => {
+			const [hasDialog, setHasDialog] = React.useState(false);
+			return (
+				<Stack spacing="s">
+					<Button
+						icon="eye-open"
+						isActive={hasDialog}
+						onClick={() => setHasDialog(prev => !prev)}
+					>
+						Show non-modal dialog
+					</Button>
+					{hasDialog && (
+						<Dialog onClose={() => setHasDialog(false)} />
+					)}
+				</Stack>
+			);
+		}}
+	</Story>
+</Canvas>
 
 ## Options
 

src/useHasMounted/README.stories.mdx

@@ -0,0 +1,13 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+import useHasMounted from './';
+
+<Meta title="Hooks/useHasMounted" component={useHasMounted} />
+
+# useHasMounted
+
+```jsx
+import useHasMounted from 'base5-ui/useHasMounted';
+```
+
+A simple hook that will return `true` only when the host component is rendered on the client. Causes an instant double-render, so it may be best to use a third-party hook like [useIsMounted](https://usehooks-typescript.com/react-hook/use-is-mounted) instead.

src/useInterval/README.mdx → src/useInterval/README.stories.mdx

@@ -1,21 +1,22 @@
----
-name: useInterval
-menu: Hooks
----
+import {Meta} from '@storybook/addon-docs/blocks';
 
-import {Playground} from 'docz';
+import useInterval from './';
+
+<Meta title="Hooks/useInterval" component={useInterval} />
 
 # useInterval
 
+```jsx
+import useInterval from 'base5-ui/useInterval';
+```
+
 A hook for safely & declaratively setting up intervals in functional React components.
 
 Based on Dan Abramov's blog post ["Making setInterval Declarative with React Hooks"](https://overreacted.io/making-setinterval-declarative-with-react-hooks/)
 
 ## Example
 
 ```jsx
-import useInterval from 'base5-ui/useInterval';
-
 function Counter() {
 	const [count, setCount] = useState(0);
 

src/useMergedRefs/README.stories.mdx

@@ -0,0 +1,28 @@
+import {Meta} from '@storybook/addon-docs/blocks';
+
+import useMergedRefs from './';
+
+<Meta title="Hooks/useMergedRefs" component={useMergedRefs} />
+
+# useMergedRefs
+
+```jsx
+import useMergedRefs from 'base5-ui/useMergedRefs';
+```
+
+A hook for efficiently merging React refs. Usually used inside of a component that needs to expose a public ref via `React.forwardRef` while also using a ref locally. Supports both callback and object refs.
+
+## Example
+
+```jsx
+const AutoFocusingInput = forwardRef((props, ref) => {
+	const inputRef = useRef();
+	const mergedRefs = useMergedRefs([ref, inputRef]);
+
+	useEffect(() => {
+		inputRef.current.focus();
+	}, []);
+
+	return <input type="text" ref={mergedRefs} />;
+});
+```