hamlet-plugin-template 1.0.0 → 1.1.1

package/README.md

@@ -5,9 +5,11 @@ 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.
+2. Add your Handlebars partials as `.hbs` (or `.xml`, `.handlebars`) files inside `src/`.
+3. Implement helpers and set the namespace in `index.js`.
+4. Run `npm run build:partials` to generate `lib/partials.js` from your source files.
+5. Run the tests.
+6. Publish to npm.
 
 ## End-user installation
 
@@ -17,28 +19,46 @@ npm install hamlet-plugin-template
 
 ```js
 // hamlet.config.js
-import myPlugin from 'hamlet-plugin-template'
+import Sample from 'hamlet-plugin-template'
 
 export default {
   plugins: [
-    myPlugin(),
+    Sample(),
     // or with options:
-    myPlugin({ myOption: true }),
+    Sample({ 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.
+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.
+
+## Project structure
+
+```
+├── src/
+│   ├── card.hbs        ← your partial source files
+│   └── hello.hbs
+├── lib/
+│   └── partials.js     ← auto-generated, do not edit
+├── scripts/
+│   └── build-partials.js
+├── index.js
+└── package.json
+```
+
+Source files in `src/` are compiled into `lib/partials.js` by `npm run build:partials`. This script runs automatically before publishing via the `prepublishOnly` hook.
 
 ## 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
+import { partials } from './lib/partials.js'
+
 export default function hamletPlugin(options = {}) {
   return {
-    namespace: 'MyPlugin',
-    partials: {},
+    namespace: 'Sample',
+    partials,
     helpers: {},
   }
 }
@@ -48,75 +68,90 @@ export default function hamletPlugin(options = {}) {
 
 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.
+- It must start with a letter.
+- It may contain only letters and digits.
+- It is used to prefix all exported partials and helpers automatically — you only use short names inside the plugin.
+- The namespace `hamlet` is reserved and cannot be used.
 
 ### partials
 
-An object containing Handlebars partials.
+An object of Handlebars partials keyed by **short names** (without the namespace prefix). Hamlet registers them as `<namespace>.<name>` automatically.
 
-Every partial name must be prefixed with `<namespace>.`.
+Add `.hbs`, `.xml`, or `.handlebars` files to `src/` and run `npm run build:partials` to populate `lib/partials.js`. The file name becomes the partial key.
 
-Example:
+Example — `src/card.hbs`:
 
-```js
-export default function hamletPlugin(options = {}) {
-  return {
-    namespace: 'MyPlugin',
-    partials: {
-      'MyPlugin.card': '<div>...</div>',
-    }
-  }
-}
+```hbs
+<div{{#if className}} class="{{className}}"{{/if}}>
+  {{#if title}}<h2>{{title}}</h2>{{/if}}
+  {{#if description}}<p>{{description}}</p>{{/if}}
+</div>
 ```
 
-### helpers
+This becomes `partials.card`, registered by Hamlet as `Sample.card`:
 
-An object containing Handlebars helpers.
+```hbs
+{{> Sample.card title="Hello"}}
+```
+
+### helpers
 
-Every helper name must be prefixed with the namespace followed by an uppercase letter.
+An object of Handlebars helpers keyed by **short camelCase names** (without the namespace prefix). Hamlet registers them as `<namespace><Name>` automatically.
 
 Example:
 
 ```js
 export default function hamletPlugin(options = {}) {
   return {
-    namespace: 'MyPlugin',
+    namespace: 'Sample',
     helpers: {
-      MyPluginFormat: value => value.toUpperCase(),
-    }
+      shout: value => value.toUpperCase(),
+    },
   }
 }
 ```
 
-Helper names cannot contain dots because Handlebars interprets them as property paths rather than helper names.
+This registers the helper as `SampleShout`, usable in templates as:
+
+```hbs
+{{SampleShout "hello"}}
+```
+
+Helper names cannot contain dots because Handlebars interprets them as property paths.
 
 ## 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.
