@feelpp/antora-extensions 1.0.0-rc.1 → 1.0.0-rc.2

package/data/css/listing.css

@@ -0,0 +1,79 @@
+.listing .listing-container {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-start;
+  margin-top: 5em;
+  margin-bottom: 5em;
+  gap: clamp(1.5em, 2vw, 5em);
+}
+
+.listing .listing-container .listing-card-container {
+  display: flex;
+  flex: 1 calc(33.33% - 5em);
+  max-width: 500px;
+}
+
+/* Media query for small screens */
+@media (max-width: 767px) {
+  .listing .listing-container .listing-card-container {
+    flex: 1 250px;
+  }
+}
+
+/* Media query for large screens */
+@media (min-width: 768px) {
+  .listing .listing-container .listing-card-container {
+    min-width: 250px;
+  }
+}
+
+.listing .listing-card:hover,
+.listing .listing-card:focus {
+  box-shadow: 0 6px 12px 1px #104d92ad;
+  text-decoration: none;
+}
+
+.listing .listing-card {
+  box-shadow: 0 3px 6px 1px #e0e0e0;
+  padding: 1.5em 1em 1em;
+  display: flex;
+  flex-direction: column;
+  color: initial;
+  border-radius: 0.5em;
+  flex: 1;
+}
+
+.listing .listing-card-illustration {
+  height: 150px;
+  object-fit: contain;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding-left: 1em;
+  padding-right: 1em;
+}
+
+.listing .listing-card-illustration > img {
+  max-width: 100%;
+  height: 100%;
+  object-fit: cover;
+  border-radius: 0.25em;
+}
+
+.listing .listing-card .listing-card-body {
+  border-top: 1px solid #e1e1e1;
+  margin-top: 1rem;
+  padding-bottom: 0.75rem;
+  margin-left: 0.75rem;
+  margin-right: 0.75rem;
+}
+
+.listing .listing-card .listing-card-body p {
+  font-size: 0.9em;
+  color: #56595c;
+}
+
+.listing .listing-card .listing-card-body h4 {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}

package/data/helpers/image-spec.js

@@ -0,0 +1,17 @@
+'use strict'
+
+/**
+ * Adds image$ family if missing
+ * @param {string} spec
+ * @returns {string}
+ */
+module.exports = (spec) => {
+  if (!spec || spec.includes('image$') || spec.startsWith('http://') || spec.startsWith('https://')) {
+    return spec
+  }
+  const lastColon = spec.lastIndexOf(':')
+  if (lastColon > 0 && lastColon < spec.length - 1) {
+    return spec.slice(0, lastColon + 1) + 'image$' + spec.slice(lastColon + 1)
+  }
+  return 'image$' + spec
+}

package/data/helpers/listing-get-sections.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const listingConfig = ${listingConfig}
+
+module.exports = (configName, page, {data: {root}}) => {
+  const {contentCatalog} = root
+  if (configName in listingConfig) {
+    const config = listingConfig[configName]
+    if (config) {
+      return config.map((section) => {
+        const selector = {
+          tag: section.tag,
+          withinParentModule: section.withinParentModule
+        }
+        const pages = getPages(contentCatalog, page, selector)
+        return {
+          title: section.sectionTitle,
+          pages,
+        }
+      })
+    }
+  }
+  return []
+}
+
+const getPages = function (contentCatalog, page, {tag, withinParentModule}) {
+  const pages = contentCatalog.getPages(({asciidoc, out, src}) => {
+    if (!out || !asciidoc) return
+    if (src.component !== page.componentVersion.name ||
+      (withinParentModule && src.module !== page.module) ||
+      src.version !== page.componentVersion.version) return
+    const pageTags = asciidoc.attributes['page-tags']
+    return pageTags && pageTags.split(',').map((v) => v.trim()).includes(tag)
+  }).sort((a, b) => (a.title || '').localeCompare((b.title || '')))
+  if (pages && pages.length > 0) {
+    while (pages.length % 3 !== 0) {
+      pages.push({
+        empty: true,
+      })
+    }
+  }
+  return pages
+}

package/data/helpers/resolve-resource-url.js

@@ -0,0 +1,13 @@
+'use strict'
+
+module.exports = (spec, { data, hash: context }) => {
+  if (!spec) return
+  const { contentCatalog, page } = data.root
+  if (page.component) {
+    context = Object.assign({ component: page.component.name, version: page.version, module: page.module }, context)
+  }
+  const file = contentCatalog.resolveResource(spec, context, 'page', ['page', 'attachment', 'image'])
+  if (file) {
+    return file.pub.url
+  }
+}

package/data/partials/listing-card.hbs

@@ -0,0 +1,13 @@
+{{#if empty}}
+  <div class="empty"></div>
+{{else}}
+  <a class="listing-card" href="{{{relativize pub.url}}}">
+    <div class="listing-card-illustration">
+      <img alt="" src="{{relativize (resolve-resource-url (image-spec asciidoc.attributes.page-illustration))}}"/>
+    </div>
+    <div class="listing-card-body">
+      <h4>{{title}}</h4>
+      <p class="listing-card-description">{{{asciidoc.attributes.description}}}</p>
+    </div>
+  </a>
+{{/if}}

package/data/partials/listing.hbs

@@ -0,0 +1,16 @@
+<div class="listing">
+  {{#with (listing-get-sections configName @root.page)}}
+    {{#if this.length}}
+      {{#each this}}
+        {{#if this.pages.length}}
+          <h2>{{{this.title}}}</h2>
+          <div class="listing-container">
+            {{#each this.pages}}
+              <div class="listing-card-container">{{> listing-card this}}</div>
+            {{/each}}
+          </div>
+        {{/if}}
+      {{/each}}
+    {{/if}}
+  {{/with}}
+</div>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@feelpp/antora-extensions",
   "private": false,
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.2",
   "description": "Antora Extensions by Feel++.",
   "main": "src/index.js",
   "repository": {

package/src/index.js

@@ -1,5 +1,7 @@
-const { register: registerTooboxNavigation } = require('./toolbox-navigation.js')
+const {register: registerTooboxNavigation} = require('./toolbox-navigation.js')
+const {register: registerListing} = require('./listing.js')
 
-module.exports.register = (context) => {
-  registerTooboxNavigation(context)
+module.exports.register = (thisContext, args) => {
+  registerTooboxNavigation.call(thisContext, args)
+  registerListing.call(thisContext, args)
 }

package/src/lazy-readable.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { PassThrough } = require('stream')
+
+// adapted from https://github.com/jpommerening/node-lazystream/blob/master/lib/lazystream.js | license: MIT
+class LazyReadable extends PassThrough {
+  constructor (fn, options) {
+    super(options)
+    this._read = function () {
+      delete this._read // restores original method
+      fn.call(this, options).on('error', this.emit.bind(this, 'error')).pipe(this)
+      return this._read.apply(this, arguments)
+    }
+    this.emit('readable')
+  }
+}
+
+module.exports = LazyReadable
+

package/src/listing.js

@@ -0,0 +1,108 @@
+'use strict'
+
+// The name of the package in order to give the Antora logger a useful name
+const fs = require('fs')
+const ospath = require('path')
+const { promises: fsp } = fs
+const LazyReadable = require('./lazy-readable')
+const template = require('./template')
+
+/**
+ * @module listing-extension
+ */
+function register ({ config: { listing, ...unknownOptions } }) {
+  const packageName = "@feelpp/antora-listing-extension"
+  const logger = this.getLogger(packageName)
+
+  if (Object.keys(unknownOptions).length) {
+    const keys = Object.keys(unknownOptions)
+    throw new Error(`Unrecognized option${keys.length > 1 ? 's' : ''} specified for ${packageName}: ${keys.join(', ')}`)
+  }
+
+  this.on('uiLoaded', async ({playbook, uiCatalog}) => {
+    playbook.env.SITE_LISTING_EXTENSION_ENABLED = 'true'
+    const uiOutputDir = playbook.ui.outputDir
+    assetFile(uiCatalog, logger, uiOutputDir, 'css', 'listing.css')
+    const helperPath = 'helpers/listing-get-sections.js'
+    if (uiCatalog.findByType('helper').some(({ path }) => path === helperPath)) {
+      // ignore
+    } else {
+      const helperFilePath = ospath.join(__dirname, '../data', helperPath)
+      uiCatalog.addFile({
+        contents: Buffer.from(template(await fsp.readFile(helperFilePath, 'utf8'), {listingConfig: JSON.stringify(listing)})),
+        path: helperPath,
+        stem: ospath.parse(helperPath).name,
+        type: 'helper',
+      })
+    }
+    await helperFile(uiCatalog, 'helpers/image-spec.js')
+    await helperFile(uiCatalog, 'helpers/resolve-resource-url.js')
+    await partialFile(uiCatalog, 'partials/listing.hbs')
+    await partialFile(uiCatalog, 'partials/listing-card.hbs')
+  })
+
+  this.on('beforePublish', ({ playbook }) => {
+    delete playbook.env.SITE_LISTING_EXTENSION_ENABLED
+  })
+
+
+  async function partialFile(uiCatalog, partialPath) {
+    if (uiCatalog.findByType('partial').some(({ path }) => path === partialPath)) {
+      // ignore
+    } else {
+      const partialFilePath = ospath.join(__dirname, '../data', partialPath)
+      uiCatalog.addFile({
+        contents: Buffer.from(await fsp.readFile(partialFilePath, 'utf8')),
+        path: partialPath,
+        stem: ospath.parse(partialPath).name,
+        type: 'partial',
+      })
+    }
+  }
+
+  async function helperFile(uiCatalog, helperPath) {
+    if (uiCatalog.findByType('helper').some(({ path }) => path === helperPath)) {
+      // ignore
+    } else {
+      const helperFilePath = ospath.join(__dirname, '../data', helperPath)
+      uiCatalog.addFile({
+        contents: Buffer.from(await fsp.readFile(helperFilePath, 'utf8')),
+        path: helperPath,
+        stem: ospath.parse(helperPath).name,
+        type: 'helper',
+      })
+    }
+  }
+
+  function assetFile (
+    uiCatalog,
+    logger,
+    uiOutputDir,
+    assetDir,
+    basename,
+    assetPath = assetDir + '/' + basename,
+    contents = new LazyReadable(() => fs.createReadStream(ospath.join(__dirname, '../data', assetPath))),
+    overwrite = false
+  ) {
+    const outputDir = uiOutputDir + '/' + assetDir
+    const existingFile = uiCatalog.findByType('asset').some(({path}) => path === assetPath)
+    if (existingFile) {
+      if (overwrite) {
+        logger.warn(`Please remove the following file from your UI since it is managed by ${packageName}: ${assetPath}`)
+        existingFile.contents = contents
+        delete existingFile.stat
+      } else {
+        logger.info(`The following file already exists in your UI: ${assetPath}, skipping`)
+      }
+    } else {
+      uiCatalog.addFile({
+        contents,
+        type: 'asset',
+        path: assetPath,
+        out: {dirname: outputDir, path: outputDir + '/' + basename, basename},
+      })
+    }
+  }
+}
+
+module.exports.register = register

package/src/template.js

@@ -0,0 +1,3 @@
+'use strict'
+
+module.exports = (string, vars) => string.replace(/\${(.+?)}/g, (_, name) => vars[name])

package/src/toolbox-navigation.js

@@ -16,9 +16,9 @@ function getToolboxPageModules(contentCatalog, version, tag) {
   }, {})
 }
 
-module.exports.register = (context) => {
-  const logger = context.getLogger('toolbox-navigation')
-  context.on('navigationBuilt', ({contentCatalog, navigationCatalog}) => {
+function register() {
+  const logger = this.getLogger('toolbox-navigation')
+  this.on('navigationBuilt', ({contentCatalog, navigationCatalog}) => {
     const toolboxComponent = contentCatalog.getComponent('toolboxes')
     if (toolboxComponent) {
       const componentVersions = toolboxComponent.versions
@@ -91,3 +91,5 @@ module.exports.register = (context) => {
     }
   })
 }
+
+module.exports.register = register