docs: explain how to use hook useMentionAtom (remirror#1081)

docs/hooks/use-mention-atom.md

@@ -0,0 +1,18 @@
+---
+hide_title: true
+title: 'useMentionAtom'
+---
+
+# `useMentionAtom`
+
+## Summary
+
+A hook that provides the state for social mention atoms that responds to keybindings and key-presses from the user.
+
+- The difference between this and the `useMention` is that `useMention` creates editable mentions that can be changed over an over again. This creates atom mention which are inserted into the editor as non editable nodes. Backspacing into this node will delete the whole mention.
+- In order to properly support keybindings you will need to provide a list of data that is to be shown to the user. This allows for the user to press the arrow up and arrow down key.
+- You can also add other supported attributes which will be added to the mention node, like `href` and whatever you decide upon.
+
+## Examples
+
+See [storybook](https://remirror.vercel.app/?path=/story/react-hooks-usementionatom--basic) for examples.

packages/remirror__react-hooks/__stories__/tsconfig.json

@@ -0,0 +1,80 @@
+{
+  "__AUTO_GENERATED__": [
+    "To update the configuration edit the following field.",
+    "`package.json > @remirror > tsconfigs > '__stories__'`",
+    "",
+    "Then run: `pnpm -w generate:ts`"
+  ],
+  "extends": "../../../support/tsconfig.base.json",
+  "compilerOptions": {
+    "types": [],
+    "declaration": false,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "importsNotUsedAsValues": "remove",
+    "paths": {
+      "react": [
+        "../../../node_modules/.pnpm/@[email protected]/node_modules/@types/react/index.d.ts"
+      ],
+      "react/jsx-dev-runtime": [
+        "../../../node_modules/.pnpm/@[email protected]/node_modules/@types/react/jsx-dev-runtime.d.ts"
+      ],
+      "react/jsx-runtime": [
+        "../../../node_modules/.pnpm/@[email protected]/node_modules/@types/react/jsx-runtime.d.ts"
+      ],
+      "react-dom": [
+        "../../../node_modules/.pnpm/@[email protected]/node_modules/@types/react-dom/index.d.ts"
+      ],
+      "reakit": [
+        "../../../node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/reakit/ts/index.d.ts"
+      ],
+      "@remirror/react": ["../../remirror__react/src/index.ts"],
+      "@storybook/react": [
+        "../../../node_modules/.pnpm/@[email protected]_dfad392d5450b8683a621f3ec486af19/node_modules/@storybook/react/types-6-0.d.ts"
+      ],
+      "@remirror/dev": ["../../remirror__dev/src/index.ts"]
+    }
+  },
+  "include": ["./"],
+  "references": [
+    {
+      "path": "../../testing/src"
+    },
+    {
+      "path": "../../remirror/src"
+    },
+    {
+      "path": "../../remirror__core/src"
+    },
+    {
+      "path": "../../remirror__extension-emoji/src"
+    },
+    {
+      "path": "../../remirror__extension-events/src"
+    },
+    {
+      "path": "../../remirror__extension-history/src"
+    },
+    {
+      "path": "../../remirror__extension-mention/src"
+    },
+    {
+      "path": "../../remirror__extension-mention-atom/src"
+    },
+    {
+      "path": "../../remirror__extension-positioner/src"
+    },
+    {
+      "path": "../../remirror__i18n/src"
+    },
+    {
+      "path": "../../remirror__react-core/src"
+    },
+    {
+      "path": "../../remirror__react-utils/src"
+    },
+    {
+      "path": "../../multishift/src"
+    }
+  ]
+}

packages/remirror__react-hooks/__stories__/use-mention-atom-styles.css

@@ -0,0 +1,17 @@
+.remirror-theme {
+  /* Provide sufficient space to see the popup */
+  --rmr-space-6: 400px;
+}
+.suggestions {
+  border: 1px solid darkgray;
+  border-radius: 4px;
+}
+.suggestion {
+  padding: 2px 8px;
+}
+.highlighted {
+  background: #7963d233;
+}
+.hovered {
+  background: #7963d222;
+}

packages/remirror__react-hooks/__stories__/use-mention-atom.stories.tsx

@@ -0,0 +1,87 @@
+import './use-mention-atom-styles.css';
+
+import { useCallback, useEffect, useState } from 'react';
+import { PlaceholderExtension } from 'remirror/extensions';
+import { cx } from '@remirror/core';
+import { MentionAtomExtension, MentionAtomNodeAttributes } from '@remirror/extension-mention-atom';
+import { FloatingWrapper, Remirror, ThemeProvider, useRemirror } from '@remirror/react';
+
+import { useMentionAtom } from '../src/use-mention-atom';
+
+export default { title: 'React Hooks / useMentionAtom' };
+
+const ALL_USERS = [
+  { id: 'joe', label: 'Joe' },
+  { id: 'sue', label: 'Sue' },
+  { id: 'pat', label: 'Pat' },
+  { id: 'tom', label: 'Tom' },
+  { id: 'jim', label: 'Jim' },
+];
+
+function UserSuggestor() {
+  const [users, setUsers] = useState<MentionAtomNodeAttributes[]>([]);
+  const { state, getMenuProps, getItemProps, indexIsHovered, indexIsSelected } = useMentionAtom({
+    items: users,
+  });
+
+  useEffect(() => {
+    if (!state) {
+      return;
+    }
+
+    const searchTerm = state.query.full.toLowerCase();
+    const filteredUsers = ALL_USERS.filter((user) => user.label.toLowerCase().includes(searchTerm))
+      .sort()
+      .slice(0, 5);
+    setUsers(filteredUsers);
+  }, [state]);
+
+  const enabled = !!state;
+
+  return (
+    <FloatingWrapper positioner='cursor' enabled={enabled} placement='bottom-start'>
+      <div {...getMenuProps()} className='suggestions'>
+        {enabled &&
+          users.map((user, index) => {
+            const isHighlighted = indexIsSelected(index);
+            const isHovered = indexIsHovered(index);
+
+            return (
+              <div
+                key={user.id}
+                className={cx('suggestion', isHighlighted && 'highlighted', isHovered && 'hovered')}
+                {...getItemProps({
+                  item: user,
+                  index,
+                })}
+              >
+                {user.label}
+              </div>
+            );
+          })}
+      </div>
+    </FloatingWrapper>
+  );
+}
+
+export const Basic = (): JSX.Element => {
+  const extensions = useCallback(
+    () => [
+      new MentionAtomExtension({
+        extraAttributes: { type: 'user' },
+        matchers: [{ name: 'at', char: '@', appendText: ' ', matchOffset: 0 }],
+      }),
+      new PlaceholderExtension({ placeholder: `Mention a @user` }),
+    ],
+    [],
+  );
+  const { manager } = useRemirror({ extensions });
+
+  return (
+    <ThemeProvider>
+      <Remirror manager={manager} autoRender='end'>
+        <UserSuggestor />
+      </Remirror>
+    </ThemeProvider>
+  );
+};

support/root/tsconfig.json

@@ -539,6 +539,9 @@
     {
       "path": "packages/remirror__react-editors/src"
     },
+    {
+      "path": "packages/remirror__react-hooks/__stories__"
+    },
     {
       "path": "packages/remirror__react-hooks/__tests__"
     },