@adobe/helix-html-pipeline 1.0.0

package/src/steps/rewrite-icons.js

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* eslint-disable no-param-reassign */
+
+const REGEXP_ICON = /:(#?[a-zA-Z_-]+[a-zA-Z0-9]*):/g;
+
+/**
+ * Create a <img> or <svg> icon dom element eg:
+ * `<img class="icon icon-smile" src="/icons/smile.svg"/>` or
+ * `<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-smile"><use href="/icons.svg#smile"></use></svg>`
+ * @param {Document} document the dom document
+ * @param {string} value the identifier of the icon
+ */
+function createIcon(document, value) {
+  value = encodeURIComponent(value);
+
+  // icon starts with #
+  if (value.startsWith('%23')) {
+    value = value.substring(3);
+    const $el = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    $el.classList.add('icon', `icon-${value}`);
+    const $use = document.createElement('use');
+    $use.setAttribute('href', `/icons.svg#${value}`);
+    $el.appendChild($use);
+    return $el;
+  }
+
+  // create normal image
+  const $el = document.createElement('img');
+  $el.classList.add('icon', `icon-${value}`);
+  $el.setAttribute('src', `/icons/${value}.svg`);
+  $el.setAttribute('alt', `${value} icon`);
+  return $el;
+}
+
+/**
+ * Rewrite :icons:
+ *
+ * @param {Document} document The (vdom) document
+ */
+function rewriteIcons(document) {
+  const { NodeFilter } = document.window;
+  const nodeIterator = document.createNodeIterator(
+    document.body,
+    NodeFilter.SHOW_TEXT,
+  );
+
+  let textNode;
+  // eslint-disable-next-line no-cond-assign
+  while (textNode = nodeIterator.nextNode()) {
+    const text = textNode.data;
+    let lastIdx = 0;
+    for (const match of text.matchAll(REGEXP_ICON)) {
+      const [matched, icon] = match;
+      const before = text.substring(lastIdx, match.index);
+      if (before) {
+        textNode.parentNode.insertBefore(document.createTextNode(before), textNode);
+      }
+      textNode.parentNode.insertBefore(createIcon(document, icon), textNode);
+      lastIdx = match.index + matched.length;
+    }
+
+    if (lastIdx && lastIdx <= text.length) {
+      // there is still some text left
+      const after = text.substring(lastIdx);
+      if (after) {
+        textNode.data = after;
+      } else {
+        textNode.remove();
+      }
+    }
+  }
+}
+
+/**
+ * @type PipelineStep
+ * @param content
+ */
+export default function rewrite({ content }) {
+  if (content.document) {
+    rewriteIcons(content.document);
+  }
+}

package/src/steps/set-custom-response-headers.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { cleanupHeaderValue } from '@adobe/helix-shared-utils';
+import { filterGlobalMetadata } from './extract-metadata.js';
+
+/**
+ * Array of headers allowed in the metadata.json file.
+ */
+const allowList = [
+  'content-security-policy',
+  'content-security-policy-report-only',
+  'access-control-allow-origin',
+  'access-control-allow-methods',
+  'link',
+];
+
+/**
+ * Decorates the pipeline response object with the headers defined in metadata.json.
+ * @type PipelineStep
+ * @param {PipelineState} state
+ * @param {PipelineRequest} req
+ * @param {PipelineResponse} res
+ * @returns {Promise<void>}
+ */
+export default function setCustomResponseHeaders(state, req, res) {
+  const meta = filterGlobalMetadata(state.metadata, state.info.path);
+  Object.entries(meta).forEach(([name, value]) => {
+    if (allowList.includes(name)) {
+      res.headers.set(name, cleanupHeaderValue(value));
+    }
+  });
+}

package/src/steps/set-x-surrogate-key-header.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { computeSurrogateKey } from '@adobe/helix-shared-utils';
+
+/**
+ * @type PipelineStep
+ * @param {PipelineState} state
+ * @param {PipelineRequest} req
+ * @param {PipelineResponse} res
+ * @returns {Promise<void>}
+ */
+export default function setXSurrogateKeyHeader(state, req, res) {
+  const {
+    content, contentBusId, info, owner, repo, ref,
+  } = state;
+
+  const keys = [];
+  if (content.sourceLocation) {
+    keys.push(computeSurrogateKey(content.sourceLocation));
+  }
+  if (info.selector !== 'plain') {
+    keys.push(`${contentBusId}_metadata`);
+    keys.push(`${ref}--${repo}--${owner}_head`);
+  }
+  res.headers.set('x-surrogate-key', keys.join(' '));
+}

package/src/steps/split-sections.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2018 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { selectAll } from 'unist-util-select';
+
+// Compute the meta information for the section
+function computeMeta(section) {
+  return selectAll('yaml', section).reduce((prev, { payload }) => Object.assign(prev, payload), {});
+}
+
+/**
+ * Splits the sections in the mdast tree
+ * @type PipelineStep
+ * @param {PipelineState} state
+ */
+export default function split(state) {
+  const { content: { mdast } } = state;
+
+  // filter all children that are either yaml or break blocks
+  const dividers = mdast.children.filter((node) => node.type === 'yaml' || node.type === 'thematicBreak')
+    // then get their index in the list of children
+    .map((node) => mdast.children.indexOf(node));
+
+  // find pairwise permutations of spaces between blocks
+  // include the very start and end of the document
+  const starts = [0, ...dividers];
+  const ends = [...dividers, mdast.children.length];
+
+  // content.mdast.children = _.zip(starts, ends)
+  mdast.children = starts.map((k, i) => [k, ends[i]])
+    // but filter out empty section
+    .filter(([start, end]) => start !== end)
+    // then return all nodes that are in between
+    .map(([start, end]) => {
+      // skip 'thematicBreak' nodes
+      const index = mdast.children[start].type === 'thematicBreak' ? start + 1 : start;
+      const section = {
+        type: 'section',
+        children: mdast.children.slice(index, end),
+      };
+      section.meta = computeMeta(section);
+      return section;
+    });
+
+  // unwrap sole section directly on the root
+  if (mdast.children.length === 1 && mdast.children[0].type === 'section') {
+    mdast.children = mdast.children[0].children;
+  }
+}

package/src/steps/stringify-response.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2019 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+/**
+ * Serializes the response document to HTML
+ * @param {PipelineState} state
+ * @param {PipelineRequest} req
+ * @param {PipelineResponse} res
+ */
+export default function stringify(state, req, res) {
+  const { log } = state;
+  if (res.body) {
+    log.debug('stringify: ignoring already defined context.response.body');
+    return;
+  }
+  const doc = res.document;
+  if (!doc) {
+    throw Error('no response document');
+  }
+  if (doc.serialize) {
+    res.body = doc.serialize();
+  } else if (doc.doctype) {
+    res.body = `<!DOCTYPE ${doc.doctype.name}>${doc.documentElement.outerHTML}`;
+  } else if (doc.documentElement) {
+    res.body = doc.documentElement.outerHTML;
+  } else if (doc.innerHTML) {
+    res.body = doc.innerHTML;
+  } else {
+    throw Error(`unexpected context.response.document: ${doc}`);
+  }
+}

package/src/steps/utils.js

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { parse, resolve } from 'url';
+
+/**
+ * Returns the original host name from the request to the outer CDN.
+ * @param {object} headers The request headers
+ * @returns {string} The original host
+ */
+export function getOriginalHost(headers) {
+  const xfh = headers.get('x-forwarded-host');
+  if (xfh) {
+    return xfh.split(',')[0].trim();
+  }
+  return headers.get('host');
+}
+
+/**
+ * Turns a relative into an absolute URL.
+ * @param {object} headers The request headers
+ * @param {string} url The relative or absolute URL
+ * @returns {string} The absolute URL or <code>null</code>
+ *                   if <code>url</code> is not a string
+ */
+export function getAbsoluteUrl(headers, url) {
+  if (typeof url !== 'string') {
+    return null;
+  }
+  return resolve(`https://${getOriginalHost(headers)}/`, url);
+}
+
+/**
+ * Returns the canonical HTML url for the give one by
+ *
+ * - removing .html extension
+ * - removing index
+ *
+ * @param {string} url
+ * @return {string} canonical url
+ */
+export function makeCanonicalHtmlUrl(url) {
+  if (typeof url !== 'string') {
+    return null;
+  }
+  const queryIdx = url.indexOf('?');
+  const query = queryIdx > 0 ? url.substring(queryIdx) : '';
+  let base = queryIdx > 0 ? url.substring(0, queryIdx) : url;
+  if (base.endsWith('.html')) {
+    base = base.substring(0, base.length - 5);
+  }
+  if (base.endsWith('index')) {
+    base = base.substring(0, base.length - 5);
+  }
+  return `${base}${query}`;
+}
+
+/**
+ * Wraps the content of $node with a new $parent node and then appends the new parent to the node.
+ *
+ * @param {DOMNode} $node The content of the node to wrap
+ * @param {DOMNode} $parent The new parent node
+ */
+export function wrapContent($parent, $node) {
+  $parent.append(...$node.childNodes);
+  $node.append($parent);
+}
+
+/**
+ * Converts all non-valid-css-classname characters to `-`.
+ * @param {string} text input text
+ * @returns {string} the css class name
+ */
+export function toClassName(text) {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^0-9a-z]/gi, '-');
+}
+
+/**
+ * Adds the fastly-image-optimization url params to the given image src.
+ * @param {string} src The image source.
+ * @param {number} [width = 0] optional 'width' parameter
+ * @param {string} [format = 'webply'] image format.
+ * @param {string} [optimize = 'medium'] optimization.
+ * @returns {string}
+ */
+export function optimizeImageURL(src, width, format = 'webply', optimize = 'medium') {
+  // use deprecated api to avoid complexity with non absolute paths
+  const url = parse(src, true);
+  delete url.search;
+  if (width) {
+    url.query.width = String(width);
+  }
+  url.query.format = format;
+  url.query.optimize = optimize;
+  return url.format();
+}

