@hailer/mcp 1.1.12 → 1.1.13

package/.claude/skills/SDK-document-templates/SKILL.md

@@ -1,1033 +0,0 @@
----
-name: SDK-document-templates
-description: PDF/CSV document template patterns - field mappings, pdfmake structure, generation code
-version: 1.2.0
-triggers: Document template, PDF generation, CSV export, pdfmake, field mapping
----
-
-# Document Template Patterns
-
-## File Structure
-
-```
-workspace/[Workflow]_[id]/
-├── templates.ts                     # Template registry
-└── templates/[TemplateName]_[id]/
-    ├── template.config.ts           # Field mappings, options
-    └── template.code.ts             # Generation function (pdfmake)
-```
-
----
-
-## Template Lifecycle
-
-### Creating New Template
-
-```
-1. npm run pull
-2. Edit templates.ts:
-   { templateId: "", name: "Invoice", fileType: "pdf", folder: "" }
-3. Return ["npm run templates-sync:force"]
-4. npm run pull (generates template folder + files)
-5. Edit template.config.ts (field mappings)
-6. Edit template.code.ts (generation logic)
-7. Return ["npm run templates-push"]
-```
-
-### Updating Template
-
-```
-1. npm run pull
-2. Edit template.config.ts or template.code.ts
-3. Return ["npm run templates-push"]
-```
-
----
-
-## CRITICAL: Zero vs Null Filtering
-
-**#1 PDF gotcha:** Numeric fields may have `0` as a meaningful value OR as an empty placeholder. Filter logic that uses truthiness (`if (value)`) will hide valid zeros.
-
-**Core helper function:**
-```typescript
-function shouldDisplayValue(value: unknown): boolean {
-  if (value === null || value === undefined) return false;
-  if (value === '') return false;
-  if (typeof value === 'number' && isNaN(value)) return false;
-  if (value === 0) return true;  // KEEP meaningful zeros!
-  return true;
-}
-
-// Usage in PDFs
-if (shouldDisplayValue(fields.quantity?.value)) {
-  // Displays: 0 ✓  (meaningful zero)
-  // Hides: null, undefined, NaN ✓
-}
-```
-
-For field-type-specific logic, see **"Distinguishing Meaningful Zero from Empty/Null"** section below.
-
----
-
-## templates.ts (Registry)
-
-```typescript
-export const templates: DocumentTemplateEntry[] = [
-  // NEW template - empty templateId
-  {
-    templateId: "",
-    name: "Invoice",
-    fileType: "pdf",
-    folder: ""
-  },
-  // EXISTING template
-  {
-    templateId: "6932a64fb1353d454b74d743",
-    name: "Invoice",
-    fileType: "pdf",
-    folder: "invoice_6932a64fb1353d454b74d743"
-  }
-];
-```
-
----
-
-## template.config.ts (Field Mappings)
-
-```typescript
-import { Invoice_FieldIds, Customer_FieldIds } from "../../enums";
-
-export const template: DocumentTemplateUpdatePayload = {
-  content: "@function:invoice_abc",
-  name: "Invoice Template",
-  fileType: "pdf",
-  fieldMap: {
-    fields: {
-      invoiceNumber: {
-        label: "Invoice Number",
-        description: "The invoice reference",
-        value: `::${Invoice_FieldIds.invoice_number_abc}`
-      },
-      customerName: {
-        label: "Customer",
-        description: "Customer name from linked activity",
-        value: `::${Invoice_FieldIds.customer_link_def}/::${Customer_FieldIds.name_ghi}`
-      },
-      amount: {
-        label: "Total Amount",
-        value: `::${Invoice_FieldIds.total_amount_jkl}`
-      }
-    },
-    images: {
-      logo: {
-        description: "Company logo",
-        value: "67640282d1346d04eacf4b05"  // Image ID from Hailer
-      }
-    },
-    activityLinks: {
-      customer: {
-        label: "Customer",
-        description: "Linked customer",
-        field: Invoice_FieldIds.customer_link_def,
-        process: WorkflowIds.customers_mno
-      }
-    }
-  },
-  opts: {
-    formatFieldValue: true,
-    decimalSeparator: ",",
-    thousandSeparator: " ",
-    toFixedDigits: "2",
-    toFixedIds: `${Invoice_FieldIds.total_amount_jkl}`
-  },
-  templateId: "existing_id_or_empty"
-};
-```
-
-### Field Value Syntax
-
-| Pattern | Description | Example |
-|---------|-------------|---------|
-| `::fieldId` | Field from current activity | `::${Invoice_FieldIds.number_abc}` |
-| `::fieldId/::otherFieldId` | Field from linked activity | `::${Invoice_FieldIds.customer_def}/::${Customer_FieldIds.name_ghi}` |
-| `::fieldId/::name` | **Linked activity's name** | `::${Invoice_FieldIds.customer_def}/::name` |
-| `::name` | Activity name | `"::name"` |
-| Static text | Literal value | `"Fixed text here"` |
-
-**ActivityLink → Name shortcut:** To get a linked activity's name directly, use `/::name` suffix:
-```typescript
-customerName: {
-  label: "Customer",
-  value: `::${Invoice_FieldIds.customer_link}/::name`  // Returns linked activity's name string
-}
-```
-Without `/::name`, you get the raw object/ID which won't display properly.
-
-**CRITICAL:** Use template literals with `${}`:
-```typescript
-// ✅ Correct
-value: `::${Invoice_FieldIds.number_abc}`
-
-// ❌ Wrong
-value: `::{Invoice_FieldIds.number_abc}`
-```
-
----
-
-## Linked Activity Field Values via itemTable
-
-### The Problem
-- `linkedfrom` fields DO NOT support cross-link syntax (`::linkedfromField/::targetField` returns empty)
-- Cross-link syntax (`::field/::otherField`) only works for `activitylink` (forward link) fields
-- `this.fieldMap.activityLinks` at runtime echoes config, not resolved data
-
-### The Solution: itemTable
-When you add fields from linked activities to the template's `activityLinks` config, Hailer populates `this.fieldMap.itemTable` with resolved values.
-
-**Config example:**
-```typescript
-activityLinks: {
-  tilavaraukset: {
-    label: "Tilavaraukset",
-    field: FieldIds.tilavaraukset_link,
-    process: WorkflowIds.tilavaraukset,
-    fields: {
-      lisatiedot: {
-        label: "Lisätiedot",
-        value: `::${Tilavaraukset_FieldIds.varauksen_lisatiedot}`
-      },
-      ajankohta: {
-        label: "Ajankohta",
-        value: `::${Tilavaraukset_FieldIds.ajankohta}`
-      }
-    }
-  }
-}
-```
-
-**itemTable structure at runtime:**
-
-**CRITICAL: Workflow name is ALWAYS the LAST column** in the headers array. Filter tables by checking `headers[headers.length - 1]`, NOT `headers[0]`.
-
-```javascript
-// this.fieldMap.itemTable = array of table objects, one per activityLink
-[
-  {
-    headers: ["Lisätiedot", "Ajankohta", "Tilavaraukset"],  // Last header = workflow name
-    rows: [
-      ["Kaksi pöytää", "Feb 23, 2026 14:15 – Feb 24, 2026 10:00", ""],
-      // one row per linked activity
-    ]
-  },
-  // ... more tables for other activityLinks
-]
-```
-
-**Helper pattern for extracting columns:**
-```javascript
-function getItemTableColumn(itemTable, workflowName, columnLabel) {
-  if (!itemTable) return [];
-  for (const table of itemTable) {
-    const headers = table.headers || [];
-    // Workflow name is LAST header
-    if (headers[headers.length - 1] !== workflowName) continue;
-    const colIdx = headers.indexOf(columnLabel);
-    if (colIdx === -1) return [];
-    return (table.rows || []).map(row => row[colIdx] || '-');
-  }
-  return [];
-}
-```
-
-**Usage in template code:**
-```javascript
-const lisatiedot = getItemTableColumn(
-  this.fieldMap.itemTable,
-  'Tilavaraukset',     // workflow name (last header column)
-  'Lisätiedot'         // field label to extract
-);
-// lisatiedot = ["Kaksi pöytää", "Toinen varaus kuvaus", ...]
-```
-
-### Gotchas
-
-- **`linkedfrom` cross-links: DON'T WORK** in templates. Use `itemTable` instead.
-- **`activitylink` (forward) cross-links: WORK fine** with `::field/::otherField` syntax.
-- **Dates in itemTable** come as English strings (e.g., "Feb 23, 2026 14:15") - parse and reformat for Finnish if needed.
-
----
-
-## template.code.ts (Generation Function)
-
-### Class Structure
-
-```typescript
-export class invoice_abc {
-  // Context properties (available in Hailer backend)
-  activity!: ActivityDoc;
-  process!: ProcessDoc;
-  workspaceId!: string;
-  fieldMap!: FieldMap;
-  templateId!: string;
-  templateName!: string;
-  renderedActivity!: RenderedActivity[];
-
-  // Methods
-  setDocument!: (doc: any, filename: string) => void;
-
-  // <---- UNDER THIS LINE EVERYTHING IS SENT TO HAILER ---->
-
-  async setPdfDefinition() {
-    const doc = this.getEmptyPdfDoc(this.fieldMap);
-
-    // Build document content
-    doc.content.push(this.buildHeader());
-    doc.content.push(this.buildBody());
-
-    const filename = `invoice_${this.fieldMap.fields.invoiceNumber?.value}`;
-    this.setDocument(doc, filename);
-  }
-
-  // Helper methods...
-}
-```
-
-### Available Context Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `this.fieldMap.fields` | Record | Field values with label/description |
-| `this.fieldMap.images` | Record | Image IDs |
-| `this.fieldMap.activityLinks` | Record | Linked activity data |
-| `this.fieldMap.itemTable` | Array | Table data from linked activities |
-| `this.activity` | Object | Current activity (name, currentPhase) |
-| `this.process` | Object | Workflow info (name, phases) |
-| `this.templateName` | string | Template name |
-| `this.localeDate` | Date | Current date |
-
-### Available Methods
-
-| Method | Description |
-|--------|-------------|
-| `this.getEmptyPdfDoc(fieldMap)` | Base PDF structure with styles |
-| `this.setDocument(doc, filename)` | Set final document (required) |
-| `this.getChecked()` | Checked checkbox image |
-| `this.getUnchecked()` | Unchecked checkbox image |
-| `this.getCheckbox(value)` | Checkbox based on boolean |
-
----
-
-## pdfmake Patterns
-
-### Basic Text
-```javascript
-{ text: 'Hello World' }
-{ text: 'Bold text', bold: true }
-{ text: 'Large text', fontSize: 14 }
-```
-
-### Using Field Values
-```javascript
-const fields = this.fieldMap.fields;
-
-{ text: fields.invoiceNumber?.value || 'N/A' }
-{ text: fields.customerName?.label + ': ' + fields.customerName?.value }
-```
-
-### Columns
-```javascript
-{
-  columns: [
-    { width: '*', text: 'Left side' },
-    { width: 'auto', text: 'Right side' }
-  ]
-}
-```
-
-### Tables
-```javascript
-{
-  table: {
-    headerRows: 1,
-    widths: ['*', 100, 100],
-    body: [
-      // Header row
-      [
-        { text: 'Item', bold: true },
-        { text: 'Qty', bold: true },
-        { text: 'Price', bold: true }
-      ],
-      // Data rows
-      ['Product A', '10', '€100.00'],
-      ['Product B', '5', '€50.00']
-    ]
-  }
-}
-```
-
-### Table Spacing for Label:Value Grids
-
-For 4-column label:value layouts, use narrower label columns to keep values close:
-```javascript
-// ✅ Good: Values stay close to labels
-{
-  table: {
-    widths: [90, 'auto', 90, 'auto'],
-    body: [
-      [
-        { text: 'Tilaaja:', bold: true }, fields.customer?.value || '',
-        { text: 'Päivämäärä:', bold: true }, fields.date?.value || ''
-      ]
-    ]
-  },
-  layout: 'noBorders'
-}
-
-// ❌ Avoid: [120, '*', 120, '*'] spreads content too wide
-```
-```
-
-### Images
-```javascript
-// From fieldMap
-{
-  image: this.fieldMap.images?.logo?.value,
-  width: 150
-}
-
-// With fallback
-this.fieldMap.images?.logo?.value
-  ? { image: this.fieldMap.images.logo.value, width: 150 }
-  : { text: 'No logo', italics: true }
-```
-
-### Logo in Header (Two-Step Requirement)
-
-**CRITICAL:** Logo in PDF header requires BOTH config AND code reference:
-
-**Step 1 - template.config.ts:**
-```typescript
-fieldMap: {
-  images: {
-    logo: { value: "67640282d1346d04eacf4b05" }  // Image ID from Hailer
-  }
-}
-```
-
-**Step 2 - template.code.ts (getEmptyPdfDoc header function):**
-```javascript
-getEmptyPdfDoc(fieldMap) {
-  const images = fieldMap.images;  // Must pass images to scope
-  return {
-    header(currentPage, pageCount) {
-      return [{
-        columns: [
-          // Must explicitly reference images here
-          images?.logo?.value
-            ? { image: images.logo.value, width: 140, margin: [40, 20, 0, 0] }
-            : { text: '', margin: [40, 20, 0, 0] },
-          // ... rest of header
-        ]
-      }];
-    },
-    // ...
-  };
-}
-```
-
-**Common mistake:** Adding logo to config but not referencing in header function → logo doesn't appear.
-
-### Margins & Spacing
-```javascript
-// [left, top, right, bottom]
-{ text: 'Padded', margin: [10, 20, 10, 20] }
-
-// Blank line
-{ text: ' ' }
-{ text: '', margin: [0, 10, 0, 0] }
-```
-
-### Styles
-```javascript
-// Define in getEmptyPdfDoc
-styles: {
-  header: { fontSize: 18, bold: true },
-  subheader: { fontSize: 14, bold: true },
-  tableHeader: { bold: true, fillColor: '#eeeeee' }
-}
-
-// Use
-{ text: 'Title', style: 'header' }
-```
-
----
-
-## Complete PDF Example
-
-```javascript
-async setPdfDefinition() {
-  const fields = this.fieldMap.fields;
-  const images = this.fieldMap.images;
-
-  const doc = this.getEmptyPdfDoc(this.fieldMap);
-
-  // Header with logo
-  doc.content.push({
-    columns: [
-      images?.logo?.value
-        ? { image: images.logo.value, width: 120 }
-        : { text: '' },
-      {
-        alignment: 'right',
-        stack: [
-          { text: 'INVOICE', style: 'header' },
-          { text: fields.invoiceNumber?.value || '' }
-        ]
-      }
-    ]
-  });
-
-  // Customer info
-  doc.content.push({ text: ' ' });
-  doc.content.push({
-    text: fields.customerName?.value || 'Unknown Customer',
-    style: 'subheader'
-  });
-
-  // Line items table
-  doc.content.push({ text: ' ' });
-  doc.content.push(this.buildLineItemsTable());
-
-  // Total
-  doc.content.push({
-    alignment: 'right',
-    text: `Total: €${fields.amount?.value || '0.00'}`,
-    bold: true,
-    margin: [0, 20, 0, 0]
-  });
-
-  const filename = `invoice_${fields.invoiceNumber?.value || 'draft'}`;
-  this.setDocument(doc, filename);
-}
-
-buildLineItemsTable() {
-  // Build from itemTable if available
-  const items = this.fieldMap.itemTable || [];
-
-  const body = [
-    // Header
-    [
-      { text: 'Description', bold: true },
-      { text: 'Qty', bold: true },
-      { text: 'Price', bold: true }
-    ]
-  ];
-
-  // Data rows
-  items.forEach(item => {
-    body.push([
-      item.description || '',
-      item.quantity || '',
-      item.price || ''
-    ]);
-  });
-
-  return {
-    table: {
-      headerRows: 1,
-      widths: ['*', 60, 80],
-      body
-    }
-  };
-}
-```
-
----
-
-## CSV Templates
-
-For CSV, return array of arrays:
-
-```javascript
-async setCsvDefinition() {
-  const fields = this.fieldMap.fields;
-
-  const rows = [
-    // Header row
-    ['Invoice', 'Customer', 'Amount', 'Date'],
-    // Data row
-    [
-      fields.invoiceNumber?.value || '',
-      fields.customerName?.value || '',
-      fields.amount?.value || '',
-      new Date().toLocaleDateString('fi-FI')
-    ]
-  ];
-
-  const filename = `invoice_${fields.invoiceNumber?.value || 'export'}`;
-  this.setDocument(rows, filename);
-}
-```
-
----
-
-## Options (opts)
-
-```typescript
-opts: {
-  formatFieldValue: true,        // Apply formatting
-  decimalSeparator: ",",         // Finnish: comma
-  thousandSeparator: " ",        // Finnish: space
-  toFixedDigits: "2",            // Decimal places
-  toFixedIds: "field1,field2"    // Fields to format
-}
-```
-
----
-
-## Common Mistakes
-
-| Wrong | Right |
-|-------|-------|
-| `::{FieldIds.x}` | `::${FieldIds.x}` (template literal) |
-| Missing `?.` on field access | Always use `fields.x?.value` |
-| Forgetting `setDocument()` | Must call at end of function |
-| Creating folder manually | Let `npm run pull` create it after sync |
-| Editing templateId | Never change after creation |
-| Pushing before sync (new) | New templates: sync first, then push |
-
----
-
-## Real-World Example: Meeting Minutes PDF
-
-Complete working example with brand colors, conditional rendering, and Finnish locale.
-
-### template.config.ts
-```typescript
-export const template: DocumentTemplateUpdatePayload = {
-  content: "@function:palaverimuistio_pdf_b8b",
-  description: "Palaverimuistion PDF-tuloste",
-  fieldMap: {
-    fields: {
-      name: { label: "Otsikko", value: "::name" },
-      shortDescription: { label: "Lyhyt kuvaus", value: "::681adfcadc3d7d989f58a38d" },
-      date: { label: "Ajankohta", value: "::67e697da6ada809b961c35b5" },
-      participants: { label: "Osallistujat", value: "::67e698076ada809b961c36d7" },
-      title1: { label: "Otsikko 1", value: "::6819ed047be62a4af274b5fa" },
-      text1: { label: "Teksti 1", value: "::67e697106ada809b961c310c" }
-      // ... more fields
-    },
-    images: {
-      logo: { description: "Company logo", value: "68009ab7e01c4e8528bfd901" }
-    }
-  },
-  fileType: "pdf",
-  name: "Palaverimuistio PDF",
-  opts: { formatFieldValue: true, decimalSeparator: ",", thousandSeparator: " " },
-  templateId: "6960ae0978e1a7b04df30b8b"
-};
-```
-
-### template.code.ts
-```javascript
-async setPdfDefinition() {
-    const doc = this.getEmptyPdfDoc(this.fieldMap);
-    const fields = this.fieldMap.fields;
-
-    // Title with brand color
-    doc.content.push({
-        text: fields.name?.value || 'Palaverimuistio',
-        style: 'header'
-    });
-
-    // Blue divider line
-    doc.content.push({
-        canvas: [{ type: 'line', x1: 0, y1: 0, x2: 515, y2: 0, lineWidth: 1, color: '#005EAA' }],
-        margin: [0, 10, 0, 15]
-    });
-
-    // Conditional info rows - only render if value exists
-    if (fields.date?.value) {
-        doc.content.push({
-            columns: [
-                { width: 120, text: 'Ajankohta:', bold: true, color: '#005EAA' },
-                { width: '*', text: fields.date.value }
-            ],
-            margin: [0, 3, 0, 3]
-        });
-    }
-
-    // Dynamic note sections - only show if content exists
-    const notePairs = [
-        { title: fields.title1, text: fields.text1 },
-        { title: fields.title2, text: fields.text2 }
-    ];
-
-    notePairs.forEach(pair => {
-        if (pair.title?.value || pair.text?.value) {
-            if (pair.title?.value) {
-                doc.content.push({ text: pair.title.value, style: 'sectionHeader', margin: [0, 15, 0, 8] });
-            }
-            if (pair.text?.value) {
-                doc.content.push({ text: pair.text.value, style: 'bodyText', margin: [0, 0, 0, 10] });
-            }
-        }
-    });
-
-    // Filename from activity name + date
-    const activityName = this.activity?.name || 'palaverimuistio';
-    const dateStr = fields.date?.value || new Date().toISOString().split('T')[0];
-    const filename = `${activityName}_${dateStr}`.replace(/[^a-zA-Z0-9_-]/g, '_');
-
-    this.setDocument(doc, filename);
-}
-
-getEmptyPdfDoc(fieldMap) {
-    const images = fieldMap.images;
-    return {
-        header(currentPage, pageCount) {
-            return [{
-                columns: [
-                    images?.logo?.value
-                        ? { image: images.logo.value, width: 140, margin: [40, 20, 0, 0] }
-                        : { text: '', width: 140, margin: [40, 20, 0, 0] },
-                    {
-                        width: '*',
-                        alignment: 'right',
-                        stack: [
-                            { text: 'PALAVERIMUISTIO', fontSize: 10, color: '#005EAA', bold: true },
-                            { text: `Sivu ${currentPage} / ${pageCount}`, fontSize: 8, color: '#666666' }
-                        ],
-                        margin: [0, 25, 40, 0]
-                    }
-                ]
-            }];
-        },
-        footer() {
-            const datetime = new Date().toLocaleDateString('fi-FI');
-            return [{
-                columns: [
-                    { width: '*', text: 'Luotu: ' + datetime, fontSize: 7, color: '#999999', margin: [40, 0, 0, 0] },
-                    { width: '*', text: 'hailer.com', fontSize: 7, color: '#999999', alignment: 'right', margin: [0, 0, 40, 0] }
-                ]
-            }];
-        },
-        pageSize: 'A4',
-        pageMargins: [40, 80, 40, 50],
-        content: [],
-        styles: {
-            header: { fontSize: 22, bold: true, color: '#005EAA' },
-            sectionHeader: { fontSize: 14, bold: true, color: '#005EAA' },
-            bodyText: { fontSize: 10, color: '#333333', lineHeight: 1.4 }
-        },
-        defaultStyle: { font: 'nunito', fontSize: 10 }
-    };
-}
-```
-
----
-
-## Additional Patterns
-
-### Using Raw Field IDs vs Enums
-
-When orchestrator provides field IDs directly, use them as strings:
-```typescript
-// Raw field ID (common)
-value: "::67e697da6ada809b961c35b5"
-
-// With enums (when imported)
-value: `::${Workflow_FieldIds.date_abc}`
-```
-
-### Clickable Links
-```javascript
-if (fields.materialsLink?.value) {
-    doc.content.push({
-        text: fields.materialsLink.value,
-        link: fields.materialsLink.value,
-        color: '#005EAA',
-        decoration: 'underline'
-    });
-}
-```
-
-### Finnish Locale Dates
-```javascript
-new Date().toLocaleDateString('fi-FI')  // "9.1.2025"
-new Date().toLocaleTimeString('fi-FI', { hour: '2-digit', minute: '2-digit' })  // "14:30"
-```
-
-### Parsing Pre-Formatted Hailer Dates
-
-**Problem:** Hailer pre-formats date values even with `formatFieldValue: false`. Date/daterange fields arrive as English strings like "Feb 5, 2026" or "Feb 5, 2026 Feb 5, 2026".
-
-**Solution:** Parse and reformat to Finnish:
-```javascript
-function formatToFinnishDate(hailerDate) {
-  if (!hailerDate) return '';
-
-  // Extract dates with regex (handles single date and date ranges)
-  const datePattern = /([A-Za-z]{3} \d{1,2}, \d{4})/g;
-  const matches = hailerDate.match(datePattern);
-
-  if (!matches) return hailerDate;
-
-  const finnishDates = matches.map(dateStr => {
-    const date = new Date(dateStr);
-    return date.toLocaleDateString('fi-FI', {
-      day: '2-digit',
-      month: '2-digit',
-      year: '2-digit'
-    });
-  });
-
-  // Single date or range
-  return finnishDates.length === 1
-    ? finnishDates[0]                           // "05.02.26"
-    : `${finnishDates[0]} - ${finnishDates[1]}`; // "05.02.26 - 06.02.26"
-}
-
-// Usage
-const finnishDate = formatToFinnishDate(fields.eventDate?.value);
-```
-
-### Safe Filename Generation
-```javascript
-const filename = `${activityName}_${dateStr}`.replace(/[^a-zA-Z0-9_-]/g, '_');
-```
-
-### File Upload Fields as Images
-
-When a field contains uploaded images (FileUpload field type), the value comes as a JSON array string of base64 data URLs.
-
-**Config:** Put in `fieldMap.fields` (NOT `fieldMap.images`):
-```typescript
-fieldMap: {
-  fields: {
-    photos: {
-      label: "Photos",
-      value: `::${FieldIds.photos_abc}`  // FileUpload field
-    }
-  }
-}
-```
-
-**Code:** Parse and render each image:
-```javascript
-// Parse the JSON array of base64 data URLs
-const photos = fields.photos?.value;
-if (photos) {
-  try {
-    const imageArray = JSON.parse(photos);
-
-    imageArray.forEach((dataUrl) => {
-      // Validate it's actually an image data URL
-      if (typeof dataUrl === 'string' && dataUrl.startsWith('data:image')) {
-        doc.content.push({
-          image: dataUrl,
-          fit: [400, 300],  // Preserves aspect ratio within bounds
-          margin: [0, 10, 0, 10]
-        });
-      }
-    });
-  } catch (e) {
-    // Not valid JSON - skip
-  }
-}
-```
-
-**Key points:**
-- Value is a **JSON array string**, not raw array
-- Each item is a **base64 data URL** (`data:image/png;base64,...`)
-- Use `JSON.parse()` to convert to array
-- Validate with `startsWith('data:image')` before rendering
-- Use `fit: [width, height]` to preserve aspect ratio
-
-### Null Value Filtering in PDFs
-
-Function fields can return formatted defaults (e.g., "0 kgCO2e/yksikkö") even when underlying data is null. Use a helper to distinguish meaningful values from null placeholders.
-
-```javascript
-// Helper to check if value is displayable
-function isValidValue(value) {
-  if (value === null || value === undefined) return false;
-  const str = String(value).trim();
-
-  // Filter obvious null placeholders
-  if (str === '' || str === '−' || str === '::' || str === '-') return false;
-
-  // Filter dimension zeros (0 mm, 0 cm, etc.)
-  if (/^0\s*(mm|cm|m|kg|kpl)?$/i.test(str)) return false;
-
-  return true;
-}
-
-// Usage in PDF generation
-if (isValidValue(fields.weight?.value)) {
-  doc.content.push({
-    columns: [
-      { width: 120, text: 'Paino:', bold: true },
-      { width: '*', text: fields.weight.value }
-    ]
-  });
-}
-```
-
-**Field-specific logic:**
-- **Dimension zeros** (0 mm, 0 cm): Usually hide - indicates unmeasured
-- **Price zeros** (0 €): Context-dependent - sometimes meaningful
-- **Formatted function fields**: Check if underlying calculation returned null
-
----
-
-### Distinguishing Meaningful Zero from Empty/Null
-
-**Problem:** CO2 fields in Spolia required multiple iterations to filter correctly. Some zeros are meaningful (calculated values), others are empty/null placeholders.
-
-**Solution:** Use type-specific filtering logic:
-
-```typescript
-// Core pattern: Filter out truly empty values but keep meaningful zeros
-function shouldDisplayValue(value: unknown): boolean {
-  // Null and undefined are always empty
-  if (value === null || value === undefined) return false;
-
-  // Empty string is empty
-  if (value === '') return false;
-
-  // NaN is empty (for numeric fields)
-  if (typeof value === 'number' && isNaN(value)) return false;
-
-  // CRITICAL: Keep 0 - it's a meaningful numeric value
-  if (value === 0) return true;
-
-  return true;
-}
-
-// Pattern: Filter fields for display based on value type
-const displayFields = fields.filter(f => {
-  const value = activity.fields?.[f.id]?.value;
-
-  // Different rules per field type
-  switch (f.fieldType) {
-    case 'number':
-      // Keep 0, filter null/undefined/NaN
-      return shouldDisplayValue(value);
-
-    case 'text':
-      // Filter null, undefined, empty string
-      // Consider whitespace-only as empty
-      if (!value) return false;
-      if (typeof value === 'string' && value.trim() === '') return false;
-      return true;
-
-    case 'reference':
-      // Reference fields must have a valid ID string
-      // ID length varies by workflow - check for non-empty string
-      return typeof value === 'string' && value.trim().length > 0;
-
-    case 'date':
-      // Valid ISO date or timestamp
-      return value && !isNaN(new Date(value).getTime());
-
-    case 'boolean':
-      // Keep false and true - both are valid
-      return typeof value === 'boolean';
-
-    default:
-      return shouldDisplayValue(value);
-  }
-});
-```
-
-**Field-type specific examples:**
-
-```typescript
-// Numeric field: 0 is valid, undefined is empty
-const co2Value = fields.co2_emissions?.value;  // Could be 0, could be undefined
-if (shouldDisplayValue(co2Value)) {
-  // Display: "0 kgCO2e" ✓
-  // Don't display: undefined/null/NaN ✓
-}
-
-// Text field: Empty string is empty, whitespace-only is empty
-const description = fields.description?.value;
-if (description && typeof description === 'string' && description.trim() !== '') {
-  // Display: "Sample text" ✓
-  // Don't display: "" or "   " ✓
-}
-
-// Reference field: Check for non-empty string ID
-const linkedActivityId = fields.linked_activity?.value;
-if (typeof linkedActivityId === 'string' && linkedActivityId.trim().length > 0) {
-  // Display: "507f1f77bcf86cd799439011" ✓
-  // Don't display: "" or null ✓
-}
-
-// Boolean field: Both true and false are valid values
-const isActive = fields.active?.value;
-if (typeof isActive === 'boolean') {
-  // Display: false ✓ (don't filter out)
-  // Don't display: null/undefined ✓
-}
-
-// Function field returning formatted number: Keep meaningful zeros
-const calculatedCost = fields.total_cost?.value;  // Example: "0 €" or "150 €"
-if (shouldDisplayValue(calculatedCost)) {
-  // Display: "0 €" if it's a calculated zero ✓
-  // But if underlying value was null, filtered function may still output placeholder
-  // → Use isValidValue() helper (above) for extra safety
-}
-```
-
-**Real-world scenario from Spolia CO2 case:**
-
-```typescript
-// ❌ Bad: Filters out valid zeros
-const fields = activity.fields.filter(f => f.value);  // Loses 0 values!
-
-// ❌ Also bad: Checks truthiness
-if (activity.fields[fieldId]?.value) {  // false for 0!
-  // Won't render CO2: 0 kgCO2e/yksikkö
-}
-
-// ✅ Good: Type-aware filtering
-if (shouldDisplayValue(activity.fields[fieldId]?.value)) {
-  // Renders CO2: 0 kgCO2e/yksikkö ✓
-  // Skips CO2: undefined ✓
-}
-
-// ✅ Better: Field-specific logic
-const co2 = activity.fields[CO2_FIELD_ID]?.value;
-if (co2 !== null && co2 !== undefined && !isNaN(Number(co2))) {
-  doc.content.push({
-    text: `CO2: ${co2} kgCO2e/yksikkö`
-  });
-}
-```
-
-**Troubleshooting:**
-
-| Symptom | Likely Cause | Fix |
-|---------|--------------|-----|
-| "0 € " values missing from PDF | Using truthiness check (if value) | Use `shouldDisplayValue()` |
-| Function field shows "−" or placeholder | Underlying data is null but function formatted it | Use `isValidValue()` helper |
-| Some zeros showing, some not | Inconsistent filter logic per field type | Use switch statement by fieldType |
-| NaN appearing in output | Not checking `isNaN()` for numbers | Add NaN check |
-| Whitespace-only text showing | Not trimming string values | Use `value.trim() !== ''` for text |
-
----
-
-## Checklist
-
-Before pushing template changes:
-
-- [ ] Used template literals `${}` in field mappings (or raw IDs as strings)
-- [ ] All field accesses use optional chaining `?.`
-- [ ] `setDocument(doc, filename)` called at end
-- [ ] Filename has no extension (added automatically)
-- [ ] New template: sync first, pull, then edit config/code
-- [ ] Conditional rendering for optional fields
-- [ ] Brand colors as hex codes (e.g., '#005EAA')
-- [ ] Tested PDF opens correctly