@adobe/helix-md2jcr 1.0.0

package/src/cli/convert2jcr.js

@@ -0,0 +1,128 @@
+/*
+ * 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-await-in-loop,no-console */
+import {
+  readdir, readFile, stat, writeFile,
+} from 'fs/promises';
+import path from 'path';
+import { decode } from 'entities';
+import { md2jcr } from '../index.js';
+
+/**
+ * Read a JSON file. If the file does not exist, return an empty object.
+ * @param {string} filePath The path to the JSON file.
+ * @returns {Promise<{}|any>} A promise that resolves to the JSON object in the file,
+ */
+async function readJsonFile(filePath) {
+  try {
+    if ((await stat(filePath)).isFile()) {
+      const models = await readFile(filePath, 'utf-8');
+      return JSON.parse(models);
+    }
+  } catch (error) {
+    // ignore the fact that the file doesn't exist
+    // console.error(`Error due to: ${error} for file ${filePath}`);
+  }
+  return {};
+}
+
+/**
+ * Convert a markdown file to JCR XML.
+ * @param mdFile {string} The path to the markdown file.
+ * @param decodeXML - if true a file with the decoded XML will be created.
+ * @returns {Promise<void>} A promise that resolves when the conversion is
+ * complete, or rejects if the file is not a markdown file.
+ */
+async function convert(mdFile, decodeXML = false) {
+  if (!mdFile.endsWith('.md')) {
+    return Promise.reject(new Error('File must be a markdown file'));
+  }
+
+  const dir = path.dirname(mdFile);
+  const base = path.basename(mdFile, '.md');
+  const fileJcrXML = path.resolve(dir, `${base}.xml`);
+  const decodedXML = path.resolve(dir, `${base}-decoded.xml`);
+
+  let modelJson;
+  let definitionJson;
+  let filtersJson;
+
+  const blockDefinitionsPath = path.resolve(dir, `_${base}.json`);
+
+  // check to see if the blockFiles exists
+  try {
+    await stat(blockDefinitionsPath);
+    const blockDefinitionFile = await readJsonFile(path.resolve(dir, `_${base}.json`));
+    modelJson = blockDefinitionFile.models;
+    definitionJson = {
+      groups: [
+        {
+          title: 'Blocks',
+          id: 'blocks',
+          components: [
+            ...blockDefinitionFile.definitions,
+          ],
+        },
+      ],
+    };
+    filtersJson = blockDefinitionFile.filters;
+  } catch (err) {
+    const modelFile = path.resolve(dir, `${base}-models.json`);
+    const definitionFile = path.resolve(dir, `${base}-definitions.json`);
+    const filtersFile = path.resolve(dir, `${base}-filters.json`);
+    modelJson = await readJsonFile(modelFile);
+    definitionJson = await readJsonFile(definitionFile);
+    filtersJson = await readJsonFile(filtersFile);
+  }
+
+  const md = await readFile(mdFile, 'utf-8');
+
+  /** @type {Mdast2JCROptions} */
+  const opts = {
+    models: modelJson,
+    definition: definitionJson,
+    filters: filtersJson,
+  };
+
+  const xml = await md2jcr(md, opts);
+
+  if (decodeXML) {
+    writeFile(decodedXML, decode(xml));
+  }
+
+  return writeFile(fileJcrXML, xml);
+}
+
+/**
+ * Entry point to convert a markdown file to JCR XML.
+ * @param inPath {string} The path to the markdown file or directory containing
+ * markdown files.
+ * @returns {Promise<void>} A promise that resolves when the conversion is
+ * complete.
+ */
+async function run(inPath) {
+  const dirOrFilePath = path.resolve(process.cwd(), inPath);
+
+  const files = [];
+  if ((await stat(dirOrFilePath)).isDirectory()) {
+    files.push(...await readdir(dirOrFilePath));
+  } else {
+    files.push(dirOrFilePath);
+  }
+
+  for (const file of files) {
+    await convert(file, process.argv.includes('-d'));
+  }
+}
+
+run(process.argv[2] || process.cwd()).catch(console.error);

package/src/index.d.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2024 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 mdast2jcr from './mdast2jcr/index.js';
+import md2jcr from './md2jcr/index.js';
+
+export { mdast2jcr, md2jcr };

package/src/index.js

