From 8e3ec8c3450ce7a3dc401cf6797fc94338e873b7 Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sun, 2 Jan 2022 10:50:06 +0100 Subject: [PATCH 01/10] refactor: corrected annotations.js to annotations.json --- .../dist/_annotations/{annotations.js => annotations.json} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/starterkit-twig-demo/dist/_annotations/{annotations.js => annotations.json} (100%) diff --git a/packages/starterkit-twig-demo/dist/_annotations/annotations.js b/packages/starterkit-twig-demo/dist/_annotations/annotations.json similarity index 100% rename from packages/starterkit-twig-demo/dist/_annotations/annotations.js rename to packages/starterkit-twig-demo/dist/_annotations/annotations.json From 41b4ec15243ba8b1e56bb1efce7d39dfe4c4e150 Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sun, 2 Jan 2022 10:58:18 +0100 Subject: [PATCH 02/10] refactor(annotations): allow .json extension on annotations file #836 --- ...tion_exporter.js => annotationExporter.js} | 50 +++++++++++-------- packages/core/src/lib/exportData.js | 6 +-- .../core/test/annotation_exporter_tests.js | 6 +-- 3 files changed, 35 insertions(+), 27 deletions(-) rename packages/core/src/lib/{annotation_exporter.js => annotationExporter.js} (67%) diff --git a/packages/core/src/lib/annotation_exporter.js b/packages/core/src/lib/annotationExporter.js similarity index 67% rename from packages/core/src/lib/annotation_exporter.js rename to packages/core/src/lib/annotationExporter.js index dffb01253..ffd16eb15 100644 --- a/packages/core/src/lib/annotation_exporter.js +++ b/packages/core/src/lib/annotationExporter.js @@ -6,39 +6,47 @@ const _ = require('lodash'); const mp = require('./markdown_parser'); const logger = require('./log'); -const annotations_exporter = function (pl) { +const annotationExporter = function (pl) { const paths = pl.config.paths; - let oldAnnotations; /** * Parses JS annotations. * @returns array of comments that used to be wrapped in raw JS */ - function parseAnnotationsJS() { + function parseAnnotationsJSON() { + const jsonPath = path.resolve(paths.source.annotations, 'annotations.json'); + let annotations; + //attempt to read the file try { - oldAnnotations = fs.readFileSync( - path.resolve(paths.source.annotations, 'annotations.js'), - 'utf8' - ); + if (fs.pathExistsSync(jsonPath)) { + //read the new file + annotations = fs.readFileSync(jsonPath, 'utf8'); + } else { + //read the old file + const jsPath = path.resolve(paths.source.annotations, 'annotations.js'); + + annotations = fs + .readFileSync(jsPath, 'utf8') + .replace(/^\s*var comments ?= ?/, '') + .replace(/};\s*$/, '}'); + + logger.info( + `Please convert ${jsPath} to JSON and rename it annotations.json.` + ); + } } catch (ex) { logger.debug( - `annotations.js file missing from ${paths.source.annotations}. This may be expected if you do not use annotations or are using markdown.` + `annotations.json file missing from ${paths.source.annotations}. This may be expected if you do not use annotations or are using markdown.` ); return []; } - //parse as JSON by removing the old wrapping js syntax. comments and the trailing semi-colon - oldAnnotations = oldAnnotations.replace('var comments = ', ''); - oldAnnotations = oldAnnotations.replace('};', '}'); - try { - const oldAnnotationsJSON = JSON.parse(oldAnnotations); - return oldAnnotationsJSON.comments; + const annotationsJSON = JSON.parse(annotations); + return annotationsJSON.comments; } catch (ex) { - logger.error( - `There was an error parsing JSON for ${paths.source.annotations}annotations.js` - ); + logger.error(`There was an error parsing JSON for ${jsonPath}`); return []; } } @@ -104,7 +112,7 @@ const annotations_exporter = function (pl) { * @returns array of annotations */ function gatherAnnotations() { - const annotationsJS = parseAnnotationsJS(); + const annotationsJS = parseAnnotationsJSON(); const annotationsMD = parseAnnotationsMD(); return _.unionBy(annotationsJS, annotationsMD, 'el'); } @@ -113,8 +121,8 @@ const annotations_exporter = function (pl) { gather: function () { return gatherAnnotations(); }, - gatherJS: function () { - return parseAnnotationsJS(); + gatherJSON: function () { + return parseAnnotationsJSON(); }, gatherMD: function () { return parseAnnotationsMD(); @@ -122,4 +130,4 @@ const annotations_exporter = function (pl) { }; }; -module.exports = annotations_exporter; +module.exports = annotationExporter; diff --git a/packages/core/src/lib/exportData.js b/packages/core/src/lib/exportData.js index a229cc815..aeef0a845 100644 --- a/packages/core/src/lib/exportData.js +++ b/packages/core/src/lib/exportData.js @@ -3,7 +3,7 @@ const path = require('path'); const eol = require('os').EOL; -const ae = require('./annotation_exporter'); +const ae = require('./annotationExporter'); let fs = require('fs-extra'); //eslint-disable-line prefer-const @@ -12,7 +12,7 @@ let fs = require('fs-extra'); //eslint-disable-line prefer-const * @param patternlab - global data store */ module.exports = function (patternlab, uikit) { - const annotation_exporter = new ae(patternlab); + const annotationExporter = new ae(patternlab); const paths = patternlab.config.paths; @@ -67,7 +67,7 @@ module.exports = function (patternlab, uikit) { eol; //annotations - const annotationsJSON = annotation_exporter.gather(); + const annotationsJSON = annotationExporter.gather(); const annotations = 'var comments = { "comments" : ' + JSON.stringify(annotationsJSON) + '};'; fs.outputFileSync( diff --git a/packages/core/test/annotation_exporter_tests.js b/packages/core/test/annotation_exporter_tests.js index 01b71e6d8..b1c2f9723 100644 --- a/packages/core/test/annotation_exporter_tests.js +++ b/packages/core/test/annotation_exporter_tests.js @@ -20,12 +20,12 @@ function createFakePatternLab(anPath, customProps) { } var patternlab = createFakePatternLab(anPath); -var ae = require('../src/lib/annotation_exporter')(patternlab); +var ae = require('../src/lib/annotationExporter')(patternlab); tap.test('converts old JS annotations into new format', function (test) { //arrange //act - var annotations = ae.gatherJS(); + var annotations = ae.gatherJSON(); //assert test.equal(annotations.length, 2); @@ -77,7 +77,7 @@ tap.test('merges both annotation methods into one array', function (test) { tap.test('when there are 0 annotation files', function (test) { var emptyAnPath = './test/files/empty/'; var patternlab2 = createFakePatternLab(emptyAnPath); - var ae2 = require('../src/lib/annotation_exporter')(patternlab2); + var ae2 = require('../src/lib/annotationExporter')(patternlab2); var annotations = ae2.gather(); test.equal(annotations.length, 0); From 7a54522ab45ac2be7d41e6a9aa2a35ead9e00ec9 Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sun, 2 Jan 2022 11:13:54 +0100 Subject: [PATCH 03/10] refactor: corrected annotations.js to annotations.json --- .../source/_annotations/{annotations.js => annotations.json} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/edition-twig/source/_annotations/{annotations.js => annotations.json} (100%) diff --git a/packages/edition-twig/source/_annotations/annotations.js b/packages/edition-twig/source/_annotations/annotations.json similarity index 100% rename from packages/edition-twig/source/_annotations/annotations.js rename to packages/edition-twig/source/_annotations/annotations.json From dfd9e8ba284513a407fb822c8c307ce5d4ef914a Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sun, 2 Jan 2022 11:15:48 +0100 Subject: [PATCH 04/10] feat(annotations): added at least annotation to the sample content --- .../dist/_annotations/annotations.json | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 packages/starterkit-handlebars-demo/dist/_annotations/annotations.json diff --git a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json new file mode 100644 index 000000000..398701fd3 --- /dev/null +++ b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json @@ -0,0 +1,9 @@ +{ + "comments" : [ + { + "el": ".c-header", + "title" : "Masthead", + "comment": "The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content." + } + ] +} From 199d87d1c9dfd7f98bf4b996ac8c3852004e439c Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sun, 2 Jan 2022 15:38:10 +0100 Subject: [PATCH 05/10] chore: added another annotations example --- .../dist/_annotations/annotations.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json index 398701fd3..97bee1cc6 100644 --- a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json +++ b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json @@ -4,6 +4,11 @@ "el": ".c-header", "title" : "Masthead", "comment": "The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content." + }, + { + "el": ".c-logo", + "title": "Logo", + "comment": "The logo isn't an image but regular text, which ensures that the logo displays crisply even on high resolution displays." } ] } From 4b34af2269e9eb113e8f7056ae651f22674baf95 Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sun, 2 Jan 2022 17:18:25 +0100 Subject: [PATCH 06/10] refactor(docs): corrected the filetype in the docs as well --- packages/docs/src/docs/pattern-adding-annotations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/src/docs/pattern-adding-annotations.md b/packages/docs/src/docs/pattern-adding-annotations.md index f844a4a92..5e4de04b3 100644 --- a/packages/docs/src/docs/pattern-adding-annotations.md +++ b/packages/docs/src/docs/pattern-adding-annotations.md @@ -10,7 +10,7 @@ eleventyNavigation: sitemapPriority: '0.8' --- -Annotations provide an easy way to add notes to elements that may appear inside patterns. Annotations can be saved as a single JSON file at `./source/_annotations/annotations.js` or as multiple Markdown files in `./source/_annotations/`. They're _not_ tied to any specific patterns. When annotations are active they are compared against every pattern using a CSS selector syntax. +Annotations provide an easy way to add notes to elements that may appear inside patterns. Annotations can be saved as a single JSON file at `./source/_annotations/annotations.json` or as multiple Markdown files in `./source/_annotations/`. They're _not_ tied to any specific patterns. When annotations are active they are compared against every pattern using a CSS selector syntax. ## The Elements of an Annotation @@ -22,7 +22,7 @@ The elements of an annotation are: ## JSON Example -This is an example of an annotation saved as part of `annotations.js` that will be added to an element with the class `logo`: +This is an example of an annotation saved as part of `annotations.json` that will be added to an element with the class `logo`: ```javascript { From c585da98fbfdec6c05dc98127a5926b2960ed5ed Mon Sep 17 00:00:00 2001 From: Maximilian Franzke <787658+mfranzke@users.noreply.github.com> Date: Mon, 3 Jan 2022 05:40:28 +0100 Subject: [PATCH 07/10] docs(annotations): added further details --- packages/docs/src/docs/pattern-adding-annotations.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/docs/src/docs/pattern-adding-annotations.md b/packages/docs/src/docs/pattern-adding-annotations.md index 5e4de04b3..0e56010dd 100644 --- a/packages/docs/src/docs/pattern-adding-annotations.md +++ b/packages/docs/src/docs/pattern-adding-annotations.md @@ -32,6 +32,8 @@ This is an example of an annotation saved as part of `annotations.json` that wil } ``` +Compare to e.g. [`handlebars` annotations](https://github.com/pattern-lab/patternlab-node/blob/dev/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json) or [`twig` annotations](https://github.com/pattern-lab/patternlab-node/blob/dev/packages/starterkit-twig-demo/dist/_annotations/annotations.json) editions demo content as well. + ## Markdown Example This is an example of an annotation saved as part of `annotations.md` that will be added to an element with the class `logo`: From fb3ba221c5d31df38ab89e5938e9688456e4ae8b Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sat, 29 Jan 2022 20:53:29 +0100 Subject: [PATCH 08/10] refactor: removed this file again for the moment --- .../dist/_annotations/annotations.json | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 packages/starterkit-handlebars-demo/dist/_annotations/annotations.json diff --git a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json deleted file mode 100644 index 97bee1cc6..000000000 --- a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "comments" : [ - { - "el": ".c-header", - "title" : "Masthead", - "comment": "The main header of the site doesn't take up too much screen real estate in order to keep the focus on the core content." - }, - { - "el": ".c-logo", - "title": "Logo", - "comment": "The logo isn't an image but regular text, which ensures that the logo displays crisply even on high resolution displays." - } - ] -} From 18d475b932bfd5f7ec8e56c99fb31fd90e0fa7ae Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sat, 29 Jan 2022 20:54:00 +0100 Subject: [PATCH 09/10] refactor: renamed this file (after the latest merge) --- .../dist/_annotations/{annotations.js => annotations.json} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename packages/starterkit-handlebars-demo/dist/_annotations/{annotations.js => annotations.json} (95%) diff --git a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.js b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json similarity index 95% rename from packages/starterkit-handlebars-demo/dist/_annotations/annotations.js rename to packages/starterkit-handlebars-demo/dist/_annotations/annotations.json index 0812c089d..97bee1cc6 100644 --- a/packages/starterkit-handlebars-demo/dist/_annotations/annotations.js +++ b/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json @@ -1,4 +1,4 @@ -var comments = { +{ "comments" : [ { "el": ".c-header", @@ -11,4 +11,4 @@ var comments = { "comment": "The logo isn't an image but regular text, which ensures that the logo displays crisply even on high resolution displays." } ] -}; +} From ed0873df8679f4b31dfa9e2bb3b559ccdcad702b Mon Sep 17 00:00:00 2001 From: Maximilian <787658+mfranzke@users.noreply.github.com> Date: Sat, 29 Jan 2022 21:28:16 +0100 Subject: [PATCH 10/10] refactor: migrated that file as well --- .../source/_annotations/annotations.js | 3 --- .../source/_annotations/annotations.json | 3 +++ 2 files changed, 3 insertions(+), 3 deletions(-) delete mode 100644 packages/development-edition-engine-handlebars/source/_annotations/annotations.js create mode 100644 packages/development-edition-engine-handlebars/source/_annotations/annotations.json diff --git a/packages/development-edition-engine-handlebars/source/_annotations/annotations.js b/packages/development-edition-engine-handlebars/source/_annotations/annotations.js deleted file mode 100644 index ecc9b7e36..000000000 --- a/packages/development-edition-engine-handlebars/source/_annotations/annotations.js +++ /dev/null @@ -1,3 +0,0 @@ -var comments = { - "comments": [] -}; diff --git a/packages/development-edition-engine-handlebars/source/_annotations/annotations.json b/packages/development-edition-engine-handlebars/source/_annotations/annotations.json new file mode 100644 index 000000000..a0d0268f8 --- /dev/null +++ b/packages/development-edition-engine-handlebars/source/_annotations/annotations.json @@ -0,0 +1,3 @@ +{ + "comments": [] +}