package/src/utils/hast-util-to-dom.js

@@ -0,0 +1,190 @@
+/*
+ * (ISC License)
+ *
+ * Copyright (c) 2018 Keith McKnight <keith@mcknig.ht>
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any purpose
+ * with or without fee is hereby granted, provided that the above copyright notice
+ * and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+ * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+ * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+ * OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+ * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+ * THIS SOFTWARE.
+ */
+
+// This was copied from https://github.com/syntax-tree/hast-util-to-dom/blob/master/src/index.js
+// and adapted so that it can be used with JSDOM
+// TODO: contribute back to original
+
+/* eslint-disable header/header */
+import { find as infoFind, html as infoHtml } from 'property-information';
+
+const ns = {
+  html: 'http://www.w3.org/1999/xhtml',
+};
+/* istanbul ignore next */
+const wrap = (document) => {
+  // Add all children.
+  function appendAll(node, children, options) {
+    const childrenLength = children.length;
+
+    for (let i = 0; i < childrenLength; i += 1) {
+      // eslint-disable-next-line no-use-before-define
+      node.appendChild(transform(children[i], options));
+    }
+
+    return node;
+  }
+
+  // Create a document.
+  function root(node, options) {
+    const { fragment, namespace: optionsNamespace } = options;
+    const { children = [] } = node;
+    const { length: childrenLength } = children;
+
+    let namespace = optionsNamespace;
+    let rootIsDocument = childrenLength === 0;
+
+    for (let i = 0; i < childrenLength; i += 1) {
+      const { tagName, properties = {} } = children[i];
+
+      /* c8 ignore start */
+      if (tagName === 'html') {
+        // If we have a root HTML node, we don’t need to render as a fragment.
+        rootIsDocument = true;
+
+        // Take namespace of the first child.
+        if (typeof optionsNamespace === 'undefined') {
+          namespace = properties.xmlns || ns.html;
+        }
+      }
+      /* c8 ignore end */
+    }
+
+    // The root node will be a Document, DocumentFragment, or HTMLElement.
+    let el;
+
+    if (rootIsDocument) {
+      el = document.implementation.createDocument(namespace, '', null);
+    } else if (fragment) {
+      el = document.createDocumentFragment();
+    } else {
+      /* c8 ignore next */
+      el = document.createElement('html');
+    }
+
+    return appendAll(el, children, { fragment, namespace, ...options });
+  }
+
+  // Create a `doctype`.
+  function doctype(node) {
+    return document.implementation.createDocumentType(
+      node.name || 'html',
+      node.public || '',
+      node.system || '',
+    );
+  }
+
+  // Create a `text`.
+  function text(node) {
+    return document.createTextNode(node.value);
+  }
+
+  // Create a `comment`.
+  function comment(node) {
+    return document.createComment(node.value);
+  }
+
+  // Create an `element`.
+  function element(node, options) {
+    const { namespace } = options;
+    // TODO: use `g` in SVG space.
+    const { tagName = 'div', properties = {}, children = [] } = node;
+    const el = typeof namespace !== 'undefined'
+      ? document.createElementNS(namespace, tagName)
+      : document.createElement(tagName);
+
+    // Add HTML attributes.
+    const props = Object.keys(properties);
+    const { length } = props;
+
+    for (let i = 0; i < length; i += 1) {
+      const key = props[i];
+
+      const {
+        attribute,
+        property,
+        // `mustUseAttribute`,
+        mustUseProperty,
+        boolean,
+        booleanish,
+        overloadedBoolean,
+        // `number`,
+        // `defined`,
+        commaSeparated,
+        // `spaceSeparated`,
+        // `commaOrSpaceSeparated`,
+      } = infoFind(infoHtml, key);
+
+      let value = properties[key];
+
+      if (Array.isArray(value)) {
+        value = value.join(commaSeparated ? ', ' : ' ');
+      }
+
+      if (mustUseProperty) {
+        el[property] = value;
+      }
+
+      if (boolean || (overloadedBoolean && typeof value === 'boolean')) {
+        if (value) {
+          el.setAttribute(attribute, '');
+        } else {
+          el.removeAttribute(attribute);
+        }
+      } else if (booleanish) {
+        el.setAttribute(attribute, value);
+      } else if (value === true) {
+        el.setAttribute(attribute, '');
+      } else if (value || value === 0 || value === '') {
+        el.setAttribute(attribute, value);
+      }
+    }
+
+    return appendAll(el, children, options);
+  }
+
+  // the raw node is stored in the value directly
+  function raw(node) {
+    return node.frag;
+  }
+
+  function transform(node, options) {
+    switch (node.type) {
+      case 'root':
+        return root(node, options);
+      case 'text':
+        return text(node);
+      case 'element':
+        return element(node, options);
+      case 'doctype':
+        return doctype(node);
+      case 'comment':
+        return comment(node);
+      case 'raw':
+        return raw(node);
+      default:
+        return element(node, options);
+    }
+  }
+
+  return transform;
+};
+
+export default function toDOM(document, hast, options = {}) {
+  return wrap(document)(hast, options);
+}

