@xeplr/actions 1.3.0 → 1.4.0

package/README.md

@@ -64,7 +64,7 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 |---|---|
 | `register(def)` / `register(name, def)` | Add an action. Throws without `name` or `execute`, or with a `requires` module that is not installed (`ActionMissingDependencyError`). Re-registering a name replaces it. |
 | `get(name)` / `has(name)` | Look one up. |
-| `list()` | `[{ name, description, inputSchema, outputSchema, requires }]` — serializable, for an actions endpoint. |
+| `list()` | `[{ name, description, inputSchema, outputSchema, requires, event }]` — serializable, for an actions endpoint. `event` is `null` for an ordinary action. |
 | `clear()` | Empty the registry. |
 | `runAction({ name, input, system?, timeoutMs? })` | Run a registered action. Never throws. |
 | `runAction(nameOrDef, input, { system, timeoutMs, metaStore }?)` | Same, by name or with an action module directly. |
@@ -91,6 +91,7 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 | `outputSchema` | Optional documentation of the return value. |
 | `requires` | Module names checked with `require.resolve` at `register()`. |
 | `execute({ input, system, metaStore })` | Returns (or resolves to) the output. |
+| `event` | Optional. Makes this a **screen function** rather than a step: the event it is written for — `beforeLoad`, `beforeSave`, `afterSave`, `beforeDelete`, `onError` (run by `@xeplr/factory` around a screen's records) or `decide` (run by `@xeplr/workflow-engine` to choose a flow's next step). A screen names one per event and pickers offer only the functions for that event. It is called with the event's context — `execute(ctx)`, not `{ input, system }` — and never as a workflow step. |
 
 ### `runAction` result
 
