@broadpaper/core 0.2.1 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 The document model, expression language, theme resolution and paginator behind BroadPaper. Framework-free.
 
-Part of [**BroadPaper**](https://www.broadpaper.com) — an embeddable visual report designer and PDF renderer.
+Part of [**BroadPaper**](https://www.broadpaper.com/developers/) — an embeddable visual report designer and PDF renderer.
 Your users design the report in your application; BroadPaper owns the layout, the branding,
 the pagination and the output.
 
@@ -32,14 +32,16 @@ before a single row of data exists.
 ## Licensing
 
 BroadPaper is **free to evaluate, with no trial clock and nothing behind a feature gate**.
-Install it, use every feature, run it against your real data, in production if you like.
+Install it, use every feature and evaluate it against your real data for as long as you like.
+Production use needs a licence.
 
-The only difference without a licence is that generated PDFs carry an evaluation mark. A
-licence removes it — that is the entire commercial mechanism. No seats, no activation, no
-machine binding, no telemetry, and no call home at any point.
+In the software, the only difference without a licence is that generated PDFs carry an
+evaluation mark, and a licence removes it. Contractually, the licence is also what permits
+production use. No seats, no activation, no machine binding, no telemetry, and no call home at
+any point.
 
 - [How licensing works](https://www.broadpaper.com/docs/guide/licensing/)
-- [Pricing](https://www.broadpaper.com/pricing/)
+- [Pricing](https://www.broadpaper.com/developers/pricing/)
 - [Licence agreement](https://www.broadpaper.com/legal/terms/)
 
 ## Documentation

package/dist/index.d.ts

@@ -318,9 +318,20 @@ interface PageContext {
  * Brand theme supplied by the host. A template references theme values via
  * tokens (`$colors.primary`) so one template renders under any brand.
  */
+/**
+ * A font, declared once for the canvas, the designer's pickers and the PDF.
+ *
+ * Include a TrueType or OpenType file among the sources: the browser reads any
+ * format, but the browserless PDF engine reads only those two, and a face with
+ * nothing else is drawn in a standard face in the file (with a warning saying so).
+ */
 interface ThemeFontFace {
     family: string;
-    /** URL(s) to the font file(s). `data:` URLs are supported for fully offline rendering. */
+    /**
+     * URL(s) to the font file(s), in order of preference, as `@font-face` lists them.
+     * `data:` URLs are supported for fully offline rendering. The PDF engine takes the
+     * first TrueType or OpenType one and skips WOFF and WOFF2.
+     */
     src: string | string[];
     weight?: number | string;
     style?: "normal" | "italic";
@@ -1165,6 +1176,26 @@ interface BlockDefinition<P extends Record<string, unknown> = Record<string, unk
      * Derived from `split` when omitted.
      */
     measure?: "text" | "table" | "none";
+    /**
+     * Props for a block created by dropping a data field onto the page.
+     *
+     * The designer lets a user drag a field out of the data panel, and what should
+     * appear is not the same thing for every block: a list wants a table with a
+     * column per item field, each already formatted the way the schema says; a
+     * scalar wants a labelled value. Only the block knows what its own props mean,
+     * so the block decides — including a custom block, which is the reason this is
+     * a hook rather than a rule in the editor.
+     *
+     * `expr` is the bare path; `formatted` is the same path with the field's own
+     * formatter appended, which is what a prop rendering the value as text should
+     * use. Return undefined to take the designer's default.
+     */
+    fromField?(field: {
+        expr: string;
+        formatted: string;
+        schema: FieldSchema;
+        label: string;
+    }): Partial<P> | undefined;
     /** Adjust resolved props after binding resolution (compute derived data, sort, etc.). */
     resolve?(ctx: ResolveHookContext<P>): P | void;
     render(ctx: RenderContext<P>): VNode | null;
@@ -2347,6 +2378,244 @@ declare function synthesizeValue(schema: FieldSchema, opts?: {
 declare function labelForPath(segments: PathSegment[], scope: SchemaScope): string;
 declare function humanizeKey(key: string): string;
 
+/**
+ * The formatter a field wants, when nobody has said otherwise.
+ *
+ * A schema already knows that a field is money in sterling, or a date the host
+ * writes as `d MMMM yyyy`, or a fraction meant to be read as a percentage.
+ * Nothing was doing anything with that: a binding inserted from the data panel
+ * was the bare path, so a currency field rendered as `482310.4` and a date as
+ * `2026-08-31T00:00:00.000Z` until somebody typed a pipe after it.
+ *
+ * That is a fine default for a developer who knows the expression language and
+ * a poor one for anybody else, so the pipe is written into the expression at the
+ * moment the binding is created. Written in, and not applied invisibly at render
+ * time, for two reasons worth stating:
+ *
+ * - it stays visible and editable. The template says `| currency:'USD'`, so
+ *   somebody reading it can see why the document shows dollars, and somebody who
+ *   wants three decimal places can change it;
+ * - it cannot change what an existing template does. Formatting bound values at
+ *   render time would alter the output of every document already saved against a
+ *   typed schema, which is not a change a published SDK gets to make quietly.
+ *
+ * Blocks that evaluate their own expressions — a table's columns, a chart's
+ * series — get the same treatment from the same function, which is what keeps a
+ * total in a table footer formatted like the column above it.
+ */
+
+/**
+ * The pipe expression for a field, or null when the value should be shown as it
+ * is.
+ *
+ * Text, booleans, URLs and rich text are already what they should look like.
+ * Everything numeric or temporal is not.
+ */
+declare function defaultPipeFor(schema: FieldSchema | undefined): string | null;
+/**
+ * Adds the field's default formatter to a path expression.
+ *
+ * Leaves anything that already has a pipe alone — the author said what they
+ * wanted — and leaves anything that is not a plain path alone too, because a
+ * computed expression's type is its own business and appending to it could
+ * change what it means.
+ */
+declare function withDefaultPipe(expr: string, schema: FieldSchema | undefined): string;
+/** Whether an expression already ends in a formatter, ignoring `||`. */
+declare function hasPipe(expr: string): boolean;
+/**
+ * A dotted path and nothing else: `client.name`, `row.amount`, `holdings[0].value`.
+ *
+ * Anything with an operator, a call or a literal in it is left alone. `a + b`
+ * with a currency pipe bolted on would format the sum, which may be what the
+ * author wanted or may not, and guessing is worse than doing nothing.
+ */
+declare function isPlainPath(expr: string): boolean;
+
+/**
+ * A calculation, as a person would describe it rather than as the expression
+ * language would.
+ *
+ * The designer has always been able to *bind* a value — point a property at a
+ * field — and never to work one out. Arithmetic arrived only inside a template
+ * somebody wrote by hand, so a host with the expression editor switched off had a
+ * document whose totals it could read and not change, and a host with it on asked
+ * a business user to write `sum(invoice.lineItems.amount) * (1 + taxRate)`. Both
+ * are the same missing feature.
+ *
+ * So: a small closed model of the arithmetic documents actually contain, and a
+ * codec between it and the expression language. The builder in the editor edits
+ * this; the template still holds an ordinary expression, so nothing downstream —
+ * the interpreter, the validator, the renderer, the PDF backends — learns anything
+ * new. A calculation is a *view* of an expression, never a second way to store one.
+ *
+ * ## Left to right, and no brackets
+ *
+ * `start` and then a list of `steps`, each applied to the running total. That is
+ * the one decision here worth defending, because a tree would be more general and
+ * much worse: an interface with brackets in it is a formula editor, and a business
+ * user with a formula editor is a business user writing formulas. Left-to-right
+ * covers what invoices and reports do — a subtotal, VAT on it, a discount off it,
+ * a division for an average — and reads as a sentence:
+ *
+ *     Total of Lines › Amount, add VAT rate as a percentage
+ *
+ * Precedence never arises, because there is none to get wrong: every step applies
+ * to everything before it, and `toExpression` brackets accordingly.
+ *
+ * ## Percentages are an operator, not multiplication
+ *
+ * "Add VAT rate as a percentage" rather than "multiply by (1 + VAT rate)". It is
+ * the same arithmetic and it is the difference between a step somebody can choose
+ * and one they have to derive. It is also emitted null-safe — `coalesce(rate, 0)`
+ * — because a business that has not set a VAT rate wants an invoice without VAT,
+ * not one with a hole where the total was.
+ *
+ * ## The contract that makes this safe
+ *
+ * {@link fromExpression} returns `null` for anything it cannot rebuild **byte for
+ * byte**. An interface that offered to edit an expression it would then rewrite
+ * differently is an interface that silently changes documents on being looked at;
+ * refusing is the honest answer, and the caller shows the value as read-only
+ * instead. `calculation.test.ts` asserts the round trip on every expression the
+ * starter templates ship.
+ */
+
+/** The five aggregates a document asks for. Deliberately not every function. */
+type CalcAggregate = "sum" | "avg" | "count" | "min" | "max";
+/** One thing a calculation reads or holds. Flat: a term is never itself a calculation. */
+type CalcTerm = 
+/** A field, by its dotted path. `invoice.taxRate`, `row.amount`. */
+{
+    kind: "field";
+    path: string;
+}
+/** A column of a list, across every row of it. `sum(invoice.lineItems.amount)`. */
+ | {
+    kind: "aggregate";
+    fn: CalcAggregate;
+    path: string;
+}
+/** A number somebody typed. */
+ | {
+    kind: "number";
+    value: number;
+};
+/**
+ * What to do with a term, given everything so far.
+ *
+ * `addPercent` and `subtractPercent` treat the term as a rate: 0.2 is a fifth.
+ * That matches `percent`-typed fields and the mapping package's own reading of a
+ * typed rate, so a VAT rate is the same number everywhere in the product.
+ */
+type CalcOp = "add" | "subtract" | "multiply" | "divide" | "addPercent" | "subtractPercent";
+interface CalcStep {
+    op: CalcOp;
+    term: CalcTerm;
+}
+interface Calculation {
+    start: CalcTerm;
+    steps: CalcStep[];
+    /**
+     * How the result is shown: a pipe chain, exactly as it appears after `|` in the
+     * expression. `currency:"GBP"`, `number:0`, `percent:1`. Presentation only, and
+     * applied once at the end — a format in the middle of arithmetic would turn a
+     * number into a string and the next step into a concatenation.
+     */
+    format?: string;
+}
+/** Everything a calculation reads, for validation and for naming it. */
+declare function calcPaths(calc: Calculation): string[];
+/** The AST, for a caller that wants to type-check a calculation before storing it. */
+declare function calcToAst(calc: Calculation): Expr;
+declare function toExpression(calc: Calculation): string;
+/**
+ * Reads an expression back as a calculation, or refuses.
+ *
+ * `null` means "this is not something the builder can represent", and the caller's
+ * job is then to show the value rather than offer to edit it. Everything this
+ * accepts, {@link toExpression} reproduces character for character — which is
+ * asserted, because the failure otherwise is a template quietly rewritten by
+ * somebody opening a panel.
+ */
+declare function fromExpression(expr: string): Calculation | null;
+/** Whether an expression is arithmetic rather than a plain field or a formatted one. */
+declare function isCalculation(calc: Calculation): boolean;
+
+/**
+ * What changed between two saved templates, said in words.
+ *
+ * A revision history is only useful if it can answer "what is different about
+ * this one" without asking anybody to read a template. A structural diff of the
+ * JSON answers a different question — which keys moved — and it answers it in
+ * the vocabulary of the format: `body[2].children[0].props.columns`. This speaks
+ * the vocabulary of the designer instead: the table in “Summary”, the page
+ * margins, the Heading 1 style.
+ *
+ * Three decisions shape everything below.
+ *
+ * **Nodes are matched by id, never by position.** Every node already carries a
+ * stable id, and matching by position is how inserting one section at the top
+ * becomes "changed every section in the document". A subtree added or removed
+ * is one change, not one per descendant — a person who deleted a section
+ * deleted a section.
+ *
+ * **Expression syntax never reaches the words.** A host may hide expressions
+ * entirely (`expressions: false`), and a revision list that printed
+ * `sum(invoice.lineItems.amount) | currency` would put back exactly what that
+ * flag took away. Bindings are named with `describeExpression`, the same
+ * function the canvas chips use, and anything that still would not read as
+ * words is called "a calculated value".
+ *
+ * **It is pure.** No DOM, no registry required, deterministic output — the same
+ * two templates always produce the same list in the same order, so a host can
+ * store the summary beside a revision and trust it later.
+ */
+
+type ChangeKind = "added" | "removed" | "changed" | "moved";
+type ChangeArea = "document" | "page" | "styles" | "header" | "footer" | "body";
+interface TemplateChange {
+    kind: ChangeKind;
+    area: ChangeArea;
+    /** The node's id, when the change is to a node. */
+    nodeId?: string;
+    /** What changed, named for a person: "Table", "Top margin", "Heading 1 style". */
+    subject: string;
+    /** One sentence: `Added a table to “Summary”`, `Changed the page margins`. */
+    summary: string;
+    /** Display strings, only when a single simple value changed. ≤ 80 chars each, truncated with "…". */
+    before?: string;
+    after?: string;
+}
+interface TemplateDiff {
+    changes: TemplateChange[];
+    counts: Record<ChangeKind, number>;
+    /** Changes beyond `maxChanges` that were counted but not listed. */
+    truncated: number;
+    identical: boolean;
+}
+interface DiffOptions {
+    /** Block definitions, for naming block types and their properties. */
+    registry?: BlockRegistry;
+    /** Default 200. */
+    maxChanges?: number;
+    /**
+     * The data sources the template binds to, so a binding is named by its field's
+     * own label ("Invoice number") rather than a humanised key ("Number").
+     * Optional: without them the names are still words, just plainer ones.
+     */
+    dataSources?: DataSource[];
+}
+declare function diffTemplates(before: ReportTemplate, after: ReportTemplate, options?: DiffOptions): TemplateDiff;
+/**
+ * One line for a list of revisions.
+ *
+ * A single change is worth naming outright; several are counted, because a list
+ * row that tried to name seven changes would be truncated into saying none of
+ * them properly.
+ */
+declare function summariseDiff(diff: TemplateDiff): string;
+
 interface ResolveOptions {
     template: ReportTemplate;
     registry: BlockRegistry;
@@ -2875,4 +3144,4 @@ declare function renderNode(node: ResolvedNode, opts: RenderTreeOptions, width?:
 /** Renders a list of resolved sections into a fragment-less flat list. */
 declare function renderSections(sections: ResolvedNode[], opts: RenderTreeOptions): VNode[];
 
-export { type AnyVersionTemplate, type BinaryOp, type BindingInfo, type BindingKind, type BindingSpec, type BlockCategory, type BlockDefinition, type BlockNode, BlockRegistry, type BlockRegistryLike, type BlockStyle, type BorderSpec, type BorderStyle, type BreakMode, type BreakRun, CONDITION_OPERATORS, CURRENT_SCHEMA_VERSION, type CardStyle, type ColorValue, type Command, CommandError, type Condition, type ConditionGroup, type ConditionRule, type ContainerSpec, type CreateNodeOptions, type CreateTemplateOptions, type CustomPageSize, DEFAULT_PAGE_CONTEXT, DEFAULT_THEME, type DataSource, type DispatchOptions, type DocumentStyles, type EditorState, EditorStore, type EditorStoreOptions, type EvalContext, type Expr, ExpressionError, FUNCTION_NAMES, type FieldSchema, type FieldType, type FlowOptions, type FontValue, type FormatContext, GLOBAL_SCHEMAS, type GeometryMap, type HistoryEntry, type InlineNode, type InspectorApi, type InspectorComponent, type InspectorField, type InspectorFieldBase, type InspectorSection, type Issue, type IssueCode, type IssueSeverity, type IssueSource, type LayoutWarning, type LibraryItem, type LicenseTier, type List, type ListItem, MIGRATIONS, type Measurer, type Migration, MigrationError, type MigrationResult, type Node, type NodeEntry, type NodeGeometry, type NodeIndex, type NodeLocation, type OutputCheckOptions, PAGE_SIZES_MM, PIPES, PX_PER_MM, type Page, type PageContext, type PageFragment, type PageGeometry, type PageMargins, type PageOrientation, type PageRegionSettings, type PageSettings, type PageSize, type PageSizeName, type PagedDocument, type PaginateOptions, type Paragraph, type ParseResult, type PathSegment, type PipeDefinition, type PipeFn, REGION_IDS, ROW_LAYOUTS, type RegionContent, type RegionId, type RegistryOptions, type RenderContext, type RenderMode, type RenderTreeOptions, type RepeatedHeader, type ReportData, type ReportTemplate, type ResolveHookContext, type ResolveOptions, type ResolvedDocument, type ResolvedFlow, type ResolvedNode, type ResolvedRegion, type ResolvedRole, type ResolvedSegment, type ResolvedStyle, type RichTextDoc, SchemaScope, type SchemaVersion, Scope, type SectionGeometry, type SelectOption, type Spacing, type SplitMode, type StyleCascadeInput, type StyleGroup, type TableRowGeometry, type TableStyle, type TemplateMeta, type TemplateSegment, type TemplateSettings, type TextAlign, type TextMarks, type TextRun, type TextStyle, type TextStyleId, type Theme, type ThemeColors, type ThemeFontFace, type ThemeTableDefaults, type ThemeTokenInfo, type ThemeTypography, type TokenRef, type TokenRun, type TypeIssue, type TypeResult, type VChild, type VNode, type VProps, type ValidateContext, type ValidateOptions, type ValidationResult, type ValueType, type VerticalAlign, ancestors, applyCommand, bestBreak, bindingSpecsFor, blockStyleSchema, checkExpressionSyntax, checkOutput, classNames, cloneWithNewIds, collectPaths, columnWidth, compareValues, compileCondition, computePageGeometry, countNodes, createColumn, createId, createNode, createParagraph, createRichText, createRow, createSchemaScope, createSection, createTemplate, cssText, dataSourceSchemas, defaultDocumentStyles, defaultPageSettings, defineBlock, describeExpression, documentStylesSchema, escapeHtml, evaluate, evaluateAst, evaluateCondition, evaluateText, evaluateToText, exprToString, extractTemplateTokens, findNode, formatCurrency, formatDate, formatDatePattern, formatNumber, formatPercent, getField, getRegion, h, humaniseLabel, humanize, humanizeKey, indexTemplate, inlineFromTemplate, inlineToPlain, interpolate, isDarkColor, isDescendant, isEmptyValue, isRichTextDoc, isSafeUrl, isTokenRef, isVNode, issue, itemSchemaOf, labelForPath, listAt, listThemeTokens, looseEquals, mergeTheme, migrateTemplate, missingThemeValues, mmToPx, needsMigration, nodeAt, nodeAttrs, nodeSchema, pageSettingsSchema, pageSizeMm, paginate, parseExpression, parseTemplate, pathToString, pxToMm, readProperty, readRegion, renderInline, renderNode, renderRichText, renderSections, renderSegments, resolveDefaultProps, resolvePath, resolvePathSchema, resolveStyle, resolveTemplate, resolveToken, resolveValue, richTextFromTemplate, richTextToPlain, richTextTokens, setDeterministicIds, splitTemplate, styleString, styleToCss, synthesizeSampleData, synthesizeValue, templateSchema, textStyleLabel, toDate, toDisplayString, toHtml, toNumber, tokenChip, tokenize, truthy, typeCheck, typeCheckAst, usedBlockTypes, validateTemplate, walkTemplate, walkVNodes };
+export { type AnyVersionTemplate, type BinaryOp, type BindingInfo, type BindingKind, type BindingSpec, type BlockCategory, type BlockDefinition, type BlockNode, BlockRegistry, type BlockRegistryLike, type BlockStyle, type BorderSpec, type BorderStyle, type BreakMode, type BreakRun, CONDITION_OPERATORS, CURRENT_SCHEMA_VERSION, type CalcAggregate, type CalcOp, type CalcStep, type CalcTerm, type Calculation, type CardStyle, type ChangeArea, type ChangeKind, type ColorValue, type Command, CommandError, type Condition, type ConditionGroup, type ConditionRule, type ContainerSpec, type CreateNodeOptions, type CreateTemplateOptions, type CustomPageSize, DEFAULT_PAGE_CONTEXT, DEFAULT_THEME, type DataSource, type DiffOptions, type DispatchOptions, type DocumentStyles, type EditorState, EditorStore, type EditorStoreOptions, type EvalContext, type Expr, ExpressionError, FUNCTION_NAMES, type FieldSchema, type FieldType, type FlowOptions, type FontValue, type FormatContext, GLOBAL_SCHEMAS, type GeometryMap, type HistoryEntry, type InlineNode, type InspectorApi, type InspectorComponent, type InspectorField, type InspectorFieldBase, type InspectorSection, type Issue, type IssueCode, type IssueSeverity, type IssueSource, type LayoutWarning, type LibraryItem, type LicenseTier, type List, type ListItem, MIGRATIONS, type Measurer, type Migration, MigrationError, type MigrationResult, type Node, type NodeEntry, type NodeGeometry, type NodeIndex, type NodeLocation, type OutputCheckOptions, PAGE_SIZES_MM, PIPES, PX_PER_MM, type Page, type PageContext, type PageFragment, type PageGeometry, type PageMargins, type PageOrientation, type PageRegionSettings, type PageSettings, type PageSize, type PageSizeName, type PagedDocument, type PaginateOptions, type Paragraph, type ParseResult, type PathSegment, type PipeDefinition, type PipeFn, REGION_IDS, ROW_LAYOUTS, type RegionContent, type RegionId, type RegistryOptions, type RenderContext, type RenderMode, type RenderTreeOptions, type RepeatedHeader, type ReportData, type ReportTemplate, type ResolveHookContext, type ResolveOptions, type ResolvedDocument, type ResolvedFlow, type ResolvedNode, type ResolvedRegion, type ResolvedRole, type ResolvedSegment, type ResolvedStyle, type RichTextDoc, SchemaScope, type SchemaVersion, Scope, type SectionGeometry, type SelectOption, type Spacing, type SplitMode, type StyleCascadeInput, type StyleGroup, type TableRowGeometry, type TableStyle, type TemplateChange, type TemplateDiff, type TemplateMeta, type TemplateSegment, type TemplateSettings, type TextAlign, type TextMarks, type TextRun, type TextStyle, type TextStyleId, type Theme, type ThemeColors, type ThemeFontFace, type ThemeTableDefaults, type ThemeTokenInfo, type ThemeTypography, type TokenRef, type TokenRun, type TypeIssue, type TypeResult, type VChild, type VNode, type VProps, type ValidateContext, type ValidateOptions, type ValidationResult, type ValueType, type VerticalAlign, ancestors, applyCommand, bestBreak, bindingSpecsFor, blockStyleSchema, calcPaths, calcToAst, checkExpressionSyntax, checkOutput, classNames, cloneWithNewIds, collectPaths, columnWidth, compareValues, compileCondition, computePageGeometry, countNodes, createColumn, createId, createNode, createParagraph, createRichText, createRow, createSchemaScope, createSection, createTemplate, cssText, dataSourceSchemas, defaultDocumentStyles, defaultPageSettings, defaultPipeFor, defineBlock, describeExpression, diffTemplates, documentStylesSchema, escapeHtml, evaluate, evaluateAst, evaluateCondition, evaluateText, evaluateToText, exprToString, extractTemplateTokens, findNode, formatCurrency, formatDate, formatDatePattern, formatNumber, formatPercent, fromExpression, getField, getRegion, h, hasPipe, humaniseLabel, humanize, humanizeKey, indexTemplate, inlineFromTemplate, inlineToPlain, interpolate, isCalculation, isDarkColor, isDescendant, isEmptyValue, isPlainPath, isRichTextDoc, isSafeUrl, isTokenRef, isVNode, issue, itemSchemaOf, labelForPath, listAt, listThemeTokens, looseEquals, mergeTheme, migrateTemplate, missingThemeValues, mmToPx, needsMigration, nodeAt, nodeAttrs, nodeSchema, pageSettingsSchema, pageSizeMm, paginate, parseExpression, parseTemplate, pathToString, pxToMm, readProperty, readRegion, renderInline, renderNode, renderRichText, renderSections, renderSegments, resolveDefaultProps, resolvePath, resolvePathSchema, resolveStyle, resolveTemplate, resolveToken, resolveValue, richTextFromTemplate, richTextToPlain, richTextTokens, setDeterministicIds, splitTemplate, styleString, styleToCss, summariseDiff, synthesizeSampleData, synthesizeValue, templateSchema, textStyleLabel, toDate, toDisplayString, toExpression, toHtml, toNumber, tokenChip, tokenize, truthy, typeCheck, typeCheckAst, usedBlockTypes, validateTemplate, walkTemplate, walkVNodes, withDefaultPipe };