feat(markdown): show some info about properties, switch i18n library

lib/markdownBuilder.js

@@ -10,76 +10,81 @@
  * governing permissions and limitations under the License.
  */
 const {
-  each, values, map, list: flist,
+  each, values, map, list: flist, iter, flat, filter, size
 } = require('ferrum');
 const {
-  root, paragraph, text, heading, code, table, tableRow, tableCell, link,
+  root, paragraph, text, heading, code, table, tableRow, tableCell, link, inlineCode
 } = require('mdast-builder');
+const i18n = require('es2015-i18n-tag').default;
 
 function build({ header, links = {} }) {
   const headerprops = [
     {
       name: 'type',
-      title: 'Type',
-      objectlabel: 'Object',
-      arraylabel: 'Array',
+      title: i18n`Type`,
+      objectlabel: i18n`Object`,
+      arraylabel: i18n`Array`,
     },
     {
       name: 'abstract',
-      title: 'Abstract',
-      truelabel: 'Cannot be instantiated',
-      falselabel: 'Can be instantiated',
-      undefinedlabel: 'Unknown abstraction'
+      title: i18n`Abstract`,
+      truelabel: i18n`Cannot be instantiated`,
+      falselabel: i18n`Can be instantiated`,
+      undefinedlabel: i18n`Unknown abstraction`
     },
     {
       name: 'extensible',
-      title: 'Extensible',
-      undefinedlable: 'Unknown extensibility',
-      truelabel: 'Yes',
-      falselabel: 'No',
+      title: i18n`Extensible`,
+      undefinedlable: i18n`Unknown extensibility`,
+      truelabel: i18n`Yes`,
+      falselabel: i18n`No`,
     },
     {
       name: 'status',
-      title: 'Status',
+      title: i18n`Status`,
       undefinedlabel: 'Unknown status',
-      deprecatedlabel: 'Deprecated',
-      stablelabel: 'Stable',
-      stabilizinglabel: 'Stabilizing',
-      experimentallabel: 'Experimental',
+      deprecatedlabel: i18n`Deprecated`,
+      stablelabel: i18n`Stable`,
+      stabilizinglabel: i18n`Stabilizing`,
+      experimentallabel: i18n`Experimental`,
     },
     {
       name: 'identifiable',
-      title: 'Identifiable',
-      truelabel: 'Yes',
-      falselabel: 'No',
-      undefinedlabel: 'Unknown identifiability'
+      title: i18n`Identifiable`,
+      truelabel: i18n`Yes`,
+      falselabel: i18n`No`,
+      undefinedlabel: i18n`Unknown identifiability`
     },
     {
       name: 'custom',
-      title: 'Custom Properties',
-      truelabel: 'Allowed',
-      falselabel: 'Forbidden',
-      undefinedlabel: 'Unknown custom properties'
+      title: i18n`Custom Properties`,
+      truelabel: i18n`Allowed`,
+      falselabel: i18n`Forbidden`,
+      undefinedlabel: i18n`Unknown custom properties`
     },
     {
       name: 'additional',
-      title: 'Additional Properties',
-      truelabel: 'Allowed',
-      falselabel: 'Forbidden',
-      undefinedlabel: 'Unknown additional properties'
+      title: i18n`Additional Properties`,
+      truelabel: i18n`Allowed`,
+      falselabel: i18n`Forbidden`,
+      undefinedlabel: i18n`Unknown additional properties`
     },
     {
       name: 'definedin',
-      title: 'Defined In',
-      undefinedlabel: 'Unknown definition'
+      title: i18n`Defined In`,
+      undefinedlabel: i18n`Unknown definition`
     },
   ];
 
 
+  /**
+   * Generates the overall header for the schema documentation
+   * @param {*} schema 
+   */
   function makeheader(schema) {
     if (header) {
       return [
-        heading(1, text(`${schema.title} Schema`)),
+        heading(1, text(i18n`${schema.title} Schema`)),
         paragraph(code('txt', schema.id + (schema.pointer ? `#${schema.pointer}` : ''))),
         schema.longdescription,
         table('left', [
@@ -89,7 +94,7 @@ function build({ header, links = {} }) {
               map(headerprops,
                 ({ name, title }) => {
                   if (links[name]) {
-                    return tableCell(link(links[name], `What does ${title} mean?`, text(title)));
+                    return tableCell(link(links[name], i18n`What does ${title} mean?`, text(title)));
                   }
                   return tableCell(text(title));
                 }), Array,
@@ -104,10 +109,10 @@ function build({ header, links = {} }) {
                     typeof schema.meta[prop.name] === 'object' && 
                     schema.meta[prop.name].link &&
                     schema.meta[prop.name].text) {
-                    return tableCell(link(schema.meta[prop.name].link, 'open original schema', [text(schema.meta[prop.name].text)]));
+                    return tableCell(link(schema.meta[prop.name].link, i18n`open original schema`, [text(schema.meta[prop.name].text)]));
                   }
                   const value = schema.meta ? schema.meta[prop.name] : undefined;
-                  return tableCell(text(prop[String(value) + 'label'] || 'Unknown'));
+                  return tableCell(text(prop[String(value) + 'label'] || i18n`Unknown`));
                 }), Array,
             ),
           ),
@@ -117,11 +122,95 @@ function build({ header, links = {} }) {
     return [];
   }
 
+  function type(property) {
+    const types = Array.isArray(property.type) ? property.type : [ property.type ];
+    const realtypes = flist(filter(types, type => type !== 'null' && type !== undefined));
+    if (size(realtypes) === 0) {
+      return text(i18n`Not specified`);
+    } else if (size(realtypes) === 1) {
+      const [ realtype ] = realtypes;
+      // TODO needs better handling of named types
+      return inlineCode(realtype);
+    } else {
+      return text(i18n`Multiple`);
+    }
+  }
+
+  function nullable(property) {
+    const types = Array.isArray(property.type) ? property.type : [ property.type ];
+    const nulltypes = flist(filter(types, type => type === 'null' ));
+    if (size(nulltypes)) {
+      return text(i18n`can be null`);
+    }
+    return text(i18n`cannot be null`);
+  }
+
+  /**
+   * Generates the overview table row for a single property definition
+   * @param {*} param0 
+   */
+  function makepropheader([name, definition]) {
+    return tableRow([
+      tableCell(text(name)), // Property
+      tableCell(type(definition)),
+      tableCell(text('-')),
+      tableCell(nullable(definition))
+    ]);
+  }
+
+  /**
+   * Generates the table of contents for a properties
+   * object.
+   * @param {*} props 
+   */
+  function makeproptable(props) {
+    return table('left', [
+      tableRow([
+        tableCell(text(i18n`Property`)),
+        tableCell(text(i18n`Type`)),
+        tableCell(text(i18n`Required`)),
+        tableCell(text(i18n`Nullable`)),
+        tableCell(text(i18n`Defined by`))
+      ]),
+      ...flist(map(iter(props || {}), makepropheader))
+    ]);
+  }
+
+  /**
+   * Generates the definitions section for a schema
+   * @param {*} schema 
+   */
+  function makedefinitions(schema) {
+    if (schema.schema.definitions) {
+      return [
+        heading(1, text(i18n`${schema.title} Definitions`)),
+        makeproptable(schema.schema.definitions),
+      ];
+    }
+    return [];
+  }
+
+  /**
+   * Generates the properties section for a schema
+   * @param {*} schema 
+   */
+  function makeproperties(schema) {
+    if (schema.schema.properties) {
+      return [
+        heading(1, text(i18n`${schema.title} Properties`)),
+        makeproptable(schema.schema.properties),
+      ];
+    }
+    return [];
+  }
+
   return (schemas) => {
   // eslint-disable-next-line no-return-assign, no-param-reassign
     each(values(schemas), schema => schema.markdown = root([
     // todo add more elements
       ...makeheader(schema),
+      ...makedefinitions(schema),
+      ...makeproperties(schema)
     ]));
     return schemas;
   };

package.json

@@ -19,9 +19,9 @@
     "@adobe/helix-log": "^2.0.0",
     "ajv": "^6.10.2",
     "ejs": "^2.6.2",
+    "es2015-i18n-tag": "^1.6.1",
     "ferrum": "^1.4.1",
     "github-slugger": "^1.2.1",
-    "i18next": "^19.0.1",
     "js-yaml": "^3.13.1",
     "json-pointer": "^0.6.0",
     "mdast-builder": "^1.1.1",