@financial-times/dotcom-server-handlebars 7.3.0 → 7.3.2

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@financial-times/dotcom-server-handlebars",
-  "version": "7.3.0",
+  "version": "7.3.2",
   "description": "",
   "main": "dist/node/index.js",
   "types": "src/index.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "tsc": "../../node_modules/.bin/tsc --incremental",
     "clean": "npm run clean:dist && npm run clean:node_modules",
     "clean:dist": "rm -rf dist",
     "clean:node_modules": "rm -rf node_modules",
-    "build:node": "npm run tsc -- --module commonjs --outDir ./dist/node",
+    "build:node": "tsc",
     "build": "npm run build:node",
     "dev": "npm run build:node -- --watch",
     "preinstall": "[ \"$INIT_CWD\" != \"$PWD\" ] || npm_config_yes=true npx check-engine"
@@ -31,6 +30,10 @@
     "node": ">= 14.0.0",
     "npm": "7.x || 8.x"
   },
+  "files": [
+    "dist/",
+    "src/"
+  ],
   "repository": {
     "type": "git",
     "repository": "https://github.com/Financial-Times/dotcom-page-kit.git",
@@ -43,4 +46,4 @@
   "devDependencies": {
     "check-engine": "^1.10.1"
   }
-}
+}

package/src/__test__/HandlebarsRenderer.spec.ts

@@ -0,0 +1,99 @@
+import path from 'path'
+import { PageKitHandlebars as Subject } from '../PageKitHandlebars'
+
+// NOTE: Tests are run from the repository root directory so we need to set the CWD
+const root = path.join(__dirname, '__fixtures__')
+const view = path.resolve(root, 'views/view.hbs')
+
+describe('dotcom-server-handlebars/src/PageKitHandlebars', () => {
+  let instance
+
+  beforeEach(() => {
+    instance = new Subject({
+      rootDirectory: root,
+      cache: true
+    })
+  })
+
+  describe('.loadPartials()', () => {
+    let result
+
+    beforeEach(() => {
+      result = instance.loadPartials()
+    })
+
+    it('loads and compiles partial templates from disk', () => {
+      const values = Object.values(result)
+
+      expect(values.length).toBe(3)
+
+      values.forEach((template) => {
+        expect(template).toEqual(expect.any(Function))
+      })
+    })
+
+    it('caches each compiled partial template', () => {
+      const keys = Object.keys(result)
+
+      keys.forEach((key) => {
+        const filename = path.join(root, `views/partials/${key}.hbs`)
+        expect(instance.cache.has(filename)).toBe(true)
+      })
+    })
+  })
+
+  describe('.loadTemplate()', () => {
+    let result
+
+    beforeEach(() => {
+      result = instance.loadTemplate(view)
+    })
+
+    it('loads and compiles a template from disk', () => {
+      expect(result).toEqual(expect.any(Function))
+    })
+
+    it('caches the compiled template', () => {
+      expect(instance.cache.has(view)).toBe(true)
+    })
+  })
+
+  describe('.render()', () => {
+    const templateContext = { title: 'Hello World', aside: 'Lorem ipsum' }
+
+    it('can render a template from disk', () => {
+      const result = instance.render(view, templateContext)
+
+      expect(result).toContain('<h1>Hello World</h1>')
+      expect(result).toContain('<aside>Lorem ipsum</aside>')
+      expect(result).toMatch(/<main>.+<\/main>/s)
+    })
+
+    it('can render a given template function', () => {
+      const template = instance.loadTemplate(view)
+      const result = instance.render(template, templateContext)
+
+      expect(result).toContain('<h1>Hello World</h1>')
+      expect(result).toContain('<aside>Lorem ipsum</aside>')
+      expect(result).toMatch(/<main>.+<\/main>/s)
+    })
+  })
+
+  describe('.renderView()', () => {
+    it('can render a template and fire a callback with the result', () => {
+      return new Promise((done) => {
+        const templateContext = { title: 'Hello World', aside: 'Lorem ipsum' }
+
+        instance.renderView(view, templateContext, (error, result) => {
+          expect(error).toBeNull()
+
+          expect(result).toContain('<h1>Hello World</h1>')
+          expect(result).toContain('<aside>Lorem ipsum</aside>')
+          expect(result).toMatch(/<main>.+<\/main>/s)
+
+          done()
+        })
+      })
+    })
+  })
+})

package/src/__test__/__fixtures__/components/DefaultExportComponentCJS.js

@@ -0,0 +1,5 @@
+const React = require('react')
+
+module.exports = function ({ text }) {
+  return React.createElement('div', null, text)
+}

package/src/__test__/__fixtures__/components/DefaultExportComponentES.tsx

@@ -0,0 +1,5 @@
+import React from 'react'
+
+export default function ({ text }) {
+  return <div>{text}</div>
+}

package/src/__test__/__fixtures__/components/NamedExportComponentCJS.js