@@ -260,6 +261,8 @@ await runAction(builtins.exportTable, {
 - `rect` (`fill`, `stroke`, `radius`)
 - `line`
 
+**`page: { width, height }`** (points, 72–14,400 each) makes every page exactly that size, edge to edge: no margins, no title and no footer or page numbers. It is for a PDF *of the screen*: a board captured as one image, posted as a single `image` block at `x: 0, y: 0, w: 1, h: 1` on a page the board's own size. Nothing is scaled, so what you see is what you get. Without `page`, the layout is A4 with margins, the title on page 1 and a footer on each page, as before.
+
 What it is given is assumed to come from a browser, so it is bounded: 50 pages, 200 blocks a page, 8 MB per image, 500 table rows, and 5,000 characters of text. An image that will not decode draws a note in its box instead of failing the whole file.
 
 Peers (optional, needed only by the format used): `fflate` for xlsx; `pdfkit` and `dejavu-fonts-ttf` for pdf. `writers` (`getWriter`, `INFO`, `SUPPORTED`) is exported for code that wants a writer without the action.

package/lib/builtins/export/pages.js

@@ -25,11 +25,22 @@ function fail(message) {
   return err;
 }
 
+// A page of an exact size, in points: at least an inch, at most PDF's own
+// 200-inch limit (14,400 pt) on a side.
+function pageSize(page) {
+  if (page == null) return;
+  var ok = function(n) { return typeof n === 'number' && isFinite(n) && n >= 72 && n <= 14400; };
+  if (typeof page !== 'object' || !ok(page.width) || !ok(page.height)) {
+    throw fail('page must be { width, height } in points, each between 72 and 14400');
+  }
+}
+
 function fraction(n) { return typeof n === 'number' && isFinite(n) && n >= -0.01 && n <= 50; }
 
 /** Throws (400) naming the first block that is not one this action draws. */
 function validate(spec) {
   var pages = spec.pages;
+  pageSize(spec.page);
   if (!Array.isArray(pages) || !pages.length) throw fail('pages must list at least one page');
   if (pages.length > LIMITS.pages) throw fail('At most ' + LIMITS.pages + ' pages');
   pages.forEach(function(page, p) {
@@ -66,7 +77,9 @@ module.exports = {
     { name: 'title', type: 'string', order: 2 },
     { name: 'footer', type: 'string', order: 3 },
     { name: 'landscape', type: 'boolean', order: 4, description: 'Default true.' },
-    { name: 'outputPath', type: 'string', order: 5 }
+    { name: 'outputPath', type: 'string', order: 5 },
+    { name: 'page', type: 'object', order: 6,
+      description: '{ width, height } in points: every page exactly that size, edge to edge, no title or footer. For a PDF of what the screen shows.' }
   ],
   outputSchema: [
     { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' },
@@ -82,7 +95,8 @@ module.exports = {
     fs.mkdirSync(dir, { recursive: true });
     var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(dir, 'export-')), name);
     var done = await pdf.renderPages(filePath, {
-      pages: input.pages, title: input.title, footer: input.footer, landscape: input.landscape !== false
+      pages: input.pages, title: input.title, footer: input.footer, landscape: input.landscape !== false,
+      page: input.page || null
     });
     return {
       filePath: filePath, fileName: path.basename(filePath), contentType: 'application/pdf',

package/lib/formats/writers/pdf.js

@@ -28,8 +28,8 @@ function newDocument(filePath, opts) {
   var PDFDocument = require('pdfkit');
   var doc = new PDFDocument({
     size: opts.size || 'A4',
-    layout: opts.landscape ? 'landscape' : 'portrait',
-    margins: { top: 36, bottom: 36, left: 32, right: 32 },
+    layout: opts.size ? 'portrait' : (opts.landscape ? 'landscape' : 'portrait'),
+    margins: opts.margin === 0 ? { top: 0, bottom: 0, left: 0, right: 0 } : { top: 36, bottom: 36, left: 32, right: 32 },
     bufferPages: true,
     info: { Title: opts.title || 'Export', Producer: '@xeplr/actions' }
   });
@@ -222,7 +222,13 @@ module.exports = {
    * @param {object} spec - { pages: [{ blocks }], title?, footer?, landscape?: true, font?, boldFont? }
    */
   renderPages: async function(filePath, spec) {
-    var made = newDocument(filePath, { title: spec.title, landscape: spec.landscape !== false, font: spec.font, boldFont: spec.boldFont });
+    // spec.page — { width, height } in points: a page exactly that size, edge
+    // to edge, with no title and no footer. What a "PDF of the screen" needs:
+    // the content IS the page, so nothing is scaled, margined or stamped.
+    var exact = spec.page && spec.page.width && spec.page.height ? spec.page : null;
+    var made = newDocument(filePath, exact
+      ? { title: spec.title, size: [exact.width, exact.height], margin: 0, font: spec.font, boldFont: spec.boldFont }
+      : { title: spec.title, landscape: spec.landscape !== false, font: spec.font, boldFont: spec.boldFont });
     var pdf = made.doc;
     var pages = spec.pages && spec.pages.length ? spec.pages : [{ blocks: [] }];
     try {
@@ -230,8 +236,10 @@ module.exports = {
     pages.forEach(function(page, p) {
       if (p > 0) pdf.addPage();
       var m = pdf.page.margins;
-      var box = { x: m.left, y: m.top, w: pdf.page.width - m.left - m.right, h: pdf.page.height - m.top - m.bottom - 14 };
-      if (p === 0 && spec.title) {
+      var box = exact
+        ? { x: 0, y: 0, w: pdf.page.width, h: pdf.page.height }
+        : { x: m.left, y: m.top, w: pdf.page.width - m.left - m.right, h: pdf.page.height - m.top - m.bottom - 14 };
+      if (p === 0 && spec.title && !exact) {
         pdf.font('bold').fontSize(13).fillColor(COLORS.text).text(spec.title, box.x, box.y, { width: box.w, lineBreak: false });
         var used = pdf.y - box.y + 6;
         box = { x: box.x, y: box.y + used, w: box.w, h: box.h - used };
@@ -281,7 +289,7 @@ module.exports = {
         pdf.restore();
       });
     });
-    stampPages(pdf, spec.footer);
+    if (!exact) stampPages(pdf, spec.footer);
     } catch (err) {
       made.abandon();
       throw err;

package/lib/registry.js

@@ -9,8 +9,17 @@
 //     outputSchema : array?     — optional; documents what the action returns
 //     requires     : string[]?  — peer-dep module names checked at register time
 //     execute      : function   — async ({ input, system }) => output
+//     event        : string?    — a SCREEN FUNCTION, not a step: the event it
+//                                 is written for ('beforeSave', 'decide', …).
+//                                 Called with that event's own context instead
+//                                 of { input, system } — see the README.
 //   }
 //
+// One registry for both, because one app registers both and the two readers
+// (a screen's events, a workflow's arrows and steps) live in one process. What
+// an `event` means is the reader's business: this package only keeps it, and
+// lists it, so a picker can offer each event only the functions written for it.
+//
 // Two call forms:
 //   register(name, def)      → traditional
 //   register(def)            → module-export style: `def.name` is used
@@ -33,6 +42,9 @@ function register(nameOrDef, def) {
   if (typeof action.execute !== 'function') {
     throw new Error('register: action "' + action.name + '" must have an `execute` function');
   }
+  if (action.event !== undefined && (typeof action.event !== 'string' || !action.event.trim())) {
+    throw new Error('register: action "' + action.name + '" has an `event` that is not a name — e.g. "beforeSave"');
+  }
 
   // Sanity-check peer deps.
   if (Array.isArray(action.requires)) {
@@ -48,6 +60,7 @@ function register(nameOrDef, def) {
     inputSchema:  Array.isArray(action.inputSchema) ? action.inputSchema : [],
     outputSchema: action.outputSchema || null,
     requires:     Array.isArray(action.requires) ? action.requires.slice() : [],
+    event:        action.event || null,
     execute:      action.execute
   });
 }
@@ -64,7 +77,8 @@ function list() {
       description: def.description,
       inputSchema: def.inputSchema,
       outputSchema: def.outputSchema,
-      requires: def.requires
+      requires: def.requires,
+      event: def.event
     });
   });
   return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "files": [