@@ -0,0 +1,15 @@
+/*
+ * 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 mdast2jcr from './mdast2jcr/index.js';
+import md2jcr from './md2jcr/index.js';
+
+export { mdast2jcr, md2jcr };

package/src/md2jcr/index.d.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2024 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 { Mdast2JCROptions } from '../mdast2jcr'
+
+/**
+ * Convert a Markdown document to a JCR XML document.
+ * @param {string} md The Markdown document
+ * @param {Mdast2JCROptions} options options
+ * @returns {Promise<Buffer>} the converted JCR XML document
+ */
+export default function md2jcr(md:string, options?: Mdast2JCROptions): Promise<Buffer>;

package/src/md2jcr/index.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2024 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 { unified } from 'unified';
+import remark from 'remark-parse';
+import gfm from 'remark-gfm';
+import { dereference } from '@adobe/helix-markdown-support';
+import { remarkMatter } from '@adobe/helix-markdown-support/matter';
+import remarkGridTable from '@adobe/remark-gridtables';
+import mdast2jcr from '../mdast2jcr/index.js';
+
+/**
+ * Convert markdown to JCR XML.
+ * @param md {string} The markdown content.
+ * @param opts {Mdast2JCROptions} Options.
+ * @return {Promise<String>} The JCR XML.
+ */
+export default async function md2jcr(md, opts) {
+  const mdast = unified()
+    .use(remark, { position: false })
+    .use(gfm)
+    .use(remarkMatter)
+    .use(remarkGridTable)
+    .parse(md);
+
+  dereference(mdast);
+  return mdast2jcr(mdast, opts);
+}

package/src/mdast2jcr/domain/Component.js

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2024 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.
+ */
+
+/**
+ * The Component class represents a single component located in the
+ * component-definitions.json file.
+ */
+class Component {
+  /**
+   * Create a new Component.
+   * @param {string} name
+   * @param {string} id
+   * @param {object} template
+   */
+  constructor(name, id, template) {
+    this._template = template;
+    this._filterId = template?.filter;
+    this._modelId = template?.model;
+    this._keyValue = template?.['key-value'];
+    this._name = name;
+    this._id = id;
+  }
+
+  get id() {
+    return this._id;
+  }
+
+  get filterId() {
+    return this._filterId;
+  }
+
+  get modelId() {
+    return this._modelId;
+  }
+
+  get keyValue() {
+    return this._keyValue;
+  }
+
+  get name() {
+    return this._name;
+  }
+
+  /* eslint-disable no-unused-vars */
+  get defaultFields() {
+    // remove the fields that are listed below, but keep the rest as default fields
+    // to be added to the block
+    const {
+      'key-value': keyValue,
+      ...rest
+    } = this._template;
+
+    return rest;
+  }
+}
+
+export default Component;

package/src/mdast2jcr/domain/Definitions.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2024 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.
+ */
+
+/**
+ * @typedef {import('../mdast2jcr/index.d.ts').ComponentDef} ComponentDef
+ */
+
+import Component from './Component.js';
+
+/**
+ * Get the components from the definitions object, (component-definitions.json).
+ * @param {DefinitionDef} definitions The Definitions object.
+ * @returns {Component[]} An array of Component objects.
+ */
+function getAllComponents(definitions) {
+  return definitions.groups.map((group) => group.components)
+    .flat()
+    .map((/** @type {ComponentDef} */ component) => new Component(
+      component.title,
+      component.id,
+      component.plugins?.xwalk?.page?.template,
+    ));
+}
+
+/**
+ * Get a component by locating it against the template name.
+ * @param {DefinitionDef} definitions The Definitions object.
+ * @param {string} title The title of the component.
+ * @returns {Component} The component.
+ */
+function getComponentByTitle(definitions, title) {
+  return getAllComponents(definitions).find(
+    (component) => component.name === title,
+  );
+}
+
+/**
+ * Get a component by its id.
+ * @param {DefinitionDef} definitions The Definitions object.
+ * @param {string} id The id of the component.
+ * @return {Component}
+ */
+function getComponentById(definitions, id) {
+  return getAllComponents(definitions).find(
+    (component) => component.id === id,
+  );
+}
+
+/**
+ * Get the model id given a component name, or null if not found.
+ * @param {DefinitionDef} definitions The Definitions object.
+ * @param {string} title of the component.
+ * @returns {string | null} The model id associated with the component or null
+ * if not found.
+ */
+function getModelId(definitions, title) {
+  const component = getComponentByTitle(definitions, title);
+  if (component) {
+    return component.modelId || null;
+  }
+  return null;
+}
+
+export {
+  getAllComponents,
+  getComponentByTitle,
+  getModelId,
+  getComponentById,
+};