@@ -0,0 +1,5 @@
+const React = require('react')
+
+exports.Component = function ({ text }) {
+  return React.createElement('div', null, text)
+}

package/src/__test__/__fixtures__/components/NamedExportComponentES.tsx

@@ -0,0 +1,5 @@
+import React from 'react'
+
+export function Component({ text }) {
+  return <div>{text}</div>
+}

package/src/__test__/__fixtures__/views/partials/content.hbs

@@ -0,0 +1 @@
+<h1>{{title}}</h1>

package/src/__test__/__fixtures__/views/partials/partial.hbs

@@ -0,0 +1 @@
+<aside>{{aside}}</aside>

package/src/__test__/__fixtures__/views/partials/wrapper.hbs

@@ -0,0 +1,3 @@
+<main>
+  {{> @partial-block }}
+</main>

package/src/__test__/__fixtures__/views/view.hbs

@@ -0,0 +1,4 @@
+{{#> wrapper }}
+  {{>content}}
+  {{>partial}}
+{{/wrapper}}

package/src/__test__/helpers.spec.ts

@@ -0,0 +1,341 @@
+import { compile } from 'handlebars'
+import * as helpers from '../helpers'
+
+describe('dotcom-server-handlebars/src/helpers', () => {
+  describe('block helpers', () => {
+    describe('#capture', () => {
+      it('captures the string and assigns it to a variable', () => {
+        const template = compile('{{#capture "myOutput"}}Hello, World!{{/capture}}')
+        const templateData = {} as { [key: string]: any }
+        const result = template(templateData, { helpers })
+
+        expect(templateData.myOutput).toBe('Hello, World!')
+        expect(result).toBe('')
+      })
+    })
+
+    describe('#dateformat', () => {
+      const date = new Date('2019-04-10 13:40:21 GMT+0100 (BST)')
+
+      it('formats as ISO date time by default', () => {
+        const template = compile('{{#dateformat}}{{date}}{{/dateformat}}')
+        const result = template({ date }, { helpers })
+
+        expect(result).toBe('2019-04-10T12:40:21Z')
+      })
+
+      it('formats using the given format', () => {
+        const template = compile('{{#dateformat "dddd, mmmm d, yyyy"}}{{date}}{{/dateformat}}')
+        const result = template({ date }, { helpers })
+
+        expect(result).toBe('Wednesday, April 10, 2019')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#dateformat "" ""}}{{date}}{{/dateformat}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifAll', () => {
+      const template = compile('{{#ifAll foo bar baz}}yes{{else}}no{{/ifAll}}')
+
+      it('outputs the contents when all parameters are truthy', () => {
+        const result = template({ foo: 123, bar: 'abc', baz: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameters are falsy', () => {
+        const result = template({ foo: 123, bar: 'abc', baz: false }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifSome}}yes{{/ifSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifEquals', () => {
+      const template = compile('{{#ifEquals foo bar}}yes{{else}}no{{/ifEquals}}')
+
+      it('outputs the contents parameters are strictly equal', () => {
+        const result = template({ foo: true, bar: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameter is not strictly equal', () => {
+        const result = template({ foo: true, bar: null }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifEquals}}yes{{/ifEquals}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifEqualsSome', () => {
+      const template = compile('{{#ifEqualsSome foo bar baz}}yes{{else}}no{{/ifEqualsSome}}')
+
+      it('outputs the contents if parameters are strictly equal', () => {
+        const result = template({ foo: true, bar: true, baz: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('outputs true if first parameter is equal', () => {
+        const result = template({ foo: true, bar: false, baz: true }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('outputs true if second parameter is equal', () => {
+        const result = template({ foo: true, bar: true, baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('outputs false if neither parameter is equal', () => {
+        const result = template({ foo: true, bar: false, baz: false }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifEqualsSome}}yes{{/ifEqualsSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#ifSome', () => {
+      const template = compile('{{#ifSome foo bar baz}}yes{{else}}no{{/ifSome}}')
+
+      it('outputs the contents if at least one parameter is truthy', () => {
+        const result = template({ foo: 123, bar: '', baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if all parameters are falsy', () => {
+        const result = template({ foo: 0, bar: '', baz: false }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#ifSome}}yes{{/ifSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#renderReactComponent', () => {
+      it('renders the specified component (exported as a default CJS Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/DefaultExportComponentCJS"
+          text="foo"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>foo</div>')
+      })
+
+      it('renders the specified component (exported as a default ES Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/DefaultExportComponentES"
+          text="bar"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>bar</div>')
+      })
+
+      it('renders the specified component (exported as a named CJS Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/NamedExportComponentCJS"
+          namedExport="Component"
+          text="baz"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>baz</div>')
+      })
+
+      it('renders the specified component (exported as a named ES Module export) from a local path', () => {
+        const template = compile(`{{{renderReactComponent
+          localPath="packages/dotcom-server-handlebars/src/__test__/__fixtures__/components/NamedExportComponentES"
+          namedExport="Component"
+          text="qux"
+        }}}`)
+        const result = template({}, { helpers })
+
+        expect(result).toBe('<div>qux</div>')
+      })
+
+      it('throws if mandatory parameters are not provided', () => {
+        const template = compile('{{{renderReactComponent}}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#resize', () => {
+      it('formats the image as an image service URL', () => {
+        const template = compile('{{#resize 640}}http://website.com/picture.jpg{{/resize}}')
+        const result = template({}, { helpers })
+
+        expect(result).toBe(
+          'https://www.ft.com/__origami/service/image/v2/images/raw/http%3A%2F%2Fwebsite.com%2Fpicture.jpg?width=640&source=next&fit=scale-down'
+        )
+      })
+
+      it('accepts named parameters', () => {
+        const template = compile('{{#resize 640 fit="contain"}}http://website.com/picture.jpg{{/resize}}')
+        const result = template({}, { helpers })
+
+        expect(result).toBe(
+          'https://www.ft.com/__origami/service/image/v2/images/raw/http%3A%2F%2Fwebsite.com%2Fpicture.jpg?width=640&source=next&fit=contain'
+        )
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#resize}}http://website.com/picture.jpg{{/resize}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#slice', () => {
+      it('slices a given array and iterates over the new array', () => {
+        const template = compile('{{#slice items offset="2" limit="3"}}{{this}}{{/slice}}')
+        const result = template({ items: [1, 2, 3, 4, 5, 6] }, { helpers })
+
+        expect(result).toBe('345')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#slice offset="2" limit="3"}}{{this}}{{/slice}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#unlessAll', () => {
+      const template = compile('{{#unlessAll foo bar baz}}yes{{else}}no{{/unlessAll}}')
+
+      it('outputs the contents if all parameters are falsy', () => {
+        const result = template({ foo: 0, bar: '', baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameters are truthy', () => {
+        const result = template({ foo: 0, bar: '', baz: true }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#unlessAll}}yes{{/unlessAll}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#unlessEquals', () => {
+      const template = compile('{{#unlessEquals foo bar}}yes{{else}}no{{/unlessEquals}}')
+
+      it('outputs the contents if all parameters are falsy', () => {
+        const result = template({ foo: true, bar: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if any parameters are truthy', () => {
+        const result = template({ foo: true, bar: true }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#unlessEquals}}yes{{/unlessEquals}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('#unlessSome', () => {
+      const template = compile('{{#unlessSome foo bar baz}}yes{{else}}no{{/unlessSome}}')
+
+      it('outputs the contents if any parameters are falsy', () => {
+        const result = template({ foo: 1, bar: 'abc', baz: false }, { helpers })
+        expect(result).toBe('yes')
+      })
+
+      it('does not output the contents if all parameters are truthy', () => {
+        const result = template({ foo: 1, bar: 'abc', baz: true }, { helpers })
+        expect(result).toBe('no')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{#unlessSome}}yes{{/unlessSome}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+  })
+
+  describe('inline helpers', () => {
+    describe('array', () => {
+      it('converts all parameters into one array', () => {
+        const template = compile('{{array foo bar baz}}')
+        const result = template({ foo: 1, bar: 2, baz: 3 }, { helpers })
+
+        expect(result).toBe('1,2,3')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{array}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('concat', () => {
+      it('concatenates all parameters into one string', () => {
+        const template = compile('{{concat "Welcome to " place ", " name}}')
+        const result = template({ place: 'Hell', name: 'human' }, { helpers })
+
+        expect(result).toBe('Welcome to Hell, human')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{concat}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('encode', () => {
+      it('encodes the parameter as a URI component', () => {
+        const template = compile('{{{encode title}}}')
+        const result = template({ title: 'http://www.foo.com?bar=baz&qux=«»' }, { helpers })
+
+        expect(result).toBe('http%3A%2F%2Fwww.foo.com%3Fbar%3Dbaz%26qux%3D%C2%AB%C2%BB')
+      })
+
+      it('encodes the parameter as a complete URI', () => {
+        const template = compile('{{{encode title mode="uri"}}}')
+        const result = template({ title: 'http://www.foo.com?bar=baz&qux=«»' }, { helpers })
+
+        expect(result).toBe('http://www.foo.com?bar=baz&qux=%C2%AB%C2%BB')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{encode}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+    })
+
+    describe('json', () => {
+      it('stringifies the parameter', () => {
+        const template = compile('{{{json data}}}')
+        const result = template({ data: { foo: 'bar', baz: 123, qux: true } }, { helpers })
+
+        expect(result).toBe('{"foo":"bar","baz":123,"qux":true}')
+      })
+
+      it('throws if the incorrect number of parameters are provided', () => {
+        const template = compile('{{json}}')
+        expect(() => template({}, { helpers })).toThrow()
+      })
+
+      it('throws if the user tries to output the @root context', () => {
+        const template = compile('{{json data}}')
+        expect(() => template({ data: { _locals: true } }, { helpers })).toThrow()
+      })
+    })
+  })
+})