chore(docs): Added a new Hover Mode demo

Author: mlaursen

packages/documentation/src/components/Demos/Utils/HoverMode.md

@@ -0,0 +1,16 @@
+`react-md@2.8.0` introduces a new public hover mode API that allows different
+temporary elements like tooltips and popover dialogs to appear immediately after
+an element has been hovered instead of waiting the default hover duration
+(`1s`). To use this functionality you'll need to:
+
+- render the `HoverModeProvider` or `Configuration` (from #layout) component as
+  a parent component
+- use the `useHoverMode` hook to provide the mouse event handlers, visibility,
+  and other functionality
+
+I recommend checking out the
+[useHoverMode type definitions]({{GITHUB_FILE_URL}}/packages/utils/src/hover/useHoverMode.ts)
+for more information around what's returned.
+
+The example below will show how you can use the hover mode API to create a
+Wikipedia-like preview window while hovering over links.

packages/documentation/src/components/Demos/Utils/HoverMode.tsx

@@ -0,0 +1,59 @@
+import React, { ReactElement } from "react";
+import { Text } from "@react-md/typography";
+import { HoverModeProvider } from "@react-md/utils";
+
+import Markdown from "components/Markdown/Markdown";
+import WikipediaPreviewLink from "components/WikipediaPreviewLink";
+
+function DesignLanguageDescription(): ReactElement {
+  return (
+    <Markdown>
+      A **design language** or **design vocabulary** is an overarching scheme or
+      style that guides the design of a complement of products or architectural
+      settings.
+    </Markdown>
+  );
+}
+
+function GoogleNowDescription(): ReactElement {
+  return (
+    <Markdown>
+      **Google Now** was a feature of Google Search of the Google app for
+      Android and iOS. Google Now proactively delivered information to users to
+      predict (based on search habits and other factors) information they may
+      need in the form of informational cards. Google Now branding is no longer
+      used, but the functionality continues in the Google app and its feed.
+    </Markdown>
+  );
+}
+
+export default function HoverMode(): ReactElement {
+  return (
+    // Note: this can be ignored if you are using the `Configuration` component
+    // from `@react-md/utils`
+    <HoverModeProvider>
+      <Text>
+        {/* copy/pasted from https://en.wikipedia.org/wiki/Material_Design */}
+        <strong>Material Design</strong> (codenamed{" "}
+        <strong>Quantum Paper</strong>){" "}
+        <WikipediaPreviewLink
+          href="https://en.wikipedia.org/wiki/Design_language"
+          preview={<DesignLanguageDescription />}
+        >
+          Design Language
+        </WikipediaPreviewLink>{" "}
+        {'"card" motifs that debuted in '}
+        <WikipediaPreviewLink
+          href="https://en.wikipedia.org/wiki/Google_Now"
+          preview={<GoogleNowDescription />}
+        >
+          Google Now
+        </WikipediaPreviewLink>{" "}
+        , Material Design uses more grid-based layouts, responsive animations
+        and transitions, padding, and depth effects such as lighting and
+        shadows. Google announced Material Design on June 25, 2014, at the 2014
+        Google I/O conference.
+      </Text>
+    </HoverModeProvider>
+  );
+}

packages/documentation/src/components/Demos/Utils/index.tsx

@@ -23,6 +23,9 @@ import simpleGridList from "./SimpleGridList.md";
 import GridListSize from "./GridListSize";
 import gridListSize from "./GridListSize.md";
 
+import HoverMode from "./HoverMode";
+import hoverMode from "./HoverMode.md";
+
 const demos = [
   {
     name: "App Size Listener Example",
@@ -59,6 +62,11 @@ const demos = [
     description: gridListSize,
     children: <GridListSize />,
   },
+  {
+    name: "Hover Mode",
+    description: hoverMode,
+    children: <HoverMode />,
+  },
 ];
 
 export default function Utils(): ReactElement {

packages/documentation/src/components/WikipediaPreviewLink/WikipediaPreviewLink.module.scss

@@ -0,0 +1,6 @@
+.dialog {
+  cursor: pointer;
+  max-height: 10rem;
+  max-width: 20rem;
+  overflow: hidden;
+}

packages/documentation/src/components/WikipediaPreviewLink/WikipediaPreviewLink.tsx

@@ -0,0 +1,62 @@
+import React, { ReactElement, ReactNode, useRef } from "react";
+import { DialogContent, FixedDialog } from "@react-md/dialog";
+import { Link } from "@react-md/link";
+import { BELOW_CENTER_ANCHOR, useHoverMode } from "@react-md/utils";
+
+import { useId } from "components/IdProvider";
+
+import styles from "./WikipediaPreviewLink.module.scss";
+
+export interface WikipediaPreviewLinkProps {
+  /**
+   * The wikipedia URL
+   */
+  href: string;
+
+  /**
+   * The content to display in the preview window.
+   */
+  preview: ReactNode;
+
+  /**
+   * The link contents.
+   */
+  children: ReactNode;
+}
+
+export default function WikipediaPreviewLink({
+  href,
+  preview,
+  children,
+}: WikipediaPreviewLinkProps): ReactElement {
+  const id = useId("wiki");
+  const { active, handlers, visible, setVisible } = useHoverMode();
+
+  const linkRef = useRef<HTMLAnchorElement>(null);
+  return (
+    <>
+      <Link ref={linkRef} href={href} {...handlers}>
+        {children}
+      </Link>
+      <FixedDialog
+        aria-label="Wikipedia Preview"
+        id={id}
+        visible={visible}
+        onRequestClose={() => setVisible(false)}
+        {...handlers}
+        fixedTo={linkRef.current}
+        onClick={() => {
+          window.location.href = href;
+        }}
+        disableFocusContainer={active}
+        disableScrollLock={!active}
+        anchor={BELOW_CENTER_ANCHOR}
+        options={{ preventOverlap: true }}
+        overlay={active ? false : undefined}
+        className={styles.dialog}
+      >
+        <DialogContent>{preview}</DialogContent>
+      </FixedDialog>
+    </>
+  );
+}

packages/documentation/src/components/WikipediaPreviewLink/index.ts

@@ -0,0 +1 @@
+export { default } from "./WikipediaPreviewLink";