@thegetty/quire-cli 0.20.3 → 1.0.0-pre-release.0

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/epub/manifest.js

@@ -0,0 +1,110 @@
+const path = require('path')
+
+/**
+ * Returns publication.yaml data as JSON for the EPUB generation library
+ * 
+ * @param  {Object} publication
+ * @return {Object}
+ */
+module.exports = (eleventyConfig) => {
+  const removeHTML = eleventyConfig.getFilter('removeHTML')
+  const { assets, readingOrder } = eleventyConfig.globalData.epub
+
+  const {
+    contributor,
+    copyright,
+    description,
+    isbn,
+    language,
+    promo_image: promoImage,
+    pub_date: pubDate,
+    publishers,
+    readingLine,
+    subtitle,
+    title
+  } = eleventyConfig.globalData.publication
+  const { epub, figures: { imageDir } } = eleventyConfig.globalData.config
+  const { url } = eleventyConfig.globalData.publication
+
+  /**
+   * Contributor name, filtered by type
+   */
+  const contributors = (type) => {
+    if (!contributor) return
+    const contributors = contributor.filter((item) => item.type === type)
+
+    return contributors.map(({ first_name, full_name, last_name, role }) => {
+      const name = full_name || `${first_name} ${last_name}`
+      const item = {
+        name: name,
+        role: `${role || 'aut'}`
+      }
+
+      if (last_name && first_name) {
+        item['file-as'] = `${last_name}, ${first_name}`
+      }
+
+      return item
+    })
+  }
+
+  const cover = () => {
+    return (promoImage)
+      ? path.join(imageDir, promoImage).replace(/^\//, '')
+      : epub.defaultCover
+  }
+
+  /**
+   * Comma-separated list of publisher names and locations
+   * @return {String}
+   */
+  const publisherNameAndLocations = () => {
+    if (!publishers) return
+    return publishers.map(({ location, name }) => {
+      return location ? `${name}, ${location}` : `${name}`
+    })
+  }
+
+  /**
+   * Paths to stylesheets
+   * @todo determine path to stylesheet
+   * @returns {Array} Paths to stylesheets
+   */
+  const stylesheets = () => {
+    return [path.join('css', 'epub.css')]
+  }
+
+  /**
+   * Publication title, subtitle, and reading line
+   */
+  const pubTitle = () => {
+    if (subtitle && readingLine) {
+      return `${title}: ${subtitle} ${readingLine}`
+    } else if (subtitle) {
+      return `${title}: ${subtitle}`
+    }
+  }
+
+  return {
+    '@context': [
+      'https://schema.org',
+      'https://www.w3.org/ns/pub-context'
+    ],
+    // css: stylesheets(),
+    conformsTo: 'https://www.w3.org/TR/pub-manifest/',
+    contributors: contributors('secondary'),
+    cover: cover(),
+    creators: contributors('primary'),
+    date: pubDate,
+    description: removeHTML(description.full).replace(/\r?\n|\r/g, ' '),
+    id: isbn,
+    languages: language,
+    publisher: publisherNameAndLocations(),
+    readingOrder: readingOrder.sort(),
+    resources: assets,
+    rights: copyright,
+    title: pubTitle(),
+    type: 'Book',
+    url
+  }
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/epub/transform.js

@@ -0,0 +1,79 @@
+const filterOutputs = require('../filter.js')
+const getIIIFConfig = require('../../../figures/iiif/config')
+const jsdom = require('jsdom')
+const layout = require('./layout')
+const path = require('path')
+const writer = require('./writer')
+
+const { JSDOM } = jsdom
+
+/**
+ * Content transforms for EPUB output
+ */
+module.exports = function(eleventyConfig, collections, content) {
+  const { output: iiifOutputDir } = getIIIFConfig(eleventyConfig).dirs
+  const pageTitle = eleventyConfig.getFilter('pageTitle')
+  const slugify = eleventyConfig.getFilter('slugify')
+  const { imageDir } = eleventyConfig.globalData.config.figures
+  const { language } = eleventyConfig.globalData.publication
+  const { assets, readingOrder } = eleventyConfig.globalData.epub
+  const { outputDir } = eleventyConfig.globalData.config.epub
+
+  const write = writer(outputDir)
+
+  /**
+   * Gather asset filepaths
+   *
+   * @param      {HTMLElement}  element
+   */
+  const getAssets = (element) => {
+    const images = element.querySelectorAll('img')
+    images.forEach((img) => {
+      const src = img.getAttribute('src')
+      if (!src) return
+      const pattern = `^(${imageDir}|/${iiifOutputDir})`
+      const regex = new RegExp(pattern, 'g')
+      if (src.match(regex)) {
+        const relativePath = src.replace(/^\//, '')
+        assets.push(relativePath)
+      }
+    })
+  }
+
+  /**
+   * Remove pages excluded from this output type
+   */
+  const epubPages = collections.epub.map(({ outputPath }) => outputPath)
+  const { ext } = path.parse(this.outputPath)
+  const index = epubPages.findIndex((path) => path == this.outputPath)
+  let epubContent =  index !== -1 ? content : undefined
+
+  if (epubContent && ext === '.html') {
+    const page = collections.epub[index]
+    const { document } = new JSDOM(epubContent).window
+    const mainElement = document.querySelector('main[data-output-path]')
+    const title = pageTitle(page.data)
+    const body = document.createElement('body')
+    body.innerHTML = mainElement.innerHTML
+    body.setAttribute('id', mainElement.getAttribute('id'))
+
+    /**
+     * Remove elements excluded from this output type
+     */
+    filterOutputs(body, 'epub')
+    getAssets(body)
+
+    const name = slugify(this.url) || path.parse(this.inputPath).name
+    const targetLength = collections.epub.length.toString().length
+    const sequence = index.toString().padStart(targetLength, 0)
+    epubContent = layout({ body: body.outerHTML, language, title })
+    const filename = `${sequence}_${name}.xhtml`
+    readingOrder.push(filename)
+    write(filename, epubContent)
+  }
+
+  /**
+   * Return unmodified content
+   */
+  return content
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/epub/writer.js

@@ -0,0 +1,21 @@
+const chalkFactory = require('~lib/chalk')
+const fs = require('fs-extra')
+const path = require('path')
+
+const logger = chalkFactory('_plugins:epub:write')
+
+/**
+ * Writes EPUB files
+ * @param  {String} content Serialized DOM content
+ */
+module.exports = (outputDir) => {
+  return (outputPath, content) => {
+    const dest = path.join(outputDir, outputPath)
+    try {
+      fs.ensureDirSync(path.parse(dest).dir)
+      fs.writeFileSync(dest, content)
+    } catch (error) {
+      logger.error(`Error writing EPUB file ${dest}. ${error}`)
+    }
+  }
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/filter.js

@@ -0,0 +1,21 @@
+/**
+ * Remove elements that should not be rendered in the provided output type
+ * 
+ * @param  {Object} element HTML elmeent
+ * @param  {String} output  pdf, epub, html
+ */
+module.exports = function (element, output) {
+  for (const item of element.querySelectorAll('[data-outputs-include]')) {
+    const value = item.dataset.outputsInclude
+    if (!value.split(',').map((item) => item.trim()).includes(output)) {
+      item.remove()
+    }
+  }
+  for (const item of element.querySelectorAll('[data-outputs-exclude]')) {
+    const value = item.dataset.outputsExclude
+    if (value.split(',').map((item) => item.trim()).includes(output)) {
+      item.remove()
+    }
+  }
+  return element
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/html/transform.js

@@ -0,0 +1,33 @@
+const filterOutputs = require('../filter.js')
+const path = require('path')
+const jsdom = require('jsdom')
+const registerWebComponents = require('./web-components')
+
+const { JSDOM } = jsdom
+
+/**
+ * Content transforms for html output
+ */
+module.exports = function(eleventyConfig, collections, content) {
+  /**
+   * Remove pages excluded from this output type
+   */
+  const pages = collections.html.map(({ outputPath }) => outputPath)
+  const { ext } = path.parse(this.outputPath)
+  content = pages.includes(this.outputPath) ? content : undefined
+
+  if (ext === '.html') {
+    const dom = new JSDOM(content)
+    /**
+     * Remove elements excluded from this output type
+     */
+    filterOutputs(dom.window.document, 'html')
+    /**
+     * Add web component script tags to <head>
+     */
+    registerWebComponents(dom)
+    content = dom.serialize()
+  }
+
+  return content
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/html/web-components.js

@@ -0,0 +1,36 @@
+const fs = require('fs-extra')
+const jsdom = require('jsdom')
+const path = require('path')
+
+/**
+ * An Eleventy transform function to register web component modules in <head>
+ *
+ * @param      {String}  content
+ * @return     {String}  transformed content
+ */
+module.exports = function (dom) {
+  const webComponentPath = path.resolve('_includes', 'web-components')
+
+  const webComponentModulePaths = fs
+    .readdirSync(webComponentPath, { withFileTypes: true })
+    .reduce((modulePaths, filePath) => {
+      if (filePath.isDirectory()) modulePaths.push(
+        path.join('_assets', 'javascript', filePath.name, 'index.js'),
+      )
+
+      return modulePaths
+    }, [])
+
+  const { document } = dom.window
+  const { head } = document
+
+  // Register web components in the current file's <head>
+  webComponentModulePaths.forEach((modulePath) => {
+    const scriptTag = document.createElement('script')
+    scriptTag.setAttribute('type', 'module')
+    scriptTag.setAttribute('src', `/${modulePath}`)
+    head.appendChild(scriptTag)
+  })
+
+  return dom.serialize()
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/index.js

@@ -0,0 +1,31 @@
+const path = require('path')
+const jsdom = require('jsdom')
+const { JSDOM } = jsdom
+const epub = require('./epub')
+const html = require('./html/transform.js')
+const pdf = require('./pdf/transform.js')
+const renderOutputs = require('./render.js')
+/**
+ * Eleventy plugin to transform content for output as epub, html, pdf
+ *
+ * @param      {Object}  eleventyConfig  Eleventy configuration
+ * @param      {Object}  collections  Eleventy collections
+ */
+module.exports = function(eleventyConfig, { collections }) {
+  eleventyConfig.addJavaScriptFunction('renderOutputs', function(...args)  {
+    return renderOutputs(eleventyConfig, ...args)
+  })
+  /**
+   * Nota bene:
+   * - Call transform with `this` context to ensure we have `this.outputPath`
+   * - Order is important. The `html` transform must run last.
+   */
+  eleventyConfig.addPlugin(epub, collections)
+
+  eleventyConfig.addTransform('pdf', function (content) {
+    return pdf.call(this, eleventyConfig, collections, content)
+  })
+  eleventyConfig.addTransform('html', function (content) {
+    return html.call(this, eleventyConfig, collections, content)
+  })
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/pdf/README.md

@@ -0,0 +1,118 @@
+## Transform to combine HTML output for PDF
+
+The PDF module implements an [Eleventy `transform` function](https://www.11ty.dev/docs/config/#transforms) that prepares the static output for input to the [`Paged.js`](https://pagedjs.org) library. The HTML output from static rendering is output to a combined HTML file that is the input to the [`Paged.js`](https://pagedjs.org) commands.
+
+## Reading the HTML output files
+
+The transform function is called for each template, with the output HTML and output path as arguments, at the end of the build step before the individual page content is written to file on disk.
+
+### Selecting the content
+
+The transfrom uses the [`JSDOM` library](https://github.com/jsdom/jsdom) to create an HTML `document` from the rendered output and `querySelect` a `section` element that contains the content. The `section` containing the content is selected by the `data-ouput-path` attribute applied to the wrapping `section` element rendered by the [`base.11ty.js` layout](../_layouts/base.11ty.js).
+
+Below is simplified example of the `content` argument passed to the transform function:
+
+```HTML
+<!DOCTYPE html>
+<html>
+  <head>
+    <!-- omitted -->
+  </head>
+  <body>
+    <header>
+      <!-- omitted -->
+    </header>
+    <main>
+      <nav>
+        <!-- omitted -->
+      </nav>
+      <section data-output-path="example/page.html">
+        <p>This is the combined output of the `content` directory template file and the applied layouts.</p>
+      </section>
+    </main>
+    <footer>
+      <!-- omitted -->
+    </footer>
+  </body>
+</html>
+```
+
+## Writing the transformed output
+
+For each file output by the build process a `<section>` element is written to the combined output file. Note that "templates are rendered in the order generated by the dependency graph" (see [Eleventy Order of Operation](https://www.11ty.dev/docs/advanced-order/#order-of-operations)), which
+prevents the transform function from simply appending the HTML fragments to the combined output file. To ensure that content in the combined output file appears in the correct order the transform function must be aware of the computed page order.
+
+### Insertion algorithm
+
+A map of all `<section>` elements written to output file is maintained to allow quick lookup of parent and sibling sections.
+
+For each `<section>` content fragment to be written to the output file its location is determined by comparing the value of its `data-ouput-path` with the computed page order and the current map of `<section>` elements written.
+
+#### Computing content order
+
+After selecting the `<section>` element by its `data-ouput-path` attribute the location of that content in looked up in the computed page order and the nearest siblings and ancestors is then found in the array of `<section>` elements already written to the combined output file.
+
+#### Inserting the content
+
+The `<section>` content fragment is written to the combined output file by calling `insertBefore` or `insertAfter` on the nearest ancestor `<section>` element.
+
+
+## Exclude/include content from the publication PDF
+
+### Pages [for editors]
+
+Use the front-matter `outputs` key to define outputs, for example:
+
+```yaml
+outputs:
+  - html
+```
+
+### Components [for developers]
+
+*Not yet implemented*
+
+Possible solutions:
+
+- Add css classes for print only output. This is less ideal as the markup will be sent to Paged.js for parsing.
+
+```html
+<canvas-panel class="no-print" />
+```
+
+- Render both markup for *both* web and print, then remove any markup not for current output during Eleventy transform or from an after build hook.
+
+```html
+<canvas-panel data-outputs="html" />
+<img data-outputs="pdf, ebub" />
+```
+
+- Render the static alternative and save the output as a string. When parsing the site output for tranform lookup and replace the component markup in `pdf.html` with the static version.
+
+- Register an alternate component render function that will be called from the PDF transform; we may not have access to the component data at this point.
+
+Can an Eleventy plugin add a `registerTransform` function to Eleventy?
+
+`web-components/canvas-panel.js`
+```javascript
+eleventyConfig.registerTransform(id, transform)
+```
+
+```javascript
+{
+  'id1': (args) => { return '' }
+  'id2': '<img src="" alt="" />'
+}
+```
+
+## Open Questions
+
+- What markup is required to correctly render sections, section headings (title, subtitle, et cetera)?
+
+- What is the PDF standard for TOC markup?
+
+- Can we pass the TOC JSON to the Paged.js API?
+
+- How can we access the PDF page numbering?
+  For example, were we to render the TOC Grid how might we get the PDF page number for each section so that it can be rendered below the section image?
+

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/pdf/layout.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html>
+  <head>
+    <!--
+    <meta charset="utf-8" />
+    <meta name="description" content="${description}">
+    <meta name="keywords" content="${keywords}">
+    <title>${pageTitle}</title>
+    <link rel="canonical" href="${canonicalURL}">
+    <link rel="version-history" href="${publication.repositoryUrl}">
+    -->
+    <link rel="stylesheet" href="pdf.css" />
+  </head>
+  <body>
+  </body>
+</html>

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/pdf/transform.js

@@ -0,0 +1,104 @@
+const jsdom = require('jsdom')
+const filterOutputs = require('../filter.js')
+const truncate = require('~lib/truncate')
+const writeOutput = require('./write')
+
+const { JSDOM } = jsdom
+
+/**
+ * A function to transform and write Eleventy content for pdf
+ *
+ * @param      {Object}  collections  Eleventy collections object
+ * @param      {String}  content      Output content
+ * @return     {Array}   The transformed content string
+ */
+module.exports = function(eleventyConfig, collections, content) {
+  const pageTitle = eleventyConfig.getFilter('pageTitle')
+  const slugify = eleventyConfig.getFilter('slugify')
+
+  /**
+   * Truncated page or section title for footer
+   * @param  {Object} page
+   * @return {String} Formatted page or section title
+   */
+  const formatTitle = ({ label, short_title: shortTitle, title }) => {
+    const truncatedTitle = shortTitle || truncate(title, 35)
+    return pageTitle({ label, title: truncatedTitle })
+  }
+
+  /**
+   * Sets data attribute used for PDF footer
+   * @see `_assets/styles/print.css`
+   *
+   * @param  {Object}       page     The page being transformed
+   * @param  {HTMLElement}  element  HTML element on which to set data attributes
+   */
+  const setDataAttributes = (page, element) => {
+    const { dataset } = element
+    const { parentPage } = page.data
+
+    dataset.footerPageTitle = formatTitle(page.data)
+
+    if (parentPage) {
+      dataset.footerSectionTitle = formatTitle(parentPage.data)
+    }
+  }
+
+  /**
+   * Transform relative links to anchor links
+   *
+   * @param      {HTMLElement}  element
+   */
+  const transformRelativeLinks = (element) => {
+    const nodes = element.querySelectorAll('a')
+    nodes.forEach((a) => {
+      const url = a.getAttribute('href')
+      a.setAttribute('href', slugify(url).replace(/^([^#])/, '#$1'))
+    })
+    return element
+  }
+
+  const pdfPages = collections.pdf.map(({ outputPath }) => outputPath)
+
+  if (pdfPages.includes(this.outputPath)) {
+    const { document } = new JSDOM(content).window
+    const mainElement = document.querySelector('main[data-output-path]')
+    const pageIndex = pdfPages.findIndex((path) => path === this.outputPath)
+
+    if (mainElement) {
+      if (pageIndex !== -1) {
+        const currentPage = collections.pdf[pageIndex]
+        const sectionElement = document.createElement('section')
+
+        sectionElement.innerHTML = mainElement.innerHTML
+
+        for (const className of mainElement.classList) {
+          sectionElement.classList.add(className)
+        }
+
+        setDataAttributes(currentPage, sectionElement)
+
+        // set an id for anchor links to each section
+        sectionElement.setAttribute('id', mainElement.getAttribute('id'))
+
+        // transform relative links to anchor links
+        transformRelativeLinks(sectionElement)
+
+        // remove non-pdf content
+        filterOutputs(sectionElement, 'pdf')
+        collections.pdf[pageIndex].sectionElement = sectionElement
+      }
+
+      /**
+       * Once this transform has been called for each PDF page
+       * every item in the collection will have `sectionConent`
+       */
+      if (collections.pdf.every(({ sectionElement }) => !!sectionElement)) {
+        writeOutput(collections.pdf)
+      }
+    }
+  }
+
+  // Return unmodified `content`
+  return content
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/pdf/write.js

@@ -0,0 +1,64 @@
+const chalkFactory = require('~lib/chalk')
+const fs = require('fs-extra')
+const jsdom = require('jsdom')
+const path = require('path')
+const sass = require('sass')
+
+const { error, warn } = chalkFactory('transforms:pdf')
+
+/**
+ * Write each page section in the PDF collection to a single HTML file
+ * @param  {Object} collection collections.pdf with `sectionElement` property
+ */
+module.exports = async function(collection) {
+  const layoutPath = path.join('_plugins', 'transforms', 'outputs', 'pdf', 'layout.html')
+  /**
+   * Nota bene:
+   * Output must be written to a directory using Passthrough File Copy
+   * @see https://www.11ty.dev/docs/copy/#passthrough-file-copy
+   */
+  const outputDir = process.env.ELEVENTY_ENV === 'production' ? 'public' : '_site'
+  const outputPath = path.join(outputDir, 'pdf.html')
+
+  const { JSDOM } = jsdom
+  const dom = await JSDOM.fromFile(layoutPath)
+  const { document } = dom.window
+
+  collection.forEach(({ outputPath, sectionElement }) => {
+    try {
+      document.body.appendChild(sectionElement)
+    } catch (errorMessage) {
+      error(`Eleventy transform for PDF error appending content for ${outputPath} to combined output. ${errorMessage}`)
+    }
+  })
+
+  const trimLeadingSlash = (string) => string.startsWith('/') ? string.substr(1) : string
+
+  document.querySelectorAll('[src]').forEach((asset) => {
+    const src = asset.getAttribute('src')
+    asset.setAttribute('src', trimLeadingSlash(src))
+  })
+
+  try {
+    fs.ensureDirSync(path.parse(outputPath).dir)
+    fs.writeFileSync(outputPath, dom.serialize())
+  } catch (errorMessage) {
+    error(`Eleventy transform for PDF error writing combined HTML output for PDF. ${errorMessage}`)
+  }
+
+  const sassOptions = {
+    loadPaths: [
+      path.resolve('node_modules')
+    ]
+  }
+
+  try {
+    const application = sass.compile(path.resolve('content', '_assets', 'styles', 'application.scss'), sassOptions)
+    const print = sass.compile(path.resolve('content', '_assets', 'styles', 'print.scss'), sassOptions)
+    const custom = sass.compile(path.resolve('content', '_assets', 'styles', 'custom.css'), sassOptions)
+    fs.ensureDirSync(path.parse(outputPath).dir)
+    fs.writeFileSync(path.join(outputDir, 'pdf.css'), application.css + print.css + custom.css)
+  } catch (error) {
+    error('Eleventy transform for PDF error compiling SASS. Error message: ', error)
+  }
+}

package/src/lib/quire/versions/1.0.0-pre-release.2/_plugins/transforms/outputs/render.js

@@ -0,0 +1,35 @@
+const { html } = require('~lib/common-tags')
+const fs = require('fs-extra')
+const jsdom = require('jsdom')
+const { JSDOM } = jsdom
+const path = require('path')
+
+/**
+ * Iterate over output files `epub.js`, html.js`, `pdf.js`, and `print.js`;
+ * initialize with `eleventyConfig` and render each with the `data-outputs-include`
+ * attribute
+ */
+module.exports = function (eleventyConfig, dir, params, page) {
+  const fileNames = ['epub', 'html', 'pdf', 'print']
+
+  const filePaths = fileNames.flatMap((output) => {
+    const filePath = path.join(dir, output)
+    return (!fs.existsSync(`${filePath}.js`))
+      ? []
+      : filePath
+  })
+
+  const content = filePaths.flatMap((filePath, index) => {
+    const init = require(filePath)
+    const renderFn = init(eleventyConfig, { page })
+    const component = renderFn(params)
+    const fragment = JSDOM.fragment(component)
+    return [...fragment.children].map((child) => {
+      const fileName = path.parse(filePaths[index]).name
+      const outputs = fileName === 'print' ? 'epub,pdf' : fileName
+      child.setAttribute('data-outputs-include', outputs)
+      return child.outerHTML
+    })
+  })
+  return html`${content}`
+}