Merge pull request #10 from github/preserve-markup

Quote markdown tweaks

Author: mislav

README.md

@@ -1,6 +1,6 @@
-# Quote Markdown selection
+# Quote selection
 
-Install a shortcut `r` to append selected text to a `<textarea>` as a Markdown quote.
+Install a keyboard shortcut <kbd>r</kbd> to append selected text to a `<textarea>` as a Markdown quote.
 
 ## Installation
 
@@ -10,53 +10,36 @@ $ npm install @github/quote-selection
 
 ## Usage
 
-### HTML
-
 ```html
-<div data-quote-region>
+<div class="my-quote-region">
   <p>Text to quote</p>
   <textarea></textarea>
 </div>
 ```
 
-#### Quote as Markdown
-
-An optional feature to translate quoted content into Markdown format is available via the `data-quote-markdown` attribute:
+```js
+import {install} from '@github/quote-selection'
 
-```html
-<div data-quote-region data-quote-markdown=".comment-body">
-  <div class="comment-body">
-    <h2><strong>Formatted</strong> text <em>to quote</em></h2>
-    <p>
-      Preserves <code>inline code</code> and
-      <a href="https://guides.github.com/features/mastering-markdown/">other features</a>.
-    </p>
-  </div>
-  <div class="comment-body">
-    <p>Some other text</p>
-  </div>
-  <textarea></textarea>
-</div>
+install(document.querySelector('.my-quote-region'))
 ```
 
-When selected, the text within the first `.comment-body` element will get quoted as:
+This sets up a keyboard event handler so that selecting any text within `.my-quote-region` and pressing <kbd>r</kbd> appends the quoted representation of the selected text into the first applicable `<textarea>` element.
 
-```
-> ## **Formatted** text _to quote_
->
-> Preserves `inline code` and [other features](https://guides.github.com/features/mastering-markdown/).
-```
-
-### JS
+### Preserving Markdown syntax
 
 ```js
-import {install} from '@github/quote-selection'
-install(document.querySelector('[data-quote-region]'))
+install(element, {
+  quoteMarkdown: true,
+  scopeSelector: '.comment-body'
+})
 ```
 
+The optional `scopeSelector` parameter ensures that even if the user selection bleeds outside of the scoped element, the quoted portion will always be contained inside the scope. This is useful to avoid accidentally quoting parts of the UI that might be interspersed between quotable content.
+
 ## Events
 
-A `quote-selection` event is fired on the quote region before text is appended to a textarea. Listen to the event to prepare the textarea or manipulate the selection text.
+* `quote-selection-markdown` (bubbles: true, cancelable: false) - fired on the quote region to optionally inject custom syntax into the `fragment` element in `quoteMarkdown: true` mode
+* `quote-selection` (bubbles: true, cancelable: true) - fired on the quote region before text is appended to a textarea
 
 For example, reveal a textarea so it can be found:
 

markdown-parsing.js

@@ -1,9 +1,5 @@
 /* @flow */
 
-function matches(el: Element, ...names: Array<string>): boolean {
-  return names.some(name => el.classList.contains(name))
-}
-
 function indexInList(li: Element): number {
   if (li.parentNode === null || !(li.parentNode instanceof HTMLElement)) throw new Error()
 
@@ -34,10 +30,6 @@ function isCheckbox(node: Node): boolean {
   return node.nodeName === 'INPUT' && node instanceof HTMLInputElement && node.type === 'checkbox'
 }
 
-function isHighlightContainer(el: HTMLElement): boolean {
-  return el.nodeName === 'DIV' && el.classList.contains('highlight')
-}
-
 let listIndexOffset = 0
 
 function nestedListExclusive(li: Element): boolean {
@@ -73,31 +65,23 @@ const filters: {[key: string]: (HTMLElement) => string | HTMLElement} = {
     const text = el.textContent
 
     if (el.parentNode && el.parentNode.nodeName === 'PRE') {
-      el.textContent = `\`\`\`\n${text.replace(/\n+$/, '')}\n\`\`\``
+      el.textContent = `\`\`\`\n${text.replace(/\n+$/, '')}\n\`\`\`\n\n`
       return el
     }
     if (text.indexOf('`') >= 0) {
       return `\`\` ${text} \`\``
     }
     return `\`${text}\``
   },
-  PRE(el) {
-    const parent = el.parentNode
-    if (parent instanceof HTMLElement && isHighlightContainer(parent)) {
-      const match = parent.className.match(/highlight-source-(\S+)/)
-      const flavor = match ? match[1] : ''
-      const text = el.textContent.replace(/\n+$/, '')
-      el.textContent = `\`\`\`${flavor}\n${text}\n\`\`\``
-      el.append('\n\n')
-    }
-    return el
-  },
   STRONG(el) {
     return `**${el.textContent}**`
   },
   EM(el) {
     return `_${el.textContent}_`
   },
+  DEL(el) {
+    return `~${el.textContent}~`
+  },
   BLOCKQUOTE(el) {
     const text = el.textContent.trim().replace(/^/gm, '> ')
     const pre = document.createElement('pre')
@@ -108,11 +92,7 @@ const filters: {[key: string]: (HTMLElement) => string | HTMLElement} = {
     const text = el.textContent
     const href = el.getAttribute('href')
 
-    if (matches(el, 'user-mention', 'team-mention')) {
-      return text
-    } else if (matches(el, 'issue-link') && /^#\d+$/.test(text)) {
-      return text
-    } else if (/^https?:/.test(text) && text === href) {
+    if (/^https?:/.test(text) && text === href) {
       return text
     } else {
       if (href) {
@@ -124,23 +104,17 @@ const filters: {[key: string]: (HTMLElement) => string | HTMLElement} = {
   },
   IMG(el) {
     const alt = el.getAttribute('alt') || ''
+    const src = el.getAttribute('src')
+    if (!src) throw new Error()
 
-    if (alt && matches(el, 'emoji')) {
-      return alt
-    } else {
-      const src = el.getAttribute('src')
-      if (!src) throw new Error()
-
-      const widthAttr = el.hasAttribute('width') ? ` width="${escapeAttribute(el.getAttribute('width') || '')}"` : ''
-      const heightAttr = el.hasAttribute('height')
-        ? ` height="${escapeAttribute(el.getAttribute('height') || '')}"`
-        : ''
+    const widthAttr = el.hasAttribute('width') ? ` width="${escapeAttribute(el.getAttribute('width') || '')}"` : ''
+    const heightAttr = el.hasAttribute('height') ? ` height="${escapeAttribute(el.getAttribute('height') || '')}"` : ''
 
-      if (widthAttr || heightAttr) {
-        return `<img alt="${escapeAttribute(alt)}"${widthAttr}${heightAttr} src="${escapeAttribute(src)}">`
-      } else {
-        return `![${alt}](${src})`
-      }
+    if (widthAttr || heightAttr) {
+      // eslint-disable-next-line github/unescaped-html-literal
+      return `<img alt="${escapeAttribute(alt)}"${widthAttr}${heightAttr} src="${escapeAttribute(src)}">`
+    } else {
+      return `![${alt}](${src})`
     }
   },
   LI(el) {
@@ -187,12 +161,7 @@ for (let level = 2; level <= 6; ++level) {
   filters[`H${level}`] = filters.H1
 }
 
-// Public: Iterate over all elements within a node that match one of the filters. The
-// iteration is done in reverse as a way of processing deepest matches first.
-function fragmentToMarkdown(
-  root: DocumentFragment,
-  fn: (node: HTMLElement, content: string | HTMLElement) => void
-): void {
+export function insertMarkdownSyntax(root: DocumentFragment): void {
   const nodeIterator = document.createNodeIterator(root, NodeFilter.SHOW_ELEMENT, function(node) {
     if (node.nodeName in filters && !skipNode(node) && (hasContent(node) || isCheckbox(node))) {
       return NodeFilter.FILTER_ACCEPT
@@ -210,13 +179,15 @@ function fragmentToMarkdown(
     node = nodeIterator.nextNode()
   }
 
+  // process deepest matches first
   results.reverse()
+
   for (node of results) {
-    fn(node, filters[node.nodeName](node))
+    node.replaceWith(filters[node.nodeName](node))
   }
 }
 
-export default function rangeToMarkdown(range: Range, selector: string, unwrap: boolean): DocumentFragment {
+export function extractFragment(range: Range, selector: string): DocumentFragment {
   const startNode = range.startContainer
   if (!startNode || !startNode.parentNode || !(startNode.parentNode instanceof HTMLElement)) {
     throw new Error('the range must start within an HTMLElement')
@@ -238,18 +209,8 @@ export default function rangeToMarkdown(range: Range, selector: string, unwrap:
   if (codeBlock) {
     const pre = document.createElement('pre')
     pre.appendChild(fragment)
-    let item = pre
-    if (!unwrap) {
-      const pp = codeBlock.parentNode
-      if (pp instanceof HTMLElement && isHighlightContainer(pp)) {
-        const div = document.createElement('div')
-        div.className = pp.className
-        div.appendChild(item)
-        item = div
-      }
-    }
     fragment = document.createDocumentFragment()
-    fragment.appendChild(item)
+    fragment.appendChild(pre)
   } else if (li && li.parentNode) {
     if (li.parentNode.nodeName === 'OL') {
       listIndexOffset = indexInList(li)
@@ -266,6 +227,6 @@ export default function rangeToMarkdown(range: Range, selector: string, unwrap:
       fragment.appendChild(list)
     }
   }
-  fragmentToMarkdown(fragment, (el, newContent) => el.replaceWith(newContent))
+
   return fragment
 }

quote-selection.js

@@ -1,29 +1,40 @@
 /* @flow */
 
-import rangeToMarkdown from './markdown-parsing'
+import {extractFragment, insertMarkdownSyntax} from './markdown-parsing'
 
-const containers = new WeakMap()
+const containers: WeakMap<Element, ContainerConfig> = new WeakMap()
 let installed = 0
 
 const edgeBrowser = /\bEdge\//.test(navigator.userAgent)
 
+type ConfigOptions = {|
+  quoteMarkdown?: boolean,
+  scopeSelector?: string
+|}
+
+type ContainerConfig = {|
+  quoteMarkdown: boolean,
+  scopeSelector: string
+|}
+
 type Subscription = {|
   unsubscribe: () => void
 |}
 
-export function subscribe(container: Element): Subscription {
-  install(container)
+export function subscribe(container: Element, options?: ConfigOptions): Subscription {
+  install(container, options)
   return {
     unsubscribe: () => {
       uninstall(container)
     }
   }
 }
 
-export function install(container: Element) {
+export function install(container: Element, options?: ConfigOptions) {
   const firstInstall = installed === 0
   installed += containers.has(container) ? 0 : 1
-  containers.set(container, 1)
+  const config: ContainerConfig = Object.assign({quoteMarkdown: false, scopeSelector: ''}, options)
+  containers.set(container, config)
   if (firstInstall) {
     document.addEventListener('keydown', quoteSelection)
   }
@@ -118,11 +129,21 @@ function extractQuote(text: string, range: Range, unwrap: boolean): ?Quote {
 
   const container = findContainer(focusNode)
   if (!container) return
+  const options = containers.get(container)
+  if (!options) return
 
-  const markdownSelector = container.getAttribute('data-quote-markdown')
-  if (markdownSelector != null && !edgeBrowser) {
+  if (options.quoteMarkdown && !edgeBrowser) {
     try {
-      selectionText = selectFragment(rangeToMarkdown(range, markdownSelector, unwrap))
+      const fragment = extractFragment(range, options.scopeSelector)
+      container.dispatchEvent(
+        new CustomEvent('quote-selection-markdown', {
+          bubbles: true,
+          cancelable: false,
+          detail: {fragment, range, unwrap}
+        })
+      )
+      insertMarkdownSyntax(fragment)
+      selectionText = selectFragment(fragment)
         .replace(/^\n+/, '')
         .replace(/\s+$/, '')
     } catch (error) {

quote-selection.js.flow

@@ -1,13 +1,18 @@
 /* @flow strict */
 
+type ConfigOptions = {|
+  quoteMarkdown?: boolean,
+  scopeSelector?: string
+|}
+
 interface Subscription {
   unsubscribe: () => void
 }
 
 declare module.exports: {
-  install(container: Element): void;
+  install(container: Element, options?: ConfigOptions): void;
   uninstall(container: Element): void;
-  subscribe(container: Element): Subscription;
+  subscribe(container: Element, options?: ConfigOptions): Subscription;
   findContainer(el: Element): ?Element;
   findTextarea(container: Element): ?HTMLTextAreaElement;
   quote(text: string, range: Range): boolean;