Add MarkdownEditor and MarkdownViewer components

.changeset/fluffy-cycles-shave.md

@@ -0,0 +1,6 @@
+---
+"@primer/react": patch
+---
+
+- Add `MarkdownEditor` and `MarkdownViewer` draft components. The `MarkdownEditor` is also known as the `CommentBox` component
+- Add `useUnifiedFileSelect`, `useIgnoreKeyboardInputWhileComposing`, `useDynamicTextareaHeight`, and `useSafeAsyncCallback` draft hooks

@types/fzy-js/index.d.ts

@@ -0,0 +1,36 @@
+declare module 'fzy.js' {
+  // as defined by https://github.com/jhawthorn/fzy.js/blob/master/index.js#L189
+  export const SCORE_MIN: typeof Infinity // for -Infinity
+  export const SCORE_MAX: typeof Infinity
+
+  export const SCORE_GAP_LEADING: number
+  export const SCORE_GAP_TRAILING: number
+  export const SCORE_GAP_INNER: number
+  export const SCORE_MATCH_CONSECUTIVE: number
+  export const SCORE_MATCH_SLASH: number
+  export const SCORE_MATCH_WORD: number
+  export const SCORE_MATCH_CAPITAL: number
+  export const SCORE_MATCH_DOT: number
+
+  /**
+   * score
+   * @param searchQuery - the user filter (the "needle")
+   * @param text - full text of the item being matched (the "haystack")
+   * @returns the score
+   */
+  export function score(searchQuery: string, text: string): number
+  /**
+   * positions
+   * @param searchQuery - the user filter (the "needle")
+   * @param text - full text of the item being matched (the "haystack")
+   * @returns the position for each character match in the sequence
+   */
+  export function positions(searchQuery: string, text: string): Array<number>
+  /**
+   * hasMatch
+   * @param searchQuery - the user filter (the "needle")
+   * @param text - full text of the item being matched (the "haystack")
+   * @returns whether or not there is a match in the sequence
+   */
+  export function hasMatch(searchQuery: string, text: string): boolean
+}

docs/content/drafts/MarkdownEditor.mdx

