@json-to-office/jto 3.0.0 → 3.2.0

package/dist/client/templates/client-report-blocks.docx.json

@@ -590,8 +590,65 @@
           ]
         }
       },
-      "metric-row": {
-        "description": "Two to four equal-width metrics. Optional source collapses together with its divider. Text budgets reject overflow; columns reflow at unchanged type size.",
+      "source-line": {
+        "description": "A hairline and a source line in the source role, under a figure or a table. The data blocks invoke it; copy it to add a source to anything else.",
+        "slots": {
+          "text": {
+            "type": "string",
+            "required": true,
+            "maxWords": 20,
+            "role": "source"
+          }
+        },
+        "body": [
+          {
+            "name": "divider",
+            "props": {
+              "thickness": 0.5,
+              "color": {
+                "$theme": "/palette/rule",
+                "default": "borderPrimary"
+              },
+              "spacing": {
+                "before": 4,
+                "after": 4
+              }
+            }
+          },
+          {
+            "name": "paragraph",
+            "props": {
+              "text": {
+                "$slot": "/text"
+              },
+              "font": {
+                "family": {
+                  "$theme": "/fonts/body/family",
+                  "default": "Calibri"
+                },
+                "size": {
+                  "$theme": "/styles/source/size",
+                  "default": 8
+                },
+                "bold": {
+                  "$theme": "/styles/source/bold",
+                  "default": false
+                },
+                "color": {
+                  "$theme": "/styles/source/color",
+                  "default": "textMuted"
+                }
+              },
+              "spacing": {
+                "before": 0,
+                "after": 8
+              }
+            }
+          }
+        ]
+      },
+      "kpi-row": {
+        "description": "Two to four headline metrics in equal columns: value with its unit, label, and a signed delta with a direction glyph. An optional source collapses with its hairline. Text budgets reject overflow; columns reflow at unchanged type size.",
         "slots": {
           "items": {
             "type": "array",
@@ -604,19 +661,38 @@
                 "value": {
                   "type": "string",
                   "required": true,
-                  "maxLength": 12
+                  "maxLength": 12,
+                  "description": "The headline figure, already formatted: 8.8, 94, +18."
+                },
+                "unit": {
+                  "type": "string",
+                  "maxLength": 6,
+                  "description": "Suffix drawn after the figure at half its size: %, €m, pts. Write the space yourself when one belongs."
                 },
                 "label": {
                   "type": "string",
                   "required": true,
-                  "maxWords": 6
+                  "oneLine": true,
+                  "maxWords": 6,
+                  "description": "What the figure measures."
+                },
+                "delta": {
+                  "type": "string",
+                  "maxLength": 12,
+                  "description": "Signed change shown beside the figure: +3.2 pts, −0.4."
+                },
+                "trend": {
+                  "type": "string",
+                  "enum": ["up", "down", "neutral"],
+                  "description": "Direction glyph drawn before the delta."
                 }
               }
             }
           },
           "source": {
             "type": "string",
-            "maxWords": 20
+            "maxWords": 20,
+            "role": "source"
           }
         },
         "body": [
@@ -634,11 +710,20 @@
                 "template": {
                   "name": "statistic",
                   "props": {
+                    "number": {
+                      "$item": "/value"
+                    },
+                    "unit": {
+                      "$item": "/unit"
+                    },
                     "description": {
                       "$item": "/label"
                     },
-                    "number": {
-                      "$item": "/value"
+                    "trend": {
+                      "$item": "/trend"
+                    },
+                    "trendValue": {
+                      "$item": "/delta"
                     }
                   }
                 }
@@ -647,21 +732,571 @@
           },
           {
             "$if": "/source",
+            "then": {
+              "name": "block",
+              "props": {
+                "ref": "source-line",
+                "slots": {
+                  "text": {
+                    "$slot": "/source"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "callout": {
+        "description": "An aside set off by a hairline rule down its left edge: a short label over up to sixty words of text. No fill, so it reads as a note beside the argument rather than a box in it.",
+        "slots": {
+          "label": {
+            "type": "string",
+            "oneLine": true,
+            "maxWords": 6,
+            "default": "Note"
+          },
+          "text": {
+            "type": "string",
+            "required": true,
+            "maxWords": 60
+          }
+        },
+        "body": [
+          {
+            "name": "text-box",
+            "props": {
+              "width": "100%",
+              "style": {
+                "padding": {
+                  "top": 2,
+                  "bottom": 2,
+                  "left": 10,
+                  "right": 0
+                },
+                "border": {
+                  "left": {
+                    "style": "solid",
+                    "width": 0.75,
+                    "color": {
+                      "$theme": "/palette/rule",
+                      "default": "borderPrimary"
+                    }
+                  }
+                }
+              }
+            },
+            "children": [
+              {
+                "name": "paragraph",
+                "props": {
+                  "text": {
+                    "$slot": "/label"
+                  },
+                  "font": {
+                    "family": {
+                      "$theme": "/fonts/body/family",
+                      "default": "Calibri"
+                    },
+                    "size": {
+                      "$theme": "/styles/label/size",
+                      "default": 9
+                    },
+                    "bold": {
+                      "$theme": "/styles/label/bold",
+                      "default": true
+                    },
+                    "color": {
+                      "$theme": "/styles/label/color",
+                      "default": "textPrimary"
+                    }
+                  },
+                  "spacing": {
+                    "before": 0,
+                    "after": 2
+                  },
+                  "keepNext": true
+                }
+              },
+              {
+                "name": "paragraph",
+                "props": {
+                  "text": {
+                    "$slot": "/text"
+                  },
+                  "spacing": {
+                    "before": 0,
+                    "after": 0
+                  }
+                }
+              }
+            ]
+          }
+        ]
+      },
+      "data-table": {
+        "description": "A sourced numeric table: a title, a text column of row labels, one to six data columns right-aligned by construction, then optional notes and a source line. With its header, 24 rows keep the table on one page; the table-design rule checks the compiled table for mixed decimals.",
+        "slots": {
+          "title": {
+            "type": "string",
+            "required": true,
+            "oneLine": true,
+            "maxWords": 16
+          },
+          "labelHeader": {
+            "type": "string",
+            "oneLine": true,
+            "maxWords": 4,
+            "default": "",
+            "description": "Header of the row-label column."
+          },
+          "labels": {
+            "type": "array",
+            "required": true,
+            "minItems": 1,
+            "maxItems": 24,
+            "items": {
+              "type": "string",
+              "oneLine": true,
+              "maxWords": 8
+            },
+            "description": "Row labels, top to bottom. Every data column lists its cells in this order and at this count."
+          },
+          "columns": {
+            "type": "array",
+            "required": true,
+            "minItems": 1,
+            "maxItems": 6,
+            "items": {
+              "type": "object",
+              "properties": {
+                "header": {
+                  "type": "string",
+                  "required": true,
+                  "oneLine": true,
+                  "maxWords": 4,
+                  "description": "Column header; put the unit here: Revenue (€m)."
+                },
+                "cells": {
+                  "type": "array",
+                  "required": true,
+                  "minItems": 1,
+                  "maxItems": 24,
+                  "items": {
+                    "type": "string",
+                    "maxLength": 16
+                  },
+                  "description": "One formatted value per row label, rounded the same way down the column."
+                },
+                "numeric": {
+                  "type": "boolean",
+                  "default": true,
+                  "description": "Right-align header and cells so digits line up by place value. Set false for a text column."
+                }
+              }
+            }
+          },
+          "notes": {
+            "type": "string",
+            "maxWords": 40,
+            "description": "What the reader needs to interpret the figures: definitions, periods, exclusions."
+          },
+          "source": {
+            "type": "string",
+            "maxWords": 20,
+            "role": "source"
+          }
+        },
+        "body": [
+          {
+            "name": "paragraph",
+            "props": {
+              "text": {
+                "$slot": "/title"
+              },
+              "font": {
+                "family": {
+                  "$theme": "/fonts/body/family",
+                  "default": "Calibri"
+                },
+                "size": {
+                  "$theme": "/styles/label/size",
+                  "default": 9
+                },
+                "bold": {
+                  "$theme": "/styles/label/bold",
+                  "default": true
+                },
+                "color": {
+                  "$theme": "/styles/label/color",
+                  "default": "textPrimary"
+                }
+              },
+              "spacing": {
+                "before": 8,
+                "after": 4
+              },
+              "keepNext": true
+            }
+          },
+          {
+            "name": "table",
+            "props": {
+              "width": 100,
+              "repeatHeaderOnPageBreak": true,
+              "columns": [
+                {
+                  "header": {
+                    "content": {
+                      "$slot": "/labelHeader"
+                    }
+                  },
+                  "cells": {
+                    "$each": "/labels",
+                    "template": {
+                      "content": {
+                        "$item": ""
+                      }
+                    }
+                  }
+                },
+                {
+                  "$each": "/columns",
+                  "template": {
+                    "header": {
+                      "content": {
+                        "$item": "/header"
+                      },
+                      "horizontalAlignment": {
+                        "$if": {
+                          "$item": "/numeric"
+                        },
+                        "then": "right",
+                        "else": "left"
+                      }
+                    },
+                    "cellDefaults": {
+                      "horizontalAlignment": {
+                        "$if": {
+                          "$item": "/numeric"
+                        },
+                        "then": "right",
+                        "else": "left"
+                      }
+                    },
+                    "cells": {
+                      "$each": {
+                        "$item": "/cells"
+                      },
+                      "template": {
+                        "content": {
+                          "$item": ""
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          {
+            "$if": "/notes",
+            "then": {
+              "name": "paragraph",
+              "props": {
+                "text": {
+                  "$slot": "/notes"
+                },
+                "font": {
+                  "family": {
+                    "$theme": "/fonts/body/family",
+                    "default": "Calibri"
+                  },
+                  "size": {
+                    "$theme": "/styles/source/size",
+                    "default": 8
+                  },
+                  "bold": {
+                    "$theme": "/styles/source/bold",
+                    "default": false
+                  },
+                  "color": {
+                    "$theme": "/styles/source/color",
+                    "default": "textMuted"
+                  }
+                },
+                "spacing": {
+                  "before": 4,
+                  "after": 0
+                }
+              }
+            }
+          },
+          {
+            "$if": "/source",
+            "then": {
+              "name": "block",
+              "props": {
+                "ref": "source-line",
+                "slots": {
+                  "text": {
+                    "$slot": "/source"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "figure-caption": {
+        "description": "The numbered caption under a figure: **Figure N.** and the text, N being a Word SEQ field over the figure sequence. chart-figure and figure invoke it, so charts and images number together.",
+        "slots": {
+          "text": {
+            "type": "string",
+            "required": true,
+            "oneLine": true,
+            "maxWords": 20
+          }
+        },
+        "body": [
+          {
+            "name": "paragraph",
+            "props": {
+              "text": {
+                "$join": [
+                  "**Figure {SEQ:figure}.** ",
+                  {
+                    "$slot": "/text"
+                  }
+                ]
+              },
+              "font": {
+                "family": {
+                  "$theme": "/fonts/body/family",
+                  "default": "Calibri"
+                },
+                "size": {
+                  "$theme": "/styles/label/size",
+                  "default": 9
+                },
+                "bold": false,
+                "color": {
+                  "$theme": "/styles/label/color",
+                  "default": "textPrimary"
+                }
+              },
+              "spacing": {
+                "before": 4,
+                "after": 2
+              },
+              "keepNext": true
+            }
+          }
+        ]
+      },
+      "chart-figure": {
+        "description": "A numbered, sourced chart: the chart itself (highcharts through the export server, or a native chart on the office-open renderer), a caption that says what it shows, an optional takeaway beneath, and the source line the report cites. The source is required; the figure number is a Word SEQ field.",
+        "slots": {
+          "chart": {
+            "type": "component",
+            "required": true,
+            "description": "A highcharts or chart component. Put the unit in the value-axis title: Revenue (€m)."
+          },
+          "caption": {
+            "type": "string",
+            "required": true,
+            "oneLine": true,
+            "maxWords": 20,
+            "description": "What the chart shows, as a statement: Revenue by quarter, 2026."
+          },
+          "takeaway": {
+            "type": "string",
+            "maxWords": 30,
+            "role": "takeaway",
+            "description": "The one sentence the reader should leave with."
+          },
+          "source": {
+            "type": "string",
+            "required": true,
+            "maxWords": 20,
+            "role": "source"
+          }
+        },
+        "body": [
+          {
+            "$slot": "/chart"
+          },
+          {
+            "name": "block",
+            "props": {
+              "ref": "figure-caption",
+              "slots": {
+                "text": {
+                  "$slot": "/caption"
+                }
+              }
+            }
+          },
+          {
+            "$if": "/takeaway",
+            "then": {
+              "name": "paragraph",
+              "props": {
+                "text": {
+                  "$slot": "/takeaway"
+                },
+                "font": {
+                  "family": {
+                    "$theme": "/fonts/body/family",
+                    "default": "Calibri"
+                  },
+                  "color": {
+                    "$theme": "/styles/quote/color",
+                    "default": "textSecondary"
+                  }
+                },
+                "spacing": {
+                  "before": 0,
+                  "after": 2
+                }
+              }
+            }
+          },
+          {
+            "$if": "/source",
+            "then": {
+              "name": "block",
+              "props": {
+                "ref": "source-line",
+                "slots": {
+                  "text": {
+                    "$slot": "/source"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "figure": {
+        "description": "A numbered image with a caption and an optional source line. The image keeps its own width and alt text; the figure number is a Word SEQ field shared with chart-figure.",
+        "slots": {
+          "image": {
+            "type": "component",
+            "required": true,
+            "description": "An image or visual component. Give it alt text and a width."
+          },
+          "caption": {
+            "type": "string",
+            "required": true,
+            "oneLine": true,
+            "maxWords": 20
+          },
+          "source": {
+            "type": "string",
+            "maxWords": 20,
+            "role": "source"
+          }
+        },
+        "body": [
+          {
+            "$slot": "/image"
+          },
+          {
+            "name": "block",
+            "props": {
+              "ref": "figure-caption",
+              "slots": {
+                "text": {
+                  "$slot": "/caption"
+                }
+              }
+            }
+          },
+          {
+            "$if": "/source",
+            "then": {
+              "name": "block",
+              "props": {
+                "ref": "source-line",
+                "slots": {
+                  "text": {
+                    "$slot": "/source"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      },
+      "footnotes": {
+        "description": "Notes and sources: every distinct source-role slot value the document's block invocations carry, in order, as a numbered list under a label — the engine's /sources context. Emits nothing when no invocation cites a source.",
+        "slots": {
+          "title": {
+            "type": "string",
+            "oneLine": true,
+            "maxWords": 6,
+            "default": "Notes and sources"
+          }
+        },
+        "body": [
+          {
+            "$if": {
+              "$context": "/sources"
+            },
             "then": [
               {
                 "name": "divider",
                 "props": {
-                  "thickness": 0.5
+                  "thickness": 0.5,
+                  "color": {
+                    "$theme": "/palette/rule",
+                    "default": "borderPrimary"
+                  },
+                  "spacing": {
+                    "before": 12,
+                    "after": 4
+                  }
                 }
               },
               {
                 "name": "paragraph",
                 "props": {
                   "text": {
-                    "$slot": "/source"
+                    "$slot": "/title"
                   },
                   "font": {
-                    "size": 9
+                    "family": {
+                      "$theme": "/fonts/body/family",
+                      "default": "Calibri"
+                    },
+                    "size": {
+                      "$theme": "/styles/label/size",
+                      "default": 9
+                    },
+                    "bold": true,
+                    "color": {
+                      "$theme": "/styles/label/color",
+                      "default": "textPrimary"
+                    }
+                  },
+                  "spacing": {
+                    "before": 0,
+                    "after": 4
+                  },
+                  "keepNext": true
+                }
+              },
+              {
+                "name": "list",
+                "props": {
+                  "format": "decimal",
+                  "items": {
+                    "$each": {
+                      "$context": "/sources"
+                    },
+                    "template": {
+                      "$item": ""
+                    }
                   }
                 }
               }
@@ -738,19 +1373,42 @@
         {
           "name": "block",
           "props": {
-            "ref": "metric-row",
+            "ref": "kpi-row",
             "slots": {
               "items": [
                 {
-                  "value": "+18%",
-                  "label": "Revenue growth"
+                  "value": "8.8",
+                  "unit": " €m",
+                  "label": "Revenue year to date",
+                  "delta": "+16.9%",
+                  "trend": "up"
+                },
+                {
+                  "value": "94",
+                  "unit": "%",
+                  "label": "Client retention",
+                  "delta": "+2 pts",
+                  "trend": "up"
                 },
                 {
-                  "value": "94%",
-                  "label": "Client retention"
+                  "value": "11",
+                  "unit": " days",
+                  "label": "Median time to deliver",
+                  "delta": "−3 days",
+                  "trend": "down"
                 }
               ],
-              "source": "Source: quarterly operating review."
+              "source": "Source: quarterly operating review, 2026."
+            }
+          }
+        },
+        {
+          "name": "block",
+          "props": {
+            "ref": "callout",
+            "slots": {
+              "label": "How to read the deltas",
+              "text": "Deltas compare the first three quarters of 2026 with the same period of 2025. Retention counts contracts renewed within thirty days of their term; late renewals are excluded from both years."
             }
           }
         }
@@ -779,10 +1437,114 @@
             }
           }
         },
+        {
+          "name": "block",
+          "props": {
+            "ref": "data-table",
+            "slots": {
+              "title": "Revenue and retention by segment, 2026 to date",
+              "labelHeader": "Segment",
+              "labels": [
+                "Enterprise",
+                "Mid-market",
+                "Public sector",
+                "All segments"
+              ],
+              "columns": [
+                {
+                  "header": "Revenue (€m)",
+                  "cells": ["4.2", "2.7", "1.9", "8.8"]
+                },
+                {
+                  "header": "Growth (%)",
+                  "cells": ["21.0", "14.5", "9.8", "16.9"]
+                },
+                {
+                  "header": "Retention (%)",
+                  "cells": ["96", "93", "91", "94"]
+                }
+              ],
+              "notes": "Growth is year on year on the same nine months. Retention counts contracts renewed within thirty days of their term.",
+              "source": "Source: quarterly operating review, 2026."
+            }
+          }
+        },
         {
           "name": "paragraph",
           "props": {
-            "text": "The inherited running header uses this section\u2019s tracker and page width. Page numbers are native Word fields."
+            "text": "The inherited running header uses this section’s tracker and page width. Page numbers are native Word fields."
+          }
+        },
+        {
+          "name": "block",
+          "props": {
+            "ref": "chart-figure",
+            "slots": {
+              "chart": {
+                "name": "highcharts",
+                "props": {
+                  "width": "100%",
+                  "options": {
+                    "chart": {
+                      "type": "column",
+                      "width": 900,
+                      "height": 460
+                    },
+                    "title": {
+                      "text": null
+                    },
+                    "xAxis": {
+                      "categories": ["Q1", "Q2", "Q3", "Q4"]
+                    },
+                    "yAxis": {
+                      "min": 0,
+                      "title": {
+                        "text": "Revenue (€m)"
+                      }
+                    },
+                    "legend": {
+                      "enabled": false
+                    },
+                    "series": [
+                      {
+                        "name": "Revenue",
+                        "data": [1.9, 2.4, 2.7, 3.1]
+                      }
+                    ],
+                    "credits": {
+                      "enabled": false
+                    }
+                  }
+                }
+              },
+              "caption": "Revenue by quarter, 2026",
+              "takeaway": "Each quarter outgrew the last as delivery stabilised; the fourth quarter alone matched the first half of 2025.",
+              "source": "Source: quarterly operating review, 2026."
+            }
+          }
+        },
+        {
+          "name": "block",
+          "props": {
+            "ref": "figure",
+            "slots": {
+              "image": {
+                "name": "image",
+                "props": {
+                  "path": "media/client-report-blocks/delivery-model.png",
+                  "width": "100%",
+                  "alt": "Four delivery stages in sequence: intake, weekly ownership, delivery and renewal; ownership and delivery are shaded as the stages that changed"
+                }
+              },
+              "caption": "The delivery model, with the two stages that changed this year",
+              "source": "Source: operating handbook, 2026 edition."
+            }
+          }
+        },
+        {
+          "name": "block",
+          "props": {
+            "ref": "footnotes"
           }
         }
       ]