package/src/mdast2jcr/domain/FieldGroup.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2024 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.
+ */
+class FieldGroup {
+  /**
+   * Constructor.
+   * @param {Model} model the model to use for the field group.
+   */
+  constructor(model) {
+    this.model = model;
+
+    // protect against missing fields
+    if (!this.model.fields) {
+      this.model.fields = [];
+    }
+
+    this.fields = [];
+    this._groupFields();
+  }
+
+  /**
+   * Group the fields in the model by their group name.
+   * @return {*[]}
+   */
+  _groupFields() {
+    const suffixes = ['Alt', 'MimeType', 'Type', 'Text', 'Title'];
+
+    this.model.fields
+      .filter((field) => field.name !== 'classes')
+      .forEach((field) => {
+        if (field.name.includes('_')) {
+          const groupName = field.name.split('_')[0];
+          const groupObj = this.fields.find((item) => item.name === groupName) || {
+            name: groupName,
+            fields: [],
+          };
+
+          if (!this.fields.includes(groupObj)) {
+            this.fields.push(groupObj);
+          }
+
+          const suffix = suffixes.find((s) => field.name.endsWith(s));
+          const collapsedName = field.name.substring(0, field.name.lastIndexOf(suffix));
+          const collapsedField = groupObj.fields.find((item) => item.name === collapsedName);
+
+          if (collapsedField) {
+            collapsedField.collapsed = collapsedField.collapsed || [];
+            collapsedField.collapsed.push(field);
+          } else {
+            groupObj.fields.push(field);
+          }
+        } else {
+          const suffix = suffixes.find((s) => field.name.endsWith(s));
+          const groupName = field.name.substring(0, field.name.indexOf(suffix));
+          let groupObj = this.fields.find((item) => item.name === groupName);
+
+          if (!groupObj) {
+            groupObj = {
+              name: field.name,
+              fields: [field],
+            };
+            this.fields.push(groupObj);
+          } else {
+            // find the field in the group that has a name that starts with the field.name
+            const collapsedField = groupObj.fields.find((item) => field.name.startsWith(item.name));
+            if (!collapsedField) {
+              throw new Error(`Unable to find the collapsed field for field: ${field.name}`);
+            }
+            collapsedField.collapsed = collapsedField.collapsed || [];
+            collapsedField.collapsed.push(field);
+          }
+        }
+      });
+  }
+}
+
+export default FieldGroup;

package/src/mdast2jcr/domain/FieldGroupFieldResolver.js

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2024 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.
+ */
+
+/**
+ * The FieldResolver class attempts to resolve a node to a model's field.
+ */
+class FieldGroupFieldResolver {
+  /**
+   * Constructor.
+   * @param {Component} component - the component associated with the model.
+   */
+  constructor(component) {
+    this.component = component;
+  }
+
+  /**
+   * Return the collapsed field name, that can support the node's heading depth.
+   * If the field does not have a collapsed field that matches the heading
+   * depth, then return undefined.
+   * @param node - the node
+   * @param field - the field
+   * @return {Field} a field that matches the node or undefined
+   */
+  getFieldSupportingHeading(node, field) {
+    const fieldsFromTemplate = Object.entries(this.component.defaultFields)
+      .filter(([name]) => name.endsWith('Type'))
+      .filter(([, value]) => value === `h${node.depth}`);
+
+    // go through all the collapsed fields of the field and see if we can find
+    // a field that matches the name of our best match from the template
+    return field.collapsed
+      .find((cf) => fieldsFromTemplate.find(([name]) => cf.name === name));
+  }
+
+  /**
+   * Resolve the field.
+   * @param {Node} node - the node
+   * @param {{isGrouped: boolean, name: string, fields: [],
+   * collapsed: [{isGrouped: boolean, name: string, fields: []}]}} fieldGroup - the field group
+   */
+  resolve(node, fieldGroup) {
+    const { fields } = fieldGroup;
+    if (fields === undefined) {
+      // throw an Error indicating the issue
+      throw new Error(`Field group ${fieldGroup.name} does not have any fields defined.`);
+    }
+
+    let foundField = fields.find((field) => {
+      if (node.type === 'heading' && field.collapsed?.find((c) => c.name.endsWith('Type'))) {
+        // try to find a field that matches the heading depth, if we have one
+        // then the field supports it so we can return true
+        if (!this.getFieldSupportingHeading(node, field)) {
+          // if the field does not match the heading type then we return false
+          return false;
+        }
+        // if we have a match then we remove all fields up to and including the match
+        fields.splice(0, fields.indexOf(field) + 1);
+        return true;
+      } else if (node.type === 'paragraph') {
+        // is the first child an image?
+        if (node.children[0]?.type === 'image') {
+          // remove the field from fields
+          fields.splice(fields.indexOf(field), 1);
+          return true;
+        }
+
+        // do we have a link
+        if (node.children[0]?.type === 'link') {
+          fields.splice(fields.indexOf(field), 1);
+          return true;
+        }
+        return false;
+      }
+
+      return false;
+    });
+
+    if (!foundField) {
+      [foundField] = fields.splice(0, 1);
+    }
+
+    // if foundField is undefined then return the next field from the fields.
+    return foundField;
+  }
+}
+
+export default FieldGroupFieldResolver;