+If a plugin attempts to register a partial or helper whose name already exists (whether built-in to Hamlet, from another plugin, or from the user's project), the duplicate is silently skipped 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:
+Plugin partials can freely use Hamlet's built-in helpers and partials:
 
 ```hbs
 {{concat "Hello, " name}}
 
 {{#switch value}}
-  ...
+  {{#case "post"}}...{{/case}}
+  {{#default}}...{{/default}}
 {{/switch}}
 
 {{> hamlet.snippet}}
 ```
 
-## Tests
+## Scripts
 
-Before publishing:
+| Script | Description |
+| ------ | ----------- |
+| `npm run build:partials` | Generates `lib/partials.js` from files in `src/` |
+| `npm test` | Runs the test suite |
+| `npm run lint` | Lints the project |
+| `npm run lint:fix` | Lints and auto-fixes |
+
+`build:partials` also runs automatically via `prepublishOnly` before every `npm publish`.
+
+## Tests
 
 ```bash
 npm install
@@ -125,20 +160,20 @@ 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.
+- The plugin exports a valid factory function.
+- The returned object follows Hamlet's plugin contract.
+- A valid, non-reserved namespace is exported.
+- Partial and helper names are short (no namespace prefix) and follow Hamlet's naming rules.
+- No computed full name collides with Hamlet's reserved partials or helpers.
+- Partials are strings and compile without Handlebars syntax errors.
+- Helpers are functions (not nested objects).
+- No name is on Hamlet's blocked list (`__proto__`, `constructor`, `prototype`).
 
 Feel free to extend the tests with plugin-specific behavior or option validation.
 
 ## Linting
 
-This template uses the same ESLint configuration as Hamlet itself.
+This template uses the same ESLint configuration as Hamlet itself (`@antfu/eslint-config`).
 
 ```bash
 npm run lint

package/index.js

@@ -1,39 +1,31 @@
+import { partials } from './lib/partials.js'
+
 /**
  * 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").
+ *   - namespace: A unique plugin namespace. Hamlet uses it to
+ *     prefix all exported partials and helpers automatically,
+ *     so you only need to define short names here.
  *
- *   - 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.
+ *   - partials: An object of Handlebars partials. Use short names
+ *     without the namespace prefix (e.g. "card", not "Sample.card").
+ *     Hamlet registers them as "<namespace>.<name>" automatically.
+ *     Usage in templates: {{> Sample.card}}
  *
- * 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.
+ *   - helpers: An object of Handlebars helpers. Use short camelCase
+ *     names without the namespace prefix (e.g. "format", not "SampleFormat").
+ *     Hamlet registers them as "<namespace><Name>" automatically.
+ *     Usage in templates: {{SampleFormat value}}
  *
- * @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
-
+export default function hamletPlugin() {
   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(),
-    },
+    namespace: 'Sample',
+    partials,
+    helpers: {},
   }
 }

package/lib/partials.js

@@ -0,0 +1,5 @@
+// This file is auto-generated. Do not edit it manually.
+export const partials = {
+  "hello": "<p>Hello World!</p>\n",
+  "card": "<div{{#if className}} class=\"{{className}}\"{{/if}}>\r\n  {{#if title}}<h2>{{title}}</h2>{{/if}}\r\n  {{#if description}}<p>{{description}}</p>{{/if}}\r\n</div>\n"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hamlet-plugin-template",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A plugin template for hamlet",
   "license": "MIT",
   "keywords": [
@@ -11,16 +11,22 @@
   "exports": {
     ".": "./index.js"
   },
-  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib"
+  ],
   "scripts": {
+    "build:partials": "node ./scripts/build-partials.js",
+    "prepublishOnly": "npm run build:partials",
     "test": "vitest run",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.1.0",
-    "eslint": "^10.6.0",
+    "eslint": "^10.7.0",
+    "glob": "^13.0.0",
     "handlebars": "^4.7.9",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   }
 }

package/.editorconfig

@@ -1,12 +0,0 @@
-# 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/eslint.config.js

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

package/test/Plugin.test.js

@@ -1,167 +0,0 @@
-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")`,
-    )
-  }
-})