@formfeed/devkit 0.3.0 → 0.3.1

package/README.md

@@ -13,7 +13,7 @@ npm install @formfeed/devkit
 ```ts
 import { defaultData, diagnose, projectAround, readTemplate, renderLocal } from '@formfeed/devkit';
 
-// a folder with template.html, template.json, styles.css, data/*.json (see the project layout docs)
+// a folder with template.html, template.json, style.css, data/*.json (see the project layout docs)
 const project = projectAround('templates/invoice-de');
 const tpl = readTemplate(project, 'invoice-de');
 const { data } = defaultData(tpl); // data/default.json, or the first data set
@@ -22,7 +22,22 @@ console.log(diagnose(tpl, data)); // the editor's diagnostics: syntax errors, un
 const { document } = await renderLocal(project, tpl, data, { mode: 'print' }); // complete HTML, no browser
 ```
 
-Errors are `DevkitError` instances with a `code`, which the CLI maps to its exit codes.
+A folder can hold a Word or PowerPoint document (`template.docx` or `template.pptx`) instead of the
+HTML files; `readTemplate` returns it as `tpl.file` and `templateFileName(kind)` names the file for
+a kind. `diagnose` lists such a template's findings by part and paragraph, `renderOfficeLocal` fills
+it (`bytes`, `warnings`) and `officeSnapshot(bytes)` turns the filled file into readable XML for
+snapshot tests:
+
+```ts
+import { officeSnapshot, readTemplate, renderOfficeLocal } from '@formfeed/devkit';
+
+const offer = readTemplate(project, 'offer');
+const filled = await renderOfficeLocal(project, offer, { customer: { name: 'Olvarest GmbH' } });
+console.log(filled.warnings, officeSnapshot(filled.bytes));
+```
+
+`renderLocal` works on HTML templates only. Errors are `DevkitError` instances with a `code`, which
+the CLI maps to its exit codes.
 
 ## Documentation
 

package/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   diagnose: () => diagnose,
   findProject: () => findProject,
   generateTypes: () => generateTypes,
+  isIgnored: () => isIgnored,
   listLocalFiles: () => listLocalFiles,
   listTemplateSlugs: () => listTemplateSlugs,
   loadProject: () => loadProject,