@@ -0,0 +1,162 @@
+---
+componentId: markdown_editor
+title: MarkdownEditor
+status: Draft
+description: Full-featured Markdown input.
+storybook: '/react/storybook?path=/story/forms-markdowneditor--default'
+---
+
+```js
+import {MarkdownEditor} from '@primer/react/drafts'
+```
+
+`MarkdownEditor` is a full-featured editor for GitHub Flavored Markdown, with support for:
+
+- Formatting (keyboard shortcuts & toolbar buttons)
+- File uploads (drag & drop, paste, click to upload)
+- Inline suggestions (emojis, `@` mentions, and `#` references)
+- Saved replies
+- Markdown pasting (ie, paste URL onto selected text to create a link)
+- List editing (create a new list item on `Enter`)
+- Indenting selected text
+
+## Examples
+
+### Minimal Example
+
+A `Label` is always required for accessibility:
+
+```javascript live noinline drafts
+const renderMarkdown = async (markdown) => {
+  // In production code, this would make a query to some external API endpoint to render
+  return "Rendered Markdown."
+}
+
+const MinimalExample = () => {
+  const [value, setValue] = React.useState('')
+
+  return (
+    <MarkdownEditor
+      value={value}
+      onChange={setValue}
+      onRenderPreview={renderMarkdown}
+    >
+      <MarkdownEditor.Label>Minimal Example</MarkdownEditor.Label>
+    </MarkdownEditor>
+  )
+}
+
+render(MinimalExample)
+```
+
+### Suggestions, File Uploads, and Saved Replies
+
+```javascript live noinline drafts
+const renderMarkdown = async (markdown) => "Rendered Markdown."
+
+const uploadFile = async (file) => ({
+  url: `https://example.com/${encodeURIComponent(file.name)}`,
+  file
+})
+
+const emojis = [
+  {name: '+1', character: '👍'},
+  {name: '-1', character: '👎'},
+  {name: 'heart', character: '❤️'},
+  {name: 'wave', character: '👋'},
+  {name: 'raised_hands', character: '🙌'},
+  {name: 'pray', character: '🙏'},
+  {name: 'clap', character: '👏'},
+  {name: 'ok_hand', character: '👌'},
+  {name: 'point_up', character: '☝️'},
+  {name: 'point_down', character: '👇'},
+  {name: 'point_left', character: '👈'},
+  {name: 'point_right', character: '👉'},
+  {name: 'raised_hand', character: '✋'},
+  {name: 'thumbsup', character: '👍'},
+  {name: 'thumbsdown', character: '👎'}
+]
+
+const references = [
+  {id: '1', titleText: 'Add logging functionality', titleHtml: 'Add logging functionality'},
+  {
+    id: '2',
+    titleText: 'Error: `Failed to install` when installing',
+    titleHtml: 'Error: <code>Failed to install</code> when installing'
+  },
+  {id: '3', titleText: 'Add error-handling functionality', titleHtml: 'Add error-handling functionality'}
+]
+
+const mentionables = [
+  {identifier: 'monalisa', description: 'Monalisa Octocat'},
+  {identifier: 'github', description: 'GitHub'},
+  {identifier: 'primer', description: 'Primer'}
+]
+
+const savedReplies = [
+  {name: 'Duplicate', content: 'Duplicate of #'},
+  {name: 'Welcome', content: 'Welcome to the project!\n\nPlease be sure to read the contributor guidelines.'},
+  {name: 'Thanks', content: 'Thanks for your contribution!'}
+]
+
+const MinimalExample = () => {
+  const [value, setValue] = React.useState('')
+
+  return (
+    <MarkdownEditor
+      value={value}
+      onChange={setValue}
+      onRenderPreview={renderMarkdown}
+
+      onUploadFile={uploadFile}
+
+      emojiSuggestions={emojis}
+      referenceSuggestions={references}
+      mentionSuggestions={mentionables}
+
+      savedReplies={savedReplies}
+    >
+      <MarkdownEditor.Label>Suggestions, File Uploads, and Saved Replies Example</MarkdownEditor.Label>
+    </MarkdownEditor>
+  )
+}
+
+render(MinimalExample)
+```
+
+### Custom Buttons
+
+```javascript live noinline drafts
+const renderMarkdown = async (markdown) => "Rendered Markdown."
+
+const MinimalExample = () => {
+  const [value, setValue] = React.useState('')
+
+  return (
+    <MarkdownEditor
+      value={value}
+      onChange={setValue}
+      onRenderPreview={renderMarkdown}
+    >
+      <MarkdownEditor.Label visuallyHidden>Custom Buttons</MarkdownEditor.Label>
+
+      <MarkdownEditor.Toolbar>
+        <MarkdownEditor.ToolbarButton icon={SquirrelIcon} aria-label="Custom button 1" />
+        <MarkdownEditor.DefaultToolbarButtons />
+        <MarkdownEditor.ToolbarButton icon={BugIcon} aria-label="Custom button 2" />
+      </MarkdownEditor.Toolbar>
+
+      <MarkdownEditor.Actions>
+        <MarkdownEditor.ActionButton variant="danger">
+          Cancel
+        </MarkdownEditor.ActionButton>
+        <MarkdownEditor.ActionButton variant="primary">
+          Submit
+        </MarkdownEditor.ActionButton>
+      </MarkdownEditor.Actions>
+    </MarkdownEditor>
+  )
+}
+
+render(MinimalExample)
+```

docs/content/drafts/MarkdownViewer.mdx

@@ -0,0 +1,97 @@
+---
+componentId: markdown_viewer
+title: MarkdownViewer
+status: Draft
+description: Displays rendered Markdown and facilitates interaction.
+---
+
+```js
+import {MarkdownViewer} from '@primer/react/drafts'
+```
+
+The `MarkdownViewer` displays rendered Markdown with appropriate styling and handles interaction (link clicking and checkbox checking/unchecking) with that content.
+
+## Examples
+
+### Simple Example
+
+```javascript live noinline drafts
+const MarkdownViewerExample = () => {
+  return (
+    // eslint-disable-next-line github/unescaped-html-literal
+    <MarkdownViewer dangerousRenderedHtml={{__html: '<strong>Lorem ipsum</strong> dolor sit amet.'}} />
+  )
+}
+
+render(MarkdownViewerExample)
+```
+
+### Link-Handling Example
+
+```javascript live noinline drafts
+const MarkdownViewerExample = () => {
+  return (
+    <MarkdownViewer
+      // eslint-disable-next-line github/unescaped-html-literal
+      dangerousRenderedHtml={{__html: "<a href='https://example.com'>Example link</a>"}}
+      onLinkClick={ev => console.log(ev)}
+    />
+  )
+}
+
+render(MarkdownViewerExample)
+```
+
+### Checkbox Interaction Example
+
+```javascript live noinline drafts
+const markdownSource = `
+text before list
+
+- [ ] item 1
+- [ ] item 2
+
+text after list`
+
+const renderedHtml = `
+<p>text before list</p>
+<ul class='contains-task-list'>
+  <li class='task-list-item'><input type='checkbox' class='task-list-item-checkbox' disabled/> item 1</li>
+  <li class='task-list-item'><input type='checkbox' class='task-list-item-checkbox' disabled/> item 2</li>
+</ul>
+<p>text after list</p>`
+
+const MarkdownViewerExample = () => {
+  return (
+    <MarkdownViewer
+      dangerousRenderedHtml={{__html: renderedHtml}}
+      markdownValue={markdownSource}
+      onChange={value => console.log(value) /* save the value to the server */}
+      disabled={false}
+    />
+  )
+}
+
+render(MarkdownViewerExample)
+```
+
+## Status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: false,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: true,
+    usageExamplesDocumented: false,
+    hasStorybookStories: false,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -155,6 +155,10 @@
       url: /drafts/Dialog
     - title: InlineAutocomplete
       url: /drafts/InlineAutocomplete
+    - title: MarkdownEditor
+      url: /drafts/MarkdownEditor
+    - title: MarkdownViewer
+      url: /drafts/MarkdownViewer
 - title: Deprecated
   children:
     - title: ActionList (legacy)

jest.config.js

@@ -10,5 +10,7 @@ module.exports = {
     '<rootDir>/src/utils/test-helpers.tsx'
   ],
   testMatch: ['<rootDir>/(src|codemods)/**/*.test.[jt]s?(x)', '!**/*.types.test.[jt]s?(x)'],
-  transformIgnorePatterns: ['node_modules/(?!@github/combobox-nav|@koddsson/textarea-caret)']
+  transformIgnorePatterns: [
+    'node_modules/(?!@github/combobox-nav|@koddsson/textarea-caret|@github/markdown-toolbar-element)'
+  ]
 }