Add experimental hook-based examples (#1256)

* refactor: rename the hook-example tags in the index

* docs: add a docsite queryarg to switch into experimental mode

This will allow us to test out the hooks-api without having to change what users normally see.

* docs: add headerto chessboard hooks example

* docs: move dustbin box to hooks

* docs: working on hook examples

* docs: get hooks examples compiling

* refactor: make the begin() function optional

* refactor: hooks api cleanup

* docs: add headers to hook-based examples

* fix: use drop return value in useDropTargetHandler

* docs: get dustbin examples working

* docs: update dragLayer example

* docs: fix custom drag layer example

* docs: get hooks working with more examples

* feat: allow the hooks dragPreview to be a promise

* fix: remove text fixtures from hooks examples

Author: darthtrevino

packages/documentation/package.json

@@ -31,6 +31,7 @@
 		"react": "link:../react-dnd/node_modules/react",
 		"react-dnd": "^7.2.1",
 		"react-dnd-documentation-examples": "^7.2.1",
+		"react-dnd-documentation-examples-hooks": "^7.2.1",
 		"react-dnd-html5-backend": "^7.2.0",
 		"react-dnd-test-backend": "^7.2.0",
 		"react-dom": "link:../react-dnd/node_modules/react-dom",

packages/documentation/src/components/header.tsx

@@ -4,17 +4,32 @@ import NavBar from './navbar'
 
 export interface HeaderProps {
 	debugMode?: boolean
+	experimentalMode?: boolean
 }
 
-const DebugModeFlag = () => (
-	<a className="github-fork-ribbon" data-ribbon="Debug Mode" title="Debug Mode">
-		Debug Mode
-	</a>
-)
+const DebugModeFlag = ({ debugMode, experimentalMode }: any) => {
+	if (!debugMode && !experimentalMode) {
+		return null
+	}
+
+	let text = ''
+	if (debugMode && experimentalMode) {
+		text = 'Dbg Experimental.'
+	} else if (debugMode) {
+		text = 'Debug'
+	} else if (experimentalMode) {
+		text = 'Experimental'
+	}
+	return (
+		<a className="github-fork-ribbon" data-ribbon={text} title={text}>
+			{text}
+		</a>
+	)
+}
 
-const Header: React.FC<HeaderProps> = ({ debugMode }) => (
+const Header: React.FC<HeaderProps> = ({ debugMode, experimentalMode }) => (
 	<Container>
-		{debugMode ? <DebugModeFlag /> : null}
+		<DebugModeFlag debugMode={debugMode} experimentalMode={experimentalMode} />
 		<NavBar />
 	</Container>
 )

packages/documentation/src/components/layout.tsx

@@ -14,6 +14,7 @@ import { PageGroup } from '../constants'
 import { APIPages, ExamplePages } from '../constants'
 import Header from './header'
 import './layout.css'
+import { isExperimentalApiMode } from '../util/renderHtmlAst'
 require('prismjs/themes/prism.css')
 const favicon = require('../favicon.png')
 
@@ -31,6 +32,7 @@ const Layout: React.FC<LayoutProps> = props => {
 	const sidebarItems: PageGroup[] = isExampleUrl ? ExamplePages : APIPages
 	const hideSidebar = props.hideSidebar || sitepath === '/about'
 	const debugMode = isDebugMode()
+	const experimentalMode = isExperimentalApiMode()
 	return (
 		<>
 			<Helmet
@@ -47,7 +49,7 @@ const Layout: React.FC<LayoutProps> = props => {
 					href="https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.2/gh-fork-ribbon.min.css"
 				/>
 			</Helmet>
-			<Header debugMode={debugMode} />
+			<Header debugMode={debugMode} experimentalMode={experimentalMode} />
 			<DragDropContextProvider backend={HTML5Backend} debugMode={debugMode}>
 				<ContentContainer>
 					<PageBody hasSidebar={sitepath !== '/about'}>

packages/documentation/src/util/renderHtmlAst.ts

@@ -1,14 +1,27 @@
 declare var require: any
 import { createElement } from 'react'
 import { componentIndex } from 'react-dnd-documentation-examples/lib/esm/index'
+import { componentIndex as hookComponentIndex } from 'react-dnd-documentation-examples-hooks/lib/esm/index'
+import { parse } from 'query-string'
 import processImages from './processImagesInMarkdownAst'
 const log = require('debug')('site:renderHtmlAst')
 const rehypeReact = require('rehype-react')
 
+export function isExperimentalApiMode() {
+	if (typeof window !== 'undefined') {
+		const queryObject = parse(window.location.search)
+		return queryObject.experimental !== undefined
+	} else {
+		return false
+	}
+}
+
 // Registers the examples as custom components
 const renderAst = new rehypeReact({
 	createElement,
-	components: componentIndex,
+	components: {
+		...(isExperimentalApiMode() ? hookComponentIndex : componentIndex),
+	},
 }).Compiler
 
 export default function renderHtmlAst(node: any) {

packages/examples-hooks/src/00 Chessboard/Board.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import * as React from 'react'
 import { BoardSquare } from './BoardSquare'
 import { Knight } from './Knight'
 

packages/examples-hooks/src/00 Chessboard/BoardSquare.tsx

@@ -1,4 +1,4 @@
-import React, { useRef } from 'react'
+import * as React from 'react'
 import { __EXPERIMENTAL_DND_HOOKS_THAT_MAY_CHANGE_AND_BREAK_MY_BUILD__ } from 'react-dnd'
 import { Square } from './Square'
 import { canMoveKnight, moveKnight } from './Game'
@@ -17,7 +17,7 @@ export interface BoardSquareProps {
 export const BoardSquare: React.FC<BoardSquareProps> = (
 	props: BoardSquareProps,
 ) => {
-	const ref = useRef(null)
+	const ref = React.useRef(null)
 	const { isOver, canDrop } = useDrop({
 		ref,
 		type: ItemTypes.KNIGHT,

packages/examples-hooks/src/00 Chessboard/Knight.tsx

@@ -1,4 +1,4 @@
-import React, { useRef, useMemo } from 'react'
+import * as React from 'react'
 import { __EXPERIMENTAL_DND_HOOKS_THAT_MAY_CHANGE_AND_BREAK_MY_BUILD__ } from 'react-dnd'
 import ItemTypes from './ItemTypes'
 import knightImage from './knightImage'
@@ -23,13 +23,12 @@ function createKnightImage() {
 }
 
 export const Knight: React.FC = () => {
-	const ref = useRef(null)
-	const dragPreview = useMemo(createKnightImage, [])
+	const ref = React.useRef(null)
+	const dragPreview = React.useMemo(createKnightImage, [])
 	const { isDragging } = useDrag({
 		ref,
 		type: ItemTypes.KNIGHT,
-		begin: () => ({}),
-		dragPreview,
+		preview: dragPreview,
 		collect: mon => ({
 			isDragging: !!mon.isDragging(),
 		}),

packages/examples-hooks/src/00 Chessboard/Overlay.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import * as React from 'react'
 
 export interface OverlayProps {
 	color: string

packages/examples-hooks/src/00 Chessboard/Square.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import * as React from 'react'
 
 export interface SquareProps {
 	black: boolean

packages/examples-hooks/src/00 Chessboard/index.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from 'react'
+import * as React from 'react'
 import Board from './Board'
 import { observe } from './Game'
 
@@ -16,13 +16,18 @@ const containerStyle: React.CSSProperties = {
  * The Chessboard Tutorial Application
  */
 const ChessboardTutorialApp: React.FC = () => {
-	const [knightPos, setKnightPos] = useState<[number, number]>([1, 7])
+	const [knightPos, setKnightPos] = React.useState<[number, number]>([1, 7])
 
 	// the observe function will return an unsubscribe callback
-	useEffect(() => observe((newPos: [number, number]) => setKnightPos(newPos)))
+	React.useEffect(() =>
+		observe((newPos: [number, number]) => setKnightPos(newPos)),
+	)
 	return (
-		<div style={containerStyle}>
-			<Board knightPosition={knightPos} />
+		<div>
+			<h1>EXPERIMENTAL API</h1>
+			<div style={containerStyle}>
+				<Board knightPosition={knightPos} />
+			</div>
 		</div>
 	)
 }