@@ -55,6 +56,7 @@ __export(index_exports, {
   renderContext: () => renderContext,
   renderLocal: () => renderLocal,
   renderOfficeLocal: () => renderOfficeLocal,
+  renderedSettings: () => renderedSettings,
   sha256File: () => sha256File,
   sharedPartialNames: () => sharedPartialNames,
   sharedPartialPath: () => sharedPartialPath,
@@ -90,6 +92,32 @@ var defaultProjectConfig = {
   engine: "jinja2",
   ignore: ["**/drafts/**"]
 };
+function globRegExp(pattern) {
+  let glob = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!glob.includes("/")) glob = `**/${glob}`;
+  let source = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*" && glob[i + 1] === "*") {
+      const slash = glob[i + 2] === "/";
+      source += slash ? "(?:.*/)?" : ".*";
+      i += slash ? 2 : 1;
+    } else if (ch === "*") source += "[^/]*";
+    else if (ch === "?") source += "[^/]";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source.replace(/^\//, "")}$`);
+}
+function isIgnored(project, path, folder = false) {
+  const patterns = project.config.ignore ?? [];
+  if (!patterns.length) return false;
+  const rel = (0, import_node_path.relative)(project.root, (0, import_node_path.resolve)(project.root, path)).split(import_node_path.sep).join("/");
+  const candidates = folder ? [rel, `${rel}/`, `${rel}/x`] : [rel];
+  return patterns.some((p) => {
+    const re = globRegExp(p);
+    return candidates.some((c) => re.test(c));
+  });
+}
 function findProject(cwd = process.cwd()) {
   let dir = (0, import_node_path.resolve)(cwd);
   for (; ; ) {
@@ -565,6 +593,17 @@ async function renderLocal(project, tpl, data, options) {
     options.vendor ? { vendor: options.vendor } : {}
   );
 }
+function renderedSettings(rendered) {
+  const style = rendered.inlineCss ? `<style>${rendered.inlineCss}</style>` : "";
+  const part = (settings2, html) => settings2?.html ? { ...settings2, html: `${style}${html ?? ""}` } : settings2;
+  const { settings } = rendered;
+  return {
+    ...settings,
+    ...settings.header ? { header: part(settings.header, rendered.headerHtml) } : {},
+    ...settings.footer ? { footer: part(settings.footer, rendered.footerHtml) } : {},
+    ...settings.pdf?.metadata?.title !== void 0 ? { pdf: { ...settings.pdf, metadata: { ...settings.pdf.metadata, title: rendered.title ?? "" } } } : {}
+  };
+}
 function htmlKind(tpl) {
   if ((0, import_engine4.isOfficeKind)(tpl.meta.kind)) throw new DevkitError(`${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`, "validation");
   return tpl.meta.kind;
@@ -1223,6 +1262,7 @@ function generateTypes(sources, language, options = {}) {
   diagnose,
   findProject,
   generateTypes,
+  isIgnored,
   listLocalFiles,
   listTemplateSlugs,
   loadProject,
@@ -1246,6 +1286,7 @@ function generateTypes(sources, language, options = {}) {
   renderContext,
   renderLocal,
   renderOfficeLocal,
+  renderedSettings,
   sha256File,
   sharedPartialNames,
   sharedPartialPath,

package/index.js

@@ -9,7 +9,7 @@ var DevkitError = class extends Error {
 
 // packages/devkit/src/lib/project-config.ts
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 var defaultProjectConfig = {
   templatesDir: "templates",
   partialsDir: "partials",
@@ -17,6 +17,32 @@ var defaultProjectConfig = {
   engine: "jinja2",
   ignore: ["**/drafts/**"]
 };
+function globRegExp(pattern) {
+  let glob = pattern.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!glob.includes("/")) glob = `**/${glob}`;
+  let source = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*" && glob[i + 1] === "*") {
+      const slash = glob[i + 2] === "/";
+      source += slash ? "(?:.*/)?" : ".*";
+      i += slash ? 2 : 1;
+    } else if (ch === "*") source += "[^/]*";
+    else if (ch === "?") source += "[^/]";
+    else source += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${source.replace(/^\//, "")}$`);
+}
+function isIgnored(project, path, folder = false) {
+  const patterns = project.config.ignore ?? [];
+  if (!patterns.length) return false;
+  const rel = relative(project.root, resolve(project.root, path)).split(sep).join("/");
+  const candidates = folder ? [rel, `${rel}/`, `${rel}/x`] : [rel];
+  return patterns.some((p) => {
+    const re = globRegExp(p);
+    return candidates.some((c) => re.test(c));
+  });
+}
 function findProject(cwd = process.cwd()) {
   let dir = resolve(cwd);
   for (; ; ) {
@@ -509,6 +535,17 @@ async function renderLocal(project, tpl, data, options) {
     options.vendor ? { vendor: options.vendor } : {}
   );
 }
+function renderedSettings(rendered) {
+  const style = rendered.inlineCss ? `<style>${rendered.inlineCss}</style>` : "";
+  const part = (settings2, html) => settings2?.html ? { ...settings2, html: `${style}${html ?? ""}` } : settings2;
+  const { settings } = rendered;
+  return {
+    ...settings,
+    ...settings.header ? { header: part(settings.header, rendered.headerHtml) } : {},
+    ...settings.footer ? { footer: part(settings.footer, rendered.footerHtml) } : {},
+    ...settings.pdf?.metadata?.title !== void 0 ? { pdf: { ...settings.pdf, metadata: { ...settings.pdf.metadata, title: rendered.title ?? "" } } } : {}
+  };
+}
 function htmlKind(tpl) {
   if (isOfficeKind2(tpl.meta.kind)) throw new DevkitError(`${tpl.slug} is a ${tpl.meta.kind} template; fill it with renderOfficeLocal`, "validation");
   return tpl.meta.kind;
@@ -528,7 +565,7 @@ function previewDocument(tpl, rendered, mode, pagedScriptUrl) {
 // packages/devkit/src/lib/files.ts
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname3, join as join4, relative, resolve as resolve2, sep } from "node:path";
+import { dirname as dirname3, join as join4, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
 
 // packages/api-types/src/lib/assets.ts
 var SEGMENT = "[A-Za-z0-9][A-Za-z0-9._-]*";
@@ -570,7 +607,7 @@ function listLocalFiles(project) {
         continue;
       }
       if (!entry.isFile()) continue;
-      const name = relative(project.filesDir, path).split(sep).join("/");
+      const name = relative2(project.filesDir, path).split(sep2).join("/");
       const size = statSync2(path).size;
       const contentType = contentTypeFor(name);
       const reason = !isAssetName(name) ? "the name has characters a library name cannot have (letters, digits, dot, dash, underscore)" : !contentType ? "not an image or a PDF" : size === 0 ? "empty" : size > ASSET_MAX_BYTES ? `larger than ${ASSET_MAX_BYTES / 1024 / 1024} MB` : null;
@@ -589,7 +626,7 @@ function listLocalFiles(project) {
 function localFilePath(project, name) {
   if (!isAssetName(name)) throw new DevkitError(`"${name}" is not a library file name`);
   const path = resolve2(project.filesDir, ...name.split("/"));
-  if (!path.startsWith(resolve2(project.filesDir) + sep)) throw new DevkitError(`"${name}" is not inside the files folder`);
+  if (!path.startsWith(resolve2(project.filesDir) + sep2)) throw new DevkitError(`"${name}" is not inside the files folder`);
   return path;
 }
 function writeLocalFile(project, name, bytes) {
@@ -1166,6 +1203,7 @@ export {
   diagnose,
   findProject,
   generateTypes,
+  isIgnored,
   listLocalFiles,
   listTemplateSlugs,
   loadProject,
@@ -1189,6 +1227,7 @@ export {
   renderContext,
   renderLocal,
   renderOfficeLocal,
+  renderedSettings,
   sha256File,
   sharedPartialNames,
   sharedPartialPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/devkit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Formfeed template folders, project config and local rendering, shared by the CLI and @formfeed/testing.",
   "license": "MIT",
   "type": "module",
@@ -30,8 +30,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@formfeed/engine": "0.3.0",
-    "@formfeed/sdk": "0.3.0"
+    "@formfeed/engine": "0.3.1",
+    "@formfeed/sdk": "0.3.1"
   },
   "keywords": [
     "formfeed",

package/types/index.d.cts

@@ -1,12 +1,12 @@
 export { DevkitError } from './lib/errors.cjs';
-export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.cjs';
+export { defaultProjectConfig, findProject, isIgnored, loadProject, projectAround, writeProjectConfig } from './lib/project-config.cjs';
 export type { Project, ProjectConfig } from './lib/project-config.cjs';
 export { contentHash, defaultData, listTemplateSlugs, officeVersionPayload, partialContentHash, partialResolver, readState, readTemplate, recordSharedPartial, recordSync, sharedPartialNames, sharedPartialPath, templateDir, templateFileName, titleFromSlug, versionPayload, writePartials, writeState, writeTemplate, } from './lib/project.cjs';
 export type { LocalOfficeFile, LocalTemplate, ProjectState, SharedPartialState, TemplateMeta, TemplateState } from './lib/project.cjs';
 export { brandFromJson, brandPath, readBrand, writeBrand } from './lib/brand.cjs';
 export { collectPartials } from './lib/partials.cjs';
 export type { CollectedPartials } from './lib/partials.cjs';
-export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal } from './lib/local-render.cjs';
+export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal, renderedSettings } from './lib/local-render.cjs';
 export type { LocalDiagnostic, OfficeLocalOptions } from './lib/local-render.cjs';
 export { contentTypeFor, listLocalFiles, localFilePath, sha256File, writeLocalFile } from './lib/files.cjs';
 export type { LocalFile, LocalFileListing } from './lib/files.cjs';

package/types/index.d.ts

@@ -1,12 +1,12 @@
 export { DevkitError } from './lib/errors.js';
-export { defaultProjectConfig, findProject, loadProject, projectAround, writeProjectConfig } from './lib/project-config.js';
+export { defaultProjectConfig, findProject, isIgnored, loadProject, projectAround, writeProjectConfig } from './lib/project-config.js';
 export type { Project, ProjectConfig } from './lib/project-config.js';
 export { contentHash, defaultData, listTemplateSlugs, officeVersionPayload, partialContentHash, partialResolver, readState, readTemplate, recordSharedPartial, recordSync, sharedPartialNames, sharedPartialPath, templateDir, templateFileName, titleFromSlug, versionPayload, writePartials, writeState, writeTemplate, } from './lib/project.js';
 export type { LocalOfficeFile, LocalTemplate, ProjectState, SharedPartialState, TemplateMeta, TemplateState } from './lib/project.js';
 export { brandFromJson, brandPath, readBrand, writeBrand } from './lib/brand.js';
 export { collectPartials } from './lib/partials.js';
 export type { CollectedPartials } from './lib/partials.js';
-export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal } from './lib/local-render.js';
+export { diagnose, officeSnapshot, prettyXml, previewDocument, renderContext, renderLocal, renderOfficeLocal, renderedSettings } from './lib/local-render.js';
 export type { LocalDiagnostic, OfficeLocalOptions } from './lib/local-render.js';
 export { contentTypeFor, listLocalFiles, localFilePath, sha256File, writeLocalFile } from './lib/files.js';
 export type { LocalFile, LocalFileListing } from './lib/files.js';

package/types/lib/local-render.d.cts

@@ -47,5 +47,12 @@ export interface LocalRenderOptions {
 }
 /** Assembles the complete document with the shared engine; no browser involved. */
 export declare function renderLocal(project: Project, tpl: LocalTemplate, data: unknown, options: LocalRenderOptions): Promise<RenderedDocument>;
+/**
+ * The settings to send with a locally rendered document as a raw-HTML render. The API uses
+ * `header.html`, `footer.html` and the PDF title of such a render verbatim, so they must be the
+ * filled parts, not the template's source; the inline CSS travels with them, because Chromium loads
+ * no stylesheet in its header and footer templates.
+ */
+export declare function renderedSettings(rendered: RenderedDocument): Record<string, unknown>;
 /** Wraps a preview render for the screen the way the editor does. */
 export declare function previewDocument(tpl: LocalTemplate, rendered: RenderedDocument, mode: 'flow' | 'paged', pagedScriptUrl: string): string;

package/types/lib/local-render.d.ts

@@ -47,5 +47,12 @@ export interface LocalRenderOptions {
 }
 /** Assembles the complete document with the shared engine; no browser involved. */
 export declare function renderLocal(project: Project, tpl: LocalTemplate, data: unknown, options: LocalRenderOptions): Promise<RenderedDocument>;
+/**
+ * The settings to send with a locally rendered document as a raw-HTML render. The API uses
+ * `header.html`, `footer.html` and the PDF title of such a render verbatim, so they must be the
+ * filled parts, not the template's source; the inline CSS travels with them, because Chromium loads
+ * no stylesheet in its header and footer templates.
+ */
+export declare function renderedSettings(rendered: RenderedDocument): Record<string, unknown>;
 /** Wraps a preview render for the screen the way the editor does. */
 export declare function previewDocument(tpl: LocalTemplate, rendered: RenderedDocument, mode: 'flow' | 'paged', pagedScriptUrl: string): string;

package/types/lib/project-config.d.cts

@@ -33,6 +33,12 @@ export interface Project {
     filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
+/**
+ * Whether a path of the project matches one of `ignore`. The path is taken relative to the project
+ * root; a folder also matches as `<folder>/` and through the files in it, so `**\/drafts/**` and
+ * `templates/wip-*` both catch `templates/wip-offer`.
+ */
+export declare function isIgnored(project: Project, path: string, folder?: boolean): boolean;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */
 export declare function findProject(cwd?: string): Project | null;
 export declare function loadProject(configPath: string): Project;

package/types/lib/project-config.d.ts

@@ -33,6 +33,12 @@ export interface Project {
     filesDir: string;
 }
 export declare const defaultProjectConfig: ProjectConfig;
+/**
+ * Whether a path of the project matches one of `ignore`. The path is taken relative to the project
+ * root; a folder also matches as `<folder>/` and through the files in it, so `**\/drafts/**` and
+ * `templates/wip-*` both catch `templates/wip-offer`.
+ */
+export declare function isIgnored(project: Project, path: string, folder?: boolean): boolean;
 /** Walks up from `cwd` to the nearest `formfeed.json`. */
 export declare function findProject(cwd?: string): Project | null;
 export declare function loadProject(configPath: string): Project;