@dsplay/template-manifest 1.0.0

package/README.md

@@ -0,0 +1,87 @@
+# @dsplay/template-manifest
+
+A build-time scanner for [DSPLAY HTML templates](https://developers.dsplay.tv/docs/html-templates) ([DSPLAY - Digital Signage](https://dsplay.tv/)).
+
+It statically scans a template's source for its `dsplay_template` variable reads and captures its `dsplay-data.js` mock as example data, producing two JSON files a template ships inside its `template.zip`:
+
+- **`template-variables.json`** — the detected variables, e.g.:
+  ```json
+  {
+    "variables": [
+      { "key": "title", "type": "string", "default": "Default Value" },
+      { "key": "expanded", "type": "boolean", "default": true },
+      { "key": "logo", "type": "string", "subtypeGuess": "image" }
+    ]
+  }
+  ```
+- **`template-example-data.json`** — the `{ config, media, template }` example values captured from `dsplay-data.js`.
+
+The DSPLAY CMS reads these files to auto-detect a template's variables and seed default values for an in-browser preview, instead of requiring the variables to be registered by hand.
+
+## What it detects
+
+- `tval` / `tbval` / `tival` / `tfval` and `useTemplateVal` / `useTemplateBoolVal` / `useTemplateIntVal` / `useTemplateFloatVal` calls, imported from `@dsplay/template-utils` / `@dsplay/react-template-utils` **or** called off the `dsplayTemplateUtils` global UMD alias (`u.tval(...)`) used by bundler-less templates.
+- Direct property access or destructuring off the template object, with no helper call at all — `template.title`, `useTemplate().title`, `const { title } = template`, `u.template.title` — including type promotion when wrapped in `parseInt`/`parseFloat`.
+- A best-effort `default` value, resolved through local consts and chained `tval(...)`-as-default calls using each reference's own lexical scope (never a global cross-file lookup, since two files can legitimately use the same key with different local defaults). Defaults that are computed at runtime (e.g. `list.join(',')`) are left unresolved rather than guessed.
+- A `subtypeGuess` (`image`, `video`, `color`) from the variable's key name, for `string`-typed variables — always a suggestion, never authoritative.
+
+## Installation
+
+```sh
+npm install --save-dev @dsplay/template-manifest
+```
+
+## Usage
+
+### Vite plugin
+
+For templates built with Vite:
+
+```js
+// vite.config.js
+import templateManifest from '@dsplay/template-manifest/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    // ...
+    templateManifest(),
+  ],
+});
+```
+
+It writes `template-variables.json` and `template-example-data.json` into the build output directory on `closeBundle`, so they end up inside `template.zip` alongside `index.html` and the rest of the build.
+
+By default it scans `src` and reads `public/dsplay-data.js` (both resolved relative to the Vite root). Override with:
+
+```js
+templateManifest({ srcDir: 'source', dsplayDataPath: 'public/mock-data.js' });
+```
+
+### CLI
+
+For templates with no bundler (e.g. the vanilla-js and jQuery boilerplates) or on an older build stack, run the `dsplay-scan-template` CLI from your packaging script (e.g. `pack.sh`):
+
+```sh
+npx dsplay-scan-template --src scripts --dsplay-data scripts/dsplay-data.js --out .
+```
+
+| Flag             | Default                 | Description                                  |
+|------------------|--------------------------|-----------------------------------------------|
+| `--src`          | `src`                    | Directory to scan recursively for `.js`/`.jsx` files |
+| `--dsplay-data`  | `public/dsplay-data.js`  | Path to the template's `dsplay-data.js` mock  |
+| `--out`          | `build`                  | Directory to write the two JSON files into    |
+
+### Programmatic API
+
+```js
+import { scanTemplateVariables, scanExampleData, generateManifest } from '@dsplay/template-manifest';
+
+const variables = scanTemplateVariables('src'); // [{key, type, default?, subtypeGuess?}]
+const example = scanExampleData('public/dsplay-data.js'); // {config?, media?, template?}
+
+generateManifest({ srcDir: 'src', dsplayDataPath: 'public/dsplay-data.js', outDir: 'build' });
+```
+
+## Why a separate package
+
+This scanner depends on `@babel/parser`/`@babel/traverse`, which are only needed at build time by templates that opt into this tool. Bundling it inside `@dsplay/template-utils` would have forced those dependencies onto every consumer of that package — including every React template via `@dsplay/react-template-utils` — even though the vast majority never use the scanner.

package/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { generateManifest } from './core.js';
+
+function parseArgs(argv) {
+  const options = { src: 'src', dsplayData: 'public/dsplay-data.js', out: 'build' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--src') options.src = argv[(i += 1)];
+    else if (arg === '--dsplay-data') options.dsplayData = argv[(i += 1)];
+    else if (arg === '--out') options.out = argv[(i += 1)];
+    else {
+      process.stderr.write(`Unknown argument: ${arg}\n`);
+      process.exit(1);
+    }
+  }
+  return options;
+}
+
+const { src, dsplayData, out } = parseArgs(process.argv.slice(2));
+const cwd = process.cwd();
+
+const { variables } = generateManifest({
+  srcDir: path.resolve(cwd, src),
+  dsplayDataPath: path.resolve(cwd, dsplayData),
+  outDir: path.resolve(cwd, out),
+});
+
+process.stdout.write(`dsplay-scan-template: found ${variables.length} template variable(s), wrote manifest to ${path.resolve(cwd, out)}\n`);

package/core.js

@@ -0,0 +1,352 @@
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+
+const traverse = traverseModule.default || traverseModule;
+
+const HOOK_TYPES = {
+  tval: 'string',
+  useTemplateVal: 'string',
+  tbval: 'boolean',
+  useTemplateBoolVal: 'boolean',
+  tival: 'integer',
+  useTemplateIntVal: 'integer',
+  tfval: 'float',
+  useTemplateFloatVal: 'float',
+};
+
+// The global UMD build of @dsplay/template-utils exposes itself under this fixed name
+// (see webpack.config.js's output.library) for templates with no bundler/import system at
+// all (plain <script> tags, e.g. the vanilla-js and jQuery boilerplates).
+const GLOBAL_UTILS_NAME = 'dsplayTemplateUtils';
+
+const PACKAGE_NAMES = ['@dsplay/template-utils', '@dsplay/react-template-utils'];
+
+const SOURCE_EXTENSIONS = ['.js', '.jsx'];
+
+const IMAGE_NAME_HINT = /logo|image|background|bg[_-]|[_-]bg|icon|photo|picture|banner|thumbnail/i;
+const VIDEO_NAME_HINT = /video/i;
+const COLOR_NAME_HINT = /colou?r/i;
+
+function guessSubtype(key, type) {
+  if (type !== 'string') return undefined;
+  if (VIDEO_NAME_HINT.test(key)) return 'video';
+  if (IMAGE_NAME_HINT.test(key)) return 'image';
+  if (COLOR_NAME_HINT.test(key)) return 'color';
+  return undefined;
+}
+
+function walkSourceFiles(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkSourceFiles(full, out);
+    } else if (SOURCE_EXTENSIONS.includes(path.extname(entry.name))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function parseFile(code) {
+  return parse(code, {
+    sourceType: 'unambiguous',
+    plugins: ['jsx'],
+  });
+}
+
+// Evaluates a "data literal" AST node (string/number/boolean/null/array/object of the same)
+// into a plain JS value. Anything referencing identifiers/runtime globals is left undefined.
+function evalLiteral(node) {
+  if (!node) return undefined;
+  switch (node.type) {
+    case 'StringLiteral':
+    case 'NumericLiteral':
+    case 'BooleanLiteral':
+      return node.value;
+    case 'NullLiteral':
+      return null;
+    case 'UnaryExpression':
+      if (node.operator === '-' && node.argument.type === 'NumericLiteral') {
+        return -node.argument.value;
+      }
+      return undefined;
+    case 'ArrayExpression': {
+      const arr = [];
+      for (const el of node.elements) {
+        if (el == null) { arr.push(null); continue; }
+        const v = evalLiteral(el);
+        if (v === undefined && el.type !== 'NullLiteral') return undefined;
+        arr.push(v);
+      }
+      return arr;
+    }
+    case 'ObjectExpression': {
+      const obj = {};
+      for (const prop of node.properties) {
+        if (prop.type !== 'ObjectProperty' || prop.computed) continue;
+        const propKey = prop.key.type === 'Identifier' ? prop.key.name : prop.key.value;
+        const v = evalLiteral(prop.value);
+        if (v === undefined && prop.value.type !== 'NullLiteral') continue;
+        obj[propKey] = v;
+      }
+      return obj;
+    }
+    default:
+      return undefined;
+  }
+}
+
+function literalType(value) {
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'float';
+  if (typeof value === 'string') return 'string';
+  return undefined;
+}
+
+// True when `node` is an Identifier that (directly, or via one or more local `var x = ...`
+// indirections) refers to the dsplayTemplateUtils UMD global - or `window.dsplayTemplateUtils`.
+function resolvesToGlobalUtilsAlias(node, scope, seen = new Set()) {
+  if (!node) return false;
+  if (node.type === 'Identifier') {
+    if (node.name === GLOBAL_UTILS_NAME) return true;
+    if (seen.has(node.name)) return false;
+    const binding = scope.getBinding(node.name);
+    const init = binding?.path?.isVariableDeclarator?.() ? binding.path.node.init : undefined;
+    return init ? resolvesToGlobalUtilsAlias(init, scope, new Set(seen).add(node.name)) : false;
+  }
+  if (node.type === 'MemberExpression' && !node.computed && node.property.type === 'Identifier') {
+    return node.property.name === GLOBAL_UTILS_NAME;
+  }
+  return false;
+}
+
+// Returns the tval/tbval/tival/tfval "kind" a call's callee resolves to, whether reached via
+// an ES import binding (`tval(...)`) or a member access off the global UMD alias (`u.tval(...)`).
+function getHookType(callee, scope) {
+  if (callee.type === 'Identifier') {
+    const binding = scope.getBinding(callee.name);
+    const importedName = binding?.path?.isImportSpecifier?.() ? binding.path.node.imported.name : undefined;
+    return importedName ? HOOK_TYPES[importedName] : undefined;
+  }
+  if (callee.type === 'MemberExpression' && !callee.computed && callee.property.type === 'Identifier') {
+    if (!resolvesToGlobalUtilsAlias(callee.object, scope)) return undefined;
+    return HOOK_TYPES[callee.property.name];
+  }
+  return undefined;
+}
+
+// True when `node` is an expression representing "the template variables object" itself -
+// covers the ES default export, the React `useTemplate()` hook result, and the global UMD
+// alias's `.template` property (plus one level of local variable indirection for each).
+function isTemplateAccessBase(node, scope, seen = new Set()) {
+  if (!node) return false;
+
+  if (node.type === 'MemberExpression' && !node.computed && node.property.type === 'Identifier'
+      && node.property.name === 'template') {
+    return resolvesToGlobalUtilsAlias(node.object, scope);
+  }
+
+  if (node.type === 'CallExpression' && node.callee.type === 'Identifier') {
+    const binding = scope.getBinding(node.callee.name);
+    const importedName = binding?.path?.isImportSpecifier?.() ? binding.path.node.imported.name : undefined;
+    return importedName === 'useTemplate';
+  }
+
+  if (node.type === 'Identifier') {
+    if (seen.has(node.name)) return false;
+    const binding = scope.getBinding(node.name);
+    if (!binding) return false;
+    if (binding.path.isImportDefaultSpecifier?.()) {
+      const importDecl = binding.path.parentPath;
+      return PACKAGE_NAMES.includes(importDecl.node.source.value);
+    }
+    const init = binding.path.isVariableDeclarator?.() ? binding.path.node.init : undefined;
+    return init ? isTemplateAccessBase(init, scope, new Set(seen).add(node.name)) : false;
+  }
+
+  return false;
+}
+
+// Descriptor for a var's default arg, resolved as far as static analysis allows by walking
+// straight through the AST (local const references, chained tval(...)-as-default calls) using
+// each node's own lexical scope — never through a global cross-file key lookup, since two
+// different call sites can legitimately use the same key with different local defaults.
+function describeDefault(node, scope, seen = new Set()) {
+  if (!node) return { kind: 'none' };
+
+  const literalValue = evalLiteral(node);
+  if (literalValue !== undefined || node.type === 'NullLiteral') {
+    return { kind: 'literal', value: literalValue };
+  }
+
+  if (node.type === 'CallExpression' && getHookType(node.callee, scope)) {
+    // e.g. useTemplateVal('outer', useTemplateVal('inner')) - the outer's default is
+    // whatever the inner reference itself resolves to as ITS OWN default.
+    return describeDefault(node.arguments[1], scope, seen);
+  }
+
+  if (node.type === 'Identifier') {
+    if (seen.has(node.name)) return { kind: 'unresolved' };
+    const binding = scope.getBinding(node.name);
+    const init = binding?.path?.isVariableDeclarator?.() ? binding.path.node.init : undefined;
+    if (init) return describeDefault(init, scope, new Set(seen).add(node.name));
+    return { kind: 'unresolved' };
+  }
+
+  return { kind: 'unresolved' };
+}
+
+function addVariable(table, key, type, { default: defaultValue, hasDefault = false } = {}) {
+  const existing = table.get(key);
+  if (existing) return existing;
+
+  const variable = { key, type };
+  if (hasDefault) variable.default = defaultValue;
+  const subtype = guessSubtype(key, type);
+  if (subtype) variable.subtypeGuess = subtype;
+  table.set(key, variable);
+  return variable;
+}
+
+function scanFile(code, table) {
+  let ast;
+  try {
+    ast = parseFile(code);
+  } catch {
+    return;
+  }
+
+  traverse(ast, {
+    // tval('key', default) / useTemplateVal('key', default) / u.tval('key', default)
+    CallExpression(nodePath) {
+      const { callee, arguments: args } = nodePath.node;
+      const type = getHookType(callee, nodePath.scope);
+      if (!type || args[0]?.type !== 'StringLiteral') return;
+
+      const key = args[0].value;
+      const defaultDescriptor = describeDefault(args[1], nodePath.scope);
+      addVariable(table, key, type, {
+        default: defaultDescriptor.kind === 'literal' ? defaultDescriptor.value : undefined,
+        hasDefault: defaultDescriptor.kind === 'literal',
+      });
+    },
+
+    // template.key / useTemplate().key / u.template.key (direct read, no helper call)
+    MemberExpression(nodePath) {
+      const node = nodePath.node;
+      if (node.computed || node.property.type !== 'Identifier') return;
+      if (!isTemplateAccessBase(node.object, nodePath.scope)) return;
+
+      const key = node.property.name;
+      let type = 'string';
+      const parent = nodePath.parentPath;
+      if (parent?.isCallExpression() && parent.node.arguments[0] === node
+          && parent.node.callee.type === 'Identifier') {
+        if (parent.node.callee.name === 'parseInt') type = 'integer';
+        else if (parent.node.callee.name === 'parseFloat') type = 'float';
+      }
+      addVariable(table, key, type);
+    },
+
+    // const { key, other = 'default' } = template / useTemplate() / u.template
+    VariableDeclarator(nodePath) {
+      const node = nodePath.node;
+      if (node.id.type !== 'ObjectPattern' || !isTemplateAccessBase(node.init, nodePath.scope)) return;
+
+      for (const prop of node.id.properties) {
+        if (prop.type !== 'ObjectProperty' || prop.computed) continue;
+        const key = prop.key.type === 'Identifier' ? prop.key.name : prop.key.value;
+
+        if (prop.value.type === 'AssignmentPattern') {
+          const literalValue = evalLiteral(prop.value.right);
+          const type = literalType(literalValue) || 'string';
+          addVariable(table, key, type, { default: literalValue, hasDefault: literalValue !== undefined });
+        } else {
+          addVariable(table, key, 'string');
+        }
+      }
+    },
+  });
+}
+
+/**
+ * Statically scans a template's source tree for DSPLAY template-variable reads
+ * (`tval`/`useTemplateVal`-style calls, `useTemplate()`/`.template` destructuring or direct
+ * property access, in both the ES-import and global-UMD-alias worlds) and returns the
+ * discovered `{key, type, default?, subtypeGuess?}` entries.
+ * @param {string} srcDir - Directory to scan recursively for .js/.jsx files.
+ * @returns {Array<{key: string, type: 'string'|'boolean'|'integer'|'float', default?: *, subtypeGuess?: string}>}
+ */
+export function scanTemplateVariables(srcDir) {
+  const table = new Map();
+  for (const file of walkSourceFiles(srcDir)) {
+    scanFile(readFileSync(file, 'utf-8'), table);
+  }
+  return [...table.values()];
+}
+
+function extractDsplayDataGlobal(ast, globalName) {
+  let result;
+  traverse(ast, {
+    VariableDeclarator(nodePath) {
+      if (nodePath.node.id.type === 'Identifier' && nodePath.node.id.name === globalName) {
+        result = evalLiteral(nodePath.node.init);
+      }
+    },
+  });
+  return result;
+}
+
+/**
+ * Captures a template's `dsplay-data.js` mock (`dsplay_config`/`dsplay_media`/`dsplay_template`)
+ * as plain example data. Fields that aren't statically-evaluable literals (e.g. an `orientation`
+ * computed from `window.innerWidth`) are silently dropped rather than poisoning the whole object.
+ * @param {string} dsplayDataPath - Path to the template's dsplay-data.js file.
+ * @returns {{config?: object, media?: object, template?: object}}
+ */
+export function scanExampleData(dsplayDataPath) {
+  if (!existsSync(dsplayDataPath)) return {};
+
+  const code = readFileSync(dsplayDataPath, 'utf-8');
+  let ast;
+  try {
+    ast = parse(code, { sourceType: 'script' });
+  } catch {
+    return {};
+  }
+
+  const example = {};
+  const config = extractDsplayDataGlobal(ast, 'dsplay_config');
+  const media = extractDsplayDataGlobal(ast, 'dsplay_media');
+  const template = extractDsplayDataGlobal(ast, 'dsplay_template');
+  if (config) example.config = config;
+  if (media) example.media = media;
+  if (template) example.template = template;
+  return example;
+}
+
+/**
+ * Runs both scans and writes `template-variables.json` + `template-example-data.json` into
+ * `outDir` (creating it if needed) - the pair of files a template's build should ship inside
+ * its `template.zip` so the CMS can auto-detect variables and seed default preview values.
+ * @param {{srcDir: string, dsplayDataPath: string, outDir: string}} options
+ */
+export function generateManifest({ srcDir, dsplayDataPath, outDir }) {
+  const variables = scanTemplateVariables(srcDir);
+  const example = scanExampleData(dsplayDataPath);
+
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(
+    path.join(outDir, 'template-variables.json'),
+    `${JSON.stringify({ variables }, null, 2)}\n`,
+  );
+  writeFileSync(
+    path.join(outDir, 'template-example-data.json'),
+    `${JSON.stringify(example, null, 2)}\n`,
+  );
+
+  return { variables, example };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@dsplay/template-manifest",
+  "version": "1.0.0",
+  "description": "Statically scans a DSPLAY HTML template's source for its dsplay_template variables and captures its dsplay-data.js as example preview data, producing template-variables.json + template-example-data.json for the CMS to auto-detect variables and seed default preview values.",
+  "type": "module",
+  "main": "./core.js",
+  "exports": {
+    ".": "./core.js",
+    "./vite-plugin": "./vite-plugin.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsplay-scan-template": "cli.js"
+  },
+  "files": [
+    "core.js",
+    "vite-plugin.js",
+    "cli.js"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.29.7",
+    "@babel/traverse": "^7.29.7"
+  }
+}

package/vite-plugin.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { generateManifest } from './core.js';
+
+/**
+ * Vite plugin that generates `template-variables.json` + `template-example-data.json` into
+ * the build output directory once the build finishes - see `generateManifest` for details.
+ * @param {{srcDir?: string, dsplayDataPath?: string}} [options] - Paths relative to the
+ * resolved Vite root. Defaults match this ecosystem's convention: `src` and `public/dsplay-data.js`.
+ */
+export default function templateManifestPlugin(options = {}) {
+  const { srcDir = 'src', dsplayDataPath = 'public/dsplay-data.js' } = options;
+  let config;
+  let done = false;
+
+  return {
+    name: 'dsplay-template-manifest',
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    closeBundle() {
+      if (done) return;
+      done = true;
+
+      generateManifest({
+        srcDir: path.resolve(config.root, srcDir),
+        dsplayDataPath: path.resolve(config.root, dsplayDataPath),
+        outDir: path.resolve(config.root, config.build.outDir),
+      });
+    },
+  };
+}