hamlet-plugin-template 1.0.0

package/.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+end_of_line = crlf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true

package/README.md

@@ -0,0 +1,146 @@
+# hamlet-plugin-template
+
+Base template for creating Hamlet plugins.
+
+## Usage
+
+1. Rename the package in `package.json` (e.g. `@scope/hamlet-feature` or `hamlet-plugin-feature`).
+2. Implement your plugin in `index.js`.
+3. Run the tests.
+4. Publish to npm.
+
+## End-user installation
+
+```bash
+npm install hamlet-plugin-template
+```
+
+```js
+// hamlet.config.js
+import myPlugin from 'hamlet-plugin-template'
+
+export default {
+  plugins: [
+    myPlugin(),
+    // or with options:
+    myPlugin({ myOption: true }),
+  ],
+}
+```
+
+Plugins are imported and invoked directly from `hamlet.config.js`, similar to Vite or Rollup plugins. Hamlet never resolves plugins by package name—it only consumes the object returned by the plugin factory.
+
+## Plugin contract
+
+A plugin must export a default factory function that receives the user's options and returns an object with the following shape:
+
+```js
+export default function hamletPlugin(options = {}) {
+  return {
+    namespace: 'MyPlugin',
+    partials: {},
+    helpers: {},
+  }
+}
+```
+
+### namespace
+
+Every plugin must define a unique `namespace`.
+
+* It must start with a letter.
+* It may contain only letters and digits.
+* It is used to namespace all exported partials and helpers, preventing collisions with other plugins and the user's own project.
+
+### partials
+
+An object containing Handlebars partials.
+
+Every partial name must be prefixed with `<namespace>.`.
+
+Example:
+
+```js
+export default function hamletPlugin(options = {}) {
+  return {
+    namespace: 'MyPlugin',
+    partials: {
+      'MyPlugin.card': '<div>...</div>',
+    }
+  }
+}
+```
+
+### helpers
+
+An object containing Handlebars helpers.
+
+Every helper name must be prefixed with the namespace followed by an uppercase letter.
+
+Example:
+
+```js
+export default function hamletPlugin(options = {}) {
+  return {
+    namespace: 'MyPlugin',
+    helpers: {
+      MyPluginFormat: value => value.toUpperCase(),
+    }
+  }
+}
+```
+
+Helper names cannot contain dots because Handlebars interprets them as property paths rather than helper names.
+
+## Name collisions
+
+Hamlet follows a **first registered wins** policy.
+
+If a plugin attempts to register a partial or helper whose name already exists (whether provided by Hamlet, another plugin, or the user's project), the duplicate is ignored and a warning is printed.
+
+## Using Hamlet features inside plugin partials
+
+Plugin partials can freely use Hamlet's built-in helpers and partials.
+
+For example:
+
+```hbs
+{{concat "Hello, " name}}
+
+{{#switch value}}
+  ...
+{{/switch}}
+
+{{> hamlet.snippet}}
+```
+
+## Tests
+
+Before publishing:
+
+```bash
+npm install
+npm test
+```
+
+The test suite verifies that:
+
+* The plugin exports a valid factory function.
+* The returned object follows Hamlet's plugin contract.
+* A valid namespace is exported.
+* Partial and helper names follow Hamlet's naming rules.
+* Exported names use the plugin namespace.
+* No exported name collides with Hamlet's reserved names.
+* Partials compile successfully.
+* Helpers are valid functions.
+
+Feel free to extend the tests with plugin-specific behavior or option validation.
+
+## Linting
+
+This template uses the same ESLint configuration as Hamlet itself.
+
+```bash
+npm run lint
+npm run lint:fix
+```

package/eslint.config.js

@@ -0,0 +1,3 @@
+import antfu from '@antfu/eslint-config'
+
+export default antfu()

package/index.js

@@ -0,0 +1,39 @@
+/**
+ * Hamlet plugin template.
+ *
+ * Export a factory function that receives the options from
+ * hamlet.config.js and returns:
+ *
+ *   - namespace: A unique plugin namespace. All exported partials and
+ *     helpers must use this namespace to avoid collisions.
+ *
+ *   - partials: An object of Handlebars partials. Every partial name
+ *     must be prefixed with "<namespace>." (e.g. "myPlugin.card").
+ *
+ *   - helpers: An object of Handlebars helpers. Every helper name must
+ *     be prefixed with the namespace (e.g. "myPluginFormat"). Dots are
+ *     not allowed because Handlebars interprets them as property paths.
+ *
+ * The example below exports one partial and one helper. Replace them
+ * with your own implementation, or start with empty { partials, helpers }
+ * objects while keeping the namespace consistent.
+ *
+ * @param {object} options - Options from hamlet.config.js.
+ * @return {{namespace: string, partials: object, helpers: object}}
+ */
+export default function hamletPlugin(options = {}) {
+  const { greeting = 'Hello World' } = options
+
+  return {
+    namespace: 'MyPlugin',
+
+    partials: {
+      // Usage in a .hbs file: {{> myPlugin.hello}}
+      'myPlugin.hello': `MyPlugin says: {{myPluginShout greeting}}`,
+    },
+    helpers: {
+      // Usage in a .hbs file: {{myPluginShout "Hello World"}}
+      myPluginShout: text => `${text ?? greeting}!`.toUpperCase(),
+    },
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "hamlet-plugin-template",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A plugin template for hamlet",
+  "license": "MIT",
+  "keywords": [
+    "hamlet",
+    "hamlet-plugin"
+  ],
+  "exports": {
+    ".": "./index.js"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.1.0",
+    "eslint": "^10.6.0",
+    "handlebars": "^4.7.9",
+    "vitest": "^4.1.9"
+  }
+}

package/test/Plugin.test.js

@@ -0,0 +1,167 @@
+import assert from 'node:assert/strict'
+import Handlebars from 'handlebars'
+import { it } from 'vitest'
+import plugin from '../index.js'
+
+// Reserved names exposed natively by hamlet.
+const RESERVED_HELPERS = new Set([
+  'asset',
+  'currentYear',
+  'helperMissing',
+  'blockHelperMissing',
+  'switch',
+  'case',
+  'default',
+  'eq',
+  'ne',
+  'lt',
+  'gt',
+  'and',
+  'or',
+  'not',
+  'concat',
+  'includes',
+  'capitalize',
+  'first',
+  'last',
+])
+
+const isHamletReserved = name => name.startsWith('hamlet.')
+
+const PARTIAL_NAME_PATTERN = /^[A-Z][A-Z0-9]*(?:[._-][A-Z][A-Z0-9]*)*$/i
+const HELPER_NAME_PATTERN = /^[A-Z][A-Z0-9]*(?:[-_][A-Z][A-Z0-9]*)*$/i
+const BLOCKED_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
+
+it('plugin exports a function (factory)', () => {
+  assert.equal(typeof plugin, 'function', 'default export must be a function that returns { partials, helpers }')
+})
+
+it('plugin() returns an object with partials/helpers', () => {
+  const result = plugin({})
+  assert.equal(typeof result, 'object')
+  assert.ok(result.partials === undefined || typeof result.partials === 'object')
+  assert.ok(result.helpers === undefined || typeof result.helpers === 'object')
+})
+
+it('partials do not collide with reserved hamlet names', () => {
+  const { partials = {} } = plugin({})
+
+  for (const name of Object.keys(partials)) {
+    assert.ok(
+      !isHamletReserved(name),
+      `Partial "${name}" collides with a built-in hamlet partial`,
+    )
+  }
+})
+
+it('helpers do not collide with reserved hamlet helpers', () => {
+  const { helpers = {} } = plugin({})
+
+  for (const name of Object.keys(helpers)) {
+    assert.ok(
+      !RESERVED_HELPERS.has(name),
+      `Helper "${name}" collides with a built-in hamlet helper ("${name}" is reserved)`,
+    )
+  }
+})
+
+it('partial names match hamlet\'s naming policy (dots allowed)', () => {
+  const { partials = {} } = plugin({})
+
+  for (const name of Object.keys(partials)) {
+    assert.ok(
+      PARTIAL_NAME_PATTERN.test(name),
+      `Partial "${name}" does not match hamlet's allowed name pattern `
+      + '(letter start, letters/digits, optional ".", "-" or "_" separators)',
+    )
+  }
+})
+
+it('helper names match hamlet\'s naming policy (no dots allowed)', () => {
+  const { helpers = {} } = plugin({})
+
+  for (const name of Object.keys(helpers)) {
+    assert.ok(
+      HELPER_NAME_PATTERN.test(name),
+      `Helper "${name}" does not match hamlet's allowed name pattern, or contains a dot. `
+      + 'Helpers cannot be dot-namespaced: Handlebars parses "{{a.b}}" as a property path '
+      + 'on the data context, never as a helper name — a dotted helper registers without '
+      + 'error but is unreachable from any template (use camelCase or dashes instead).',
+    )
+  }
+})
+
+it('helpers are not nested objects (a common attempt at dot-namespacing)', () => {
+  const { helpers = {} } = plugin({})
+
+  for (const [name, value] of Object.entries(helpers)) {
+    assert.ok(
+      typeof value === 'function',
+      `Helper "${name}" is not a function (got ${typeof value}). If this is an attempt to `
+      + 'namespace helpers like { myPlugin: { shout: fn } }, note that Handlebars cannot '
+      + 'call nested helpers this way — "{{myPlugin.shout}}" looks up a property path, '
+      + 'not a nested helper, and would fail with "Missing helper" at render time.',
+    )
+  }
+})
+
+it('partial and helper names are not on hamlet\'s blocked list', () => {
+  const { partials = {}, helpers = {} } = plugin({})
+
+  for (const name of [...Object.keys(partials), ...Object.keys(helpers)]) {
+    assert.ok(
+      !BLOCKED_NAMES.has(name),
+      `"${name}" is a blocked name (${[...BLOCKED_NAMES].join(', ')}) and will always be rejected by hamlet`,
+    )
+  }
+})
+
+it('partials are valid strings and compile without syntax errors', () => {
+  const { partials = {} } = plugin({})
+
+  for (const [name, template] of Object.entries(partials)) {
+    assert.equal(typeof template, 'string', `Partial "${name}" must be a string`)
+    assert.doesNotThrow(
+      () => Handlebars.compile(template),
+      `Partial "${name}" has a Handlebars syntax error`,
+    )
+  }
+})
+
+it('helpers are functions', () => {
+  const { helpers = {} } = plugin({})
+
+  for (const [name, fn] of Object.entries(helpers)) {
+    assert.equal(typeof fn, 'function', `Helper "${name}" must be a function`)
+  }
+})
+
+it('plugin namespaces its exported names', () => {
+  const { namespace, partials = {}, helpers = {} } = plugin({})
+
+  assert.equal(
+    typeof namespace,
+    'string',
+    'Plugin must export a string "namespace"',
+  )
+
+  assert.match(
+    namespace,
+    /^[A-Z][A-Z0-9]*$/i,
+    'Namespace must start with a letter and contain only letters and digits',
+  )
+
+  for (const name of Object.keys(partials)) {
+    assert.ok(
+      name.startsWith(`${namespace}.`),
+      `Partial "${name}" must be prefixed with "${namespace}."`,
+    )
+  }
+
+  for (const name of Object.keys(helpers)) {
+    assert.ok(
+      new RegExp(`^${namespace}[A-Z]`).test(name),
+      `Helper "${name}" must be prefixed with "${namespace}" followed by an uppercase letter (e.g. "${namespace}Format")`,
+    )
+  }
+})