fix(Cite extension): Restructure and reorder reference properties

src/extensions/cite/index.test.ts

@@ -0,0 +1,47 @@
+import { whenReady, select, tag, attr } from '../../util'
+
+test('DOM manipulations', async () => {
+  const body = document.body
+  body.innerHTML = `
+<section data-itemprop="references">
+  <ol>
+    <li itemscope="" itemtype="http://schema.org/Article" id="bib1" itemprop="citation">
+      <div itemscope="" itemtype="http://schema.org/Organization" itemprop="publisher">
+        <meta itemprop="name" content="Unknown">
+        <div itemscope="" itemtype="http://schema.org/ImageObject" itemprop="logo">
+          <meta itemprop="url" content="https://via.placeholder.com/" src="https://via.placeholder.com/">
+        </div>
+      </div><span itemprop="headline">The continuing case for the Renshaw cell</span>
+      <meta itemprop="image" content="https://via.placeholder.com/">
+      <ol data-itemprop="authors">
+        <li itemscope="" itemtype="http://schema.org/Person" itemprop="author"><span itemprop="name" content="FJ Alvarez"><span itemprop="givenName">FJ</span><span itemprop="familyName">Alvarez</span></span></li>
+        <li itemscope="" itemtype="http://schema.org/Person" itemprop="author"><span itemprop="name" content="REW Fyffe"><span itemprop="givenName">REW</span><span itemprop="familyName">Fyffe</span></span></li>
+      </ol><span>
+        <meta itemprop="datePublished" content="2007"><time datetime="2007" itemscope="" itemtype="http://schema.org/Date">2007</time></span>
+    </li>
+  </ol>
+</section>
+  `
+
+  await import('.')
+  whenReady()
+
+  expect(select('ol:--authors').length).toBe(0)
+  expect(select('span:--authors').length).toBe(1)
+
+  expect(select('li:--author').length).toBe(0)
+  expect(select('span:--author').length).toBe(2)
+
+  expect(
+    select(':--reference > *').map(elem => [
+      tag(elem).toLowerCase(),
+      attr(elem, 'itemprop') ?? attr(elem, 'data-itemprop')
+    ])
+  ).toEqual([
+    ['span', 'authors'],
+    ['time', 'datePublished'],
+    ['span', 'headline'],
+    ['span', 'publisher'],
+    ['meta', 'image']
+  ])
+})

src/extensions/cite/index.ts

@@ -1,7 +1,58 @@
-import { ready, create, replace, select, attr } from '../../util'
+import { ready, create, replace, select, attr, first, tag, attrs } from '../../util'
+
+// Import the `person` extension for improved structure of a Person's name
+import '../person'
 
 /**
- * Currently, Encoda encodes a `CreativeWork.datePublished` as
+ * This is a temporary patch for https://github.com/stencila/encoda/issues/455
+ *
+ * Currently, Encoda encodes each `reference` in the `references` property of
+ * an article as.
+ *
+ * ```html
+ * <li itemscope="" itemtype="http://schema.org/Article" id="bib42" itemprop="citation">
+ *   <div itemscope="" itemtype="http://schema.org/Organization" itemprop="publisher">
+ *   ...
+ *   </div>
+ *   <span data-itemprop="headline">
+ *     <meta itemprop="headline" content="A comparative review of short and long neuropeptide F signaling in invertebrates: any similarities to vertebr…">
+ *     A comparative review of short and long neuropeptide F signaling in invertebrates: any
+ *     similarities to vertebrate neuropeptide Y signaling?
+ *   </span>
+ *   <meta itemprop="image" content="https://via.placeholder.com/...">
+ *   <ol data-itemprop="authors">
+ *     <li itemscope="" itemtype="http://schema.org/Person" itemprop="author">...</li>
+ *     <li itemscope="" itemtype="http://schema.org/Person" itemprop="author">...</li>
+ *   </ol>
+ *   <span>
+ *     <meta itemprop="datePublished" content="2011">
+ *     <time datetime="2011" itemscope="" itemtype="http://schema.org/Date">2011</time>
+ *   </span>
+ * </li>
+ * ```
+ *
+ * We want to be able to display them using citation styles like APA:
+ *
+ * ```text
+ * Nässel, D. R., & Wegener, C. (2011). A comparative review of short and long
+ * neuropeptide F signaling in invertebrates: any similarities to vertebrate
+ * neuropeptide Y signaling?. Peptides, 32(6), 1335-1355.
+ * ```
+ *
+ * It would be less work for CSS developers if these properties were in the order most commonly
+ * used in citation styles:
+ *
+ * - authors (as nested spans, rather than an ol)
+ * - datePublished
+ * - title (aka headline)
+ * - isPartOf
+ * - publisher
+ * - image
+ *
+ * Note that `publisher` and `image` are always encoded to HTML, even if missing, for conformance with GSDTT,
+ * and that some properties are missing in HTML, e.g. `isPartOf` (which provides the `Peptides, 32(6), 1335-1355` bit).
+ *
+ * Also, currently, `datePublished` is encoded as
  *
  * ```html
  * <span>
@@ -10,23 +61,46 @@ import { ready, create, replace, select, attr } from '../../util'
  * </span>
  * ```
  *
- * So that we can style the date, a better encoding would simply be:
+ * A better encoding for styling, and concision, is:
  *
  * ```html
- * <time datetime="2019-08-23" itemscope="" itemtype="http://schema.org/Date" itemprop="datePublished" >2019-08-23</time>
+ * <time datetime="2019-08-23" itemprop="datePublished" >2019-08-23</time>
  * ```
  *
  * Noting that for `<time>` elements the `datetime` attribute is used as the property value:
- * https://www.w3.org/TR/microdata/#values
+ * https://www.w3.org/TR/microdata/#values and it should not have `itemscope` and `itemtype`
+ * attributes.
  */
 ready(() =>
-  select('span > :--datePublished').forEach(meta => {
-    const date = attr(meta, 'content') as string
+  select(':--references :--reference').forEach(reference => {
+    // Change `authors` property from list to nested spans
+    select(reference, 'ol:--authors').forEach(elem => {
+      select(reference, 'li:--author').forEach(elem => tag(elem, 'span'))
+      return tag(elem, 'span')
+    })
+
+    // If `datePublished` is inside a span then un-wrap it
+    select(reference, 'span > :--datePublished').forEach(elem => {
+      const date = attr(elem, 'content') as string
+      replace(
+        elem.parentElement as Element,
+        create(`time [datetime=${date}] :--datePublished`, date)
+      )
+    })
+
+    // If `publisher` is a div make it a span
+    select(reference, 'div:--publisher').forEach(elem => tag(elem, 'span'))
+
     replace(
-      meta.parentElement as Element,
+      reference,
       create(
-        `time [datetime=${date}] [itemscope] :--Date :--datePublished`,
-        date
+        tag(reference),
+        attrs(reference),
+        first(':--authors'),
+        first(':--datePublished'),
+        first(':--title'),
+        first(':--publisher'),
+        first(':--image')
       )
     )
   })