package/src/mdast2jcr/domain/ModelHelper.js

@@ -0,0 +1,123 @@
+/*
+ * Copyright 2024 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 { getComponentById, getComponentByTitle } from './Definitions.js';
+import FieldGroup from './FieldGroup.js';
+
+/**
+ * @typedef {import('../index.d.ts').Filter} Filter
+ */
+
+class ModelHelper {
+  /**
+   * Constructor.
+   * @param {string} blockName The block name.
+   * @param {Array<Model>} models The models.
+   * @param {Definition} definition The definition object.
+   * @param {Array<Filter>} filters The filters to apply to the fields.
+   */
+  constructor(blockName, models, definition, filters) {
+    this.blockName = blockName;
+    this._checkFieldOrder(models);
+    this.models = models;
+    this.definition = definition;
+    this.filters = filters;
+    this.groups = [];
+    this._groupModelFields();
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  _checkFieldOrder(models) {
+    const suffixes = ['Alt', 'MimeType', 'Type', 'Text', 'Title'];
+
+    models.forEach((model) => {
+      const seenBaseFields = new Set();
+      let warningGenerated = false;
+      const warnings = [];
+
+      model.fields.forEach((field) => {
+        const suffixMatch = suffixes.find((suffix) => field.name.endsWith(suffix));
+        const baseName = suffixMatch ? field.name.slice(0, -suffixMatch.length) : field.name;
+
+        if (suffixMatch) {
+          // This is a suffix field, we need to check if its base field exists
+          if (!seenBaseFields.has(baseName)) {
+            if (!warningGenerated) {
+              warnings.push(`Warning in model '${model.id}': Fields with suffixes should follow their base field.`);
+              warningGenerated = true;
+            }
+            warnings.push(`  - Field '${field.name}' appears before its base field '${baseName}'.`);
+          }
+        } else {
+          // This is a base field, add it to seenBaseFields
+          seenBaseFields.add(baseName);
+        }
+      });
+
+      if (warningGenerated) {
+        throw new Error(warnings.join('\n'));
+      }
+    });
+  }
+
+  /**
+   * Group the fields in the models.
+   *
+   * Given the name of the block, get the component and then locate the model.  If the component
+   * has a filter, then get the filter and locate the associated component and its model.
+   *
+   * Each model will have a FieldGroup associated with it.
+   * Each FieldGroup will contain the fields that belong to the model and any fields that
+   * are part of a collapsed field will be grouped together.
+   */
+  _groupModelFields() {
+    const component = getComponentByTitle(this.definition, this.blockName);
+    const model = this.models.find((m) => m.id === component.modelId);
+
+    // this FieldGroup is for the main model
+    if (model) {
+      this.groups.push({ modelId: model?.id || undefined, fieldGroup: new FieldGroup(model) });
+    }
+
+    // if the component has a filter, then get the associated model and create a FieldGroup for it
+    if (component.filterId) {
+      const filter = this.filters.find((f) => f.id === component.filterId);
+
+      // now for each filter, get the model and create a FieldGroup for it
+      filter.components.forEach((componentName) => {
+        const c = getComponentById(this.definition, componentName);
+        const filtersModel = this.models.find((m) => m.id === c.modelId);
+
+        // could not locate the model for the filter throw
+        if (!filtersModel) {
+          throw new Error(`Unable to locate model for filter ${componentName}`);
+        }
+
+        this.groups.push({ modelId: filtersModel.id, fieldGroup: new FieldGroup(filtersModel) });
+      });
+    }
+  }
+
+  /**
+   * Return the field group associated with the model id.
+   * @param modelId
+   * @return {FieldGroup|*|null}
+   */
+  getModelFieldGroup(modelId) {
+    const result = this.groups.find((group) => group.modelId === modelId);
+
+    // no need to pass the fieldGroup just return the fields in the group
+    return (result) ? result.fieldGroup : null;
+  }
+}
+
+export default ModelHelper;