@formfeed/devkit 0.3.5 → 0.3.7

package/README.md

@@ -1,6 +1,6 @@
 # @formfeed/devkit
 
-The local half of the [Formfeed](https://formfeed.dev) development kit: template folders, project
+The local half of the [Formfeed](https://formfeed.dev/?utm_source=npm&utm_content=devkit) development kit: template folders, project
 configuration (`formfeed.json`) and offline rendering with the same engine the API uses. The
 [`formfeed` CLI](https://www.npmjs.com/package/formfeed) and
 [`@formfeed/testing`](https://www.npmjs.com/package/@formfeed/testing) are built on it; use it

package/index.cjs

@@ -32,6 +32,7 @@ __export(index_exports, {
   diagnose: () => diagnose,
   findProject: () => findProject,
   generateTypes: () => generateTypes,
+  htmlSnapshot: () => htmlSnapshot,
   isIgnored: () => isIgnored,
   listLocalFiles: () => listLocalFiles,
   listTemplateSlugs: () => listTemplateSlugs,
@@ -538,6 +539,16 @@ async function renderOfficeLocal(project, tpl, data, options = {}) {
   if (options.locale) context.locale = options.locale;
   return (0, import_engine4.renderOffice)(tpl.file.bytes, { engine: tpl.meta.engine, data, context, images: options.images, random: options.random });
 }
+function htmlSnapshot(rendered) {
+  let snapshot = rendered.document;
+  if (rendered.headerHtml) snapshot += `
+<!-- formfeed:header -->
+${rendered.headerHtml}`;
+  if (rendered.footerHtml) snapshot += `
+<!-- formfeed:footer -->
+${rendered.footerHtml}`;
+  return snapshot;
+}
 function officeSnapshot(filled) {
   return (0, import_engine4.officeTextParts)(filled).map((part) => `--- ${part.name} ---
 ${prettyXml(part.xml)}`).join("\n");
@@ -1229,11 +1240,18 @@ function emitTypeScript(templates, options = {}) {
   return lines.join("\n") + "\n";
 }
 
-// packages/devkit/src/lib/types/index.ts
+// packages/devkit/src/lib/types/generate.ts
 var defaultTypesFile = {
   ts: "formfeed.d.ts",
   python: "formfeed_templates.py"
 };
+function generateTypes(sources, language, options = {}) {
+  const reserved = language === "python" ? ["TypedRenders", "AsyncTypedRenders", "Formfeed", "AsyncFormfeed", "Render", "Any", "Literal", "Union", "Never", "NotRequired", "TypedDict"] : ["FormfeedTemplates"];
+  const model = buildTypes(sources, reserved);
+  return language === "python" ? emitPython(model) : emitTypeScript(model, options);
+}
+
+// packages/devkit/src/lib/types/index.ts
 function localTypeSource(tpl) {
   if (tpl.dataSchema) return { slug: tpl.slug, schema: tpl.dataSchema, origin: "local" };
   const sets = Object.values(tpl.dataSets);
@@ -1243,11 +1261,6 @@ function localTypeSource(tpl) {
     origin: "inferred"
   };
 }
-function generateTypes(sources, language, options = {}) {
-  const reserved = language === "python" ? ["TypedRenders", "AsyncTypedRenders", "Formfeed", "AsyncFormfeed", "Render", "Any", "Literal", "Union", "Never", "NotRequired", "TypedDict"] : ["FormfeedTemplates"];
-  const model = buildTypes(sources, reserved);
-  return language === "python" ? emitPython(model) : emitTypeScript(model, options);
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DevkitError,
@@ -1262,6 +1275,7 @@ function generateTypes(sources, language, options = {}) {
   diagnose,
   findProject,
   generateTypes,
+  htmlSnapshot,
   isIgnored,
   listLocalFiles,
   listTemplateSlugs,

package/index.js

@@ -480,6 +480,16 @@ async function renderOfficeLocal(project, tpl, data, options = {}) {
   if (options.locale) context.locale = options.locale;
   return renderOffice(tpl.file.bytes, { engine: tpl.meta.engine, data, context, images: options.images, random: options.random });
 }
+function htmlSnapshot(rendered) {
+  let snapshot = rendered.document;
+  if (rendered.headerHtml) snapshot += `
+<!-- formfeed:header -->
+${rendered.headerHtml}`;
+  if (rendered.footerHtml) snapshot += `
+<!-- formfeed:footer -->
+${rendered.footerHtml}`;
+  return snapshot;
+}
 function officeSnapshot(filled) {
   return officeTextParts(filled).map((part) => `--- ${part.name} ---
 ${prettyXml(part.xml)}`).join("\n");
@@ -1171,11 +1181,18 @@ function emitTypeScript(templates, options = {}) {
   return lines.join("\n") + "\n";
 }
 
-// packages/devkit/src/lib/types/index.ts
+// packages/devkit/src/lib/types/generate.ts
 var defaultTypesFile = {
   ts: "formfeed.d.ts",
   python: "formfeed_templates.py"
 };
+function generateTypes(sources, language, options = {}) {
+  const reserved = language === "python" ? ["TypedRenders", "AsyncTypedRenders", "Formfeed", "AsyncFormfeed", "Render", "Any", "Literal", "Union", "Never", "NotRequired", "TypedDict"] : ["FormfeedTemplates"];
+  const model = buildTypes(sources, reserved);
+  return language === "python" ? emitPython(model) : emitTypeScript(model, options);
+}
+
+// packages/devkit/src/lib/types/index.ts
 function localTypeSource(tpl) {
   if (tpl.dataSchema) return { slug: tpl.slug, schema: tpl.dataSchema, origin: "local" };
   const sets = Object.values(tpl.dataSets);
@@ -1185,11 +1202,6 @@ function localTypeSource(tpl) {
     origin: "inferred"
   };
 }
-function generateTypes(sources, language, options = {}) {
-  const reserved = language === "python" ? ["TypedRenders", "AsyncTypedRenders", "Formfeed", "AsyncFormfeed", "Render", "Any", "Literal", "Union", "Never", "NotRequired", "TypedDict"] : ["FormfeedTemplates"];
-  const model = buildTypes(sources, reserved);
-  return language === "python" ? emitPython(model) : emitTypeScript(model, options);
-}
 export {
   DevkitError,
   brandFromJson,
@@ -1203,6 +1215,7 @@ export {
   diagnose,
   findProject,
   generateTypes,
+  htmlSnapshot,
   isIgnored,
   listLocalFiles,
   listTemplateSlugs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/devkit",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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.5",
-    "@formfeed/sdk": "0.3.5"
+    "@formfeed/engine": "0.3.7",
+    "@formfeed/sdk": "0.3.7"
   },
   "keywords": [
     "formfeed",

package/types/index.d.cts

@@ -6,7 +6,7 @@ export type { LocalOfficeFile, LocalTemplate, ProjectState, SharedPartialState,
 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, renderedSettings } from './lib/local-render.cjs';
+export { diagnose, htmlSnapshot, 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

@@ -6,7 +6,7 @@ export type { LocalOfficeFile, LocalTemplate, ProjectState, SharedPartialState,
 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, renderedSettings } from './lib/local-render.js';
+export { diagnose, htmlSnapshot, 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

@@ -23,6 +23,13 @@ export interface OfficeLocalOptions {
 }
 /** Fills a Word or PowerPoint template with the shared engine, as the render-worker does. */
 export declare function renderOfficeLocal(project: Project, tpl: LocalTemplate, data: unknown, options?: OfficeLocalOptions): Promise<OfficeRenderResult>;
+/**
+ * An HTML template's snapshot: the assembled document, then the rendered header and footer under
+ * `<!-- formfeed:header -->` and `<!-- formfeed:footer -->` lines when the template has them.
+ * Chromium prints header and footer from templates of their own, outside the document, so a
+ * snapshot of the document alone passed a changed footer unnoticed.
+ */
+export declare function htmlSnapshot(rendered: Pick<RenderedDocument, 'document' | 'headerHtml' | 'footerHtml'>): string;
 /**
  * The filled parts of a Word or PowerPoint document as readable text for snapshots: each part's XML,
  * one element per line and indented, text kept beside its element, under a `--- <part> ---` line.

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

@@ -23,6 +23,13 @@ export interface OfficeLocalOptions {
 }
 /** Fills a Word or PowerPoint template with the shared engine, as the render-worker does. */
 export declare function renderOfficeLocal(project: Project, tpl: LocalTemplate, data: unknown, options?: OfficeLocalOptions): Promise<OfficeRenderResult>;
+/**
+ * An HTML template's snapshot: the assembled document, then the rendered header and footer under
+ * `<!-- formfeed:header -->` and `<!-- formfeed:footer -->` lines when the template has them.
+ * Chromium prints header and footer from templates of their own, outside the document, so a
+ * snapshot of the document alone passed a changed footer unnoticed.
+ */
+export declare function htmlSnapshot(rendered: Pick<RenderedDocument, 'document' | 'headerHtml' | 'footerHtml'>): string;
 /**
  * The filled parts of a Word or PowerPoint document as readable text for snapshots: each part's XML,
  * one element per line and indented, text kept beside its element, under a `--- <part> ---` line.

package/types/lib/types/generate.d.cts

@@ -0,0 +1,15 @@
+import { type TypeScriptOptions } from './emit-ts.cjs';
+import { type TypeSource } from './model.cjs';
+/**
+ * `formfeed types` without the file system (spec 19 §2): a schema in, a generated file out. Apart
+ * from `index.ts`, which reads template folders and therefore brings the engine with it, so the
+ * landing site's browser tool can emit exactly what the CLI emits. `@formfeed/devkit/emit` in this
+ * workspace; the published package exposes the same functions from its single entry.
+ */
+export type TypesLanguage = 'ts' | 'python';
+export declare const defaultTypesFile: Record<TypesLanguage, string>;
+/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
+export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
+export { buildTypes, pascalCase, relaxRequired, singular } from './model.cjs';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.cjs';
+export type { TypeScriptOptions } from './emit-ts.cjs';

package/types/lib/types/generate.d.ts

@@ -0,0 +1,15 @@
+import { type TypeScriptOptions } from './emit-ts.js';
+import { type TypeSource } from './model.js';
+/**
+ * `formfeed types` without the file system (spec 19 §2): a schema in, a generated file out. Apart
+ * from `index.ts`, which reads template folders and therefore brings the engine with it, so the
+ * landing site's browser tool can emit exactly what the CLI emits. `@formfeed/devkit/emit` in this
+ * workspace; the published package exposes the same functions from its single entry.
+ */
+export type TypesLanguage = 'ts' | 'python';
+export declare const defaultTypesFile: Record<TypesLanguage, string>;
+/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
+export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
+export { buildTypes, pascalCase, relaxRequired, singular } from './model.js';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.js';
+export type { TypeScriptOptions } from './emit-ts.js';

package/types/lib/types/index.d.cts

@@ -1,15 +1,9 @@
 import type { LocalTemplate } from '../project.cjs';
-import { type TypeScriptOptions } from './emit-ts.cjs';
-import { type TypeSource } from './model.cjs';
-export type TypesLanguage = 'ts' | 'python';
-export declare const defaultTypesFile: Record<TypesLanguage, string>;
+import type { TypeSource } from './model.cjs';
 /**
  * The schema of a template folder: `schema.json` when it has one, else inferred over all its data
  * sets (a field only some sets carry is optional), marked as inferred so every field is optional.
  */
 export declare function localTypeSource(tpl: LocalTemplate): TypeSource;
-/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
-export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
-export { buildTypes, pascalCase, relaxRequired, singular } from './model.cjs';
-export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.cjs';
-export type { TypeScriptOptions } from './emit-ts.cjs';
+export { buildTypes, defaultTypesFile, generateTypes, pascalCase, relaxRequired, singular } from './generate.cjs';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeScriptOptions, TypeSource, TypesLanguage } from './generate.cjs';

package/types/lib/types/index.d.ts

@@ -1,15 +1,9 @@
 import type { LocalTemplate } from '../project.js';
-import { type TypeScriptOptions } from './emit-ts.js';
-import { type TypeSource } from './model.js';
-export type TypesLanguage = 'ts' | 'python';
-export declare const defaultTypesFile: Record<TypesLanguage, string>;
+import type { TypeSource } from './model.js';
 /**
  * The schema of a template folder: `schema.json` when it has one, else inferred over all its data
  * sets (a field only some sets carry is optional), marked as inferred so every field is optional.
  */
 export declare function localTypeSource(tpl: LocalTemplate): TypeSource;
-/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
-export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
-export { buildTypes, pascalCase, relaxRequired, singular } from './model.js';
-export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.js';
-export type { TypeScriptOptions } from './emit-ts.js';
+export { buildTypes, defaultTypesFile, generateTypes, pascalCase, relaxRequired, singular } from './generate.js';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeScriptOptions, TypeSource, TypesLanguage } from './generate.js';