package/src/utils/heading-handler.js

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2019 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { heading as fallback } from 'mdast-util-to-hast/lib/handlers/heading.js';
+import { toString } from 'mdast-util-to-string';
+import strip from 'strip-markdown';
+
+/**
+ * Utility class injects heading identifiers during the MDAST to VDOM transformation.
+ */
+export default class HeadingHandler {
+  /**
+   * Initializes the handler
+   */
+  constructor(slugger) {
+    this.slugger = slugger;
+  }
+
+  /**
+   * Returns the handler function
+   */
+  handler() {
+    return (h, node) => {
+      // Prepare the heading id
+      const headingIdentifier = this.slugger.slug(toString(strip()(node)));
+
+      // Inject the id after transformation
+      const n = { ...node };
+      const el = fallback(h, n);
+      el.properties.id = el.properties.id || headingIdentifier;
+      return el;
+    };
+  }
+}

package/src/utils/icon-handler.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2019 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Handles `icon` MDAST nodes by converting them into `img` or `<svg>` tags, e.g.
+ * `<img class="icon icon-smile" src="/icons/smile.svg"/>` or
+ * `<svg xmlns="http://www.w3.org/2000/svg" class="icon icon-smile"><use href="/icons.svg#smile"></use></svg>`
+ * @param {string} id the identifier of the icon
+ */
+export default function icon() {
+  return function handler(h, node) {
+    let { value } = node;
+    value = encodeURIComponent(value);
+    if (value.startsWith('%23')) {
+      // icon starts with #
+      value = value.substring(3);
+      return [h(node, 'svg', {
+        xmlns: 'http://www.w3.org/2000/svg',
+        className: `icon icon-${value}`,
+      }, [h(node, 'use', {
+        href: `/icons.svg#${value}`,
+      })])];
+    } else {
+      return [h(node, 'img', {
+        className: `icon icon-${value}`,
+        src: `/icons/${value}.svg`,
+        alt: `${value} icon`,
+      })];
+    }
+  };
+}