react-semaphor 0.1.514 → 0.1.516

package/dist/types/shared/format-utils/matrix-print.d.ts

@@ -0,0 +1,38 @@
+import { MatrixExportLayout, MatrixExportRow, MatrixPresentation } from '../analytics-protocol/index.js';
+/** How a printed Matrix organizes its rows (Plan 2, 2d, C1). */
+export type MatrixPrintOrganization = {
+    /** `tabular`: one column per row level. `outline`: one indented column. */
+    rowLabels: 'tabular' | 'outline';
+    /** Where each group's subtotal prints. */
+    subtotals: 'after' | 'before';
+};
+/** A report's organization: what a card PDF prints and a Document defaults to. */
+export declare const MATRIX_PRINT_ORGANIZATION_DEFAULTS: MatrixPrintOrganization;
+/**
+ * The presentation a Matrix prints with: its row labels and subtotal
+ * position. A tabular Matrix keeps its own label repetition; any other prints
+ * each label once. Grand totals, visibility, labels and formats are
+ * unchanged, so the rows and totals are the Matrix's own (E5).
+ */
+export declare function applyMatrixPrintOrganization(presentation: MatrixPresentation, organization: MatrixPrintOrganization): MatrixPresentation;
+/** Decimals a print default uses when a column has fractional values. */
+export declare const MATRIX_PRINT_DEFAULT_DECIMALS = 2;
+/**
+ * A numeric measure with no format of its own (no authored override and no
+ * semantic format) prints with grouping and fixed decimals: none when every
+ * value in the result is whole, else two. Authored and semantic formats are
+ * never replaced.
+ */
+export declare function applyMatrixPrintNumberDefaults(layout: MatrixExportLayout, rows: readonly MatrixExportRow[], presentation: MatrixPresentation): MatrixPresentation;
+/**
+ * Where a printed Matrix may break pages (Plan 2, P6): for each row, whether
+ * it must stay on the page of the row before it.
+ * - A total (subtotal or grand total) never starts a page.
+ * - A row that heads a group (an outline header row, or a subtotal printed
+ *   before its group) never ends a page.
+ * - A group's first row is never the only row of that group at the bottom of
+ *   a page when the group has more rows.
+ * A subtotal printed after its group therefore stays with the group's last
+ * row. The paginator decides what gives way when no allowed break fits.
+ */
+export declare function planMatrixKeepWithPrevious(rows: readonly MatrixExportRow[]): boolean[];

package/dist/types/shared/format-utils/pdf-table-layout/column-bands.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A column to place: its width, and the column group it belongs to, as an
+ * index into the table's groups in column order. `null` marks a row-label
+ * column, which repeats on every band.
+ */
+export type ColumnBandColumn = {
+    widthPx: number;
+    group: number | null;
+};
+/** One band: the columns it prints, in order, and the groups it covers. */
+export type ColumnBand = {
+    /** Row-label columns first, then the band's group columns. */
+    columns: number[];
+    firstGroup: number;
+    lastGroup: number;
+};
+export type ColumnBandPlan = {
+    kind: 'fits';
+} | {
+    kind: 'bands';
+    bands: ColumnBand[];
+}
+/** One group is wider than the page next to the row labels. */
+ | {
+    kind: 'too_wide';
+    reason: 'group';
+}
+/** It needs more bands than allowed. */
+ | {
+    kind: 'too_wide';
+    reason: 'bands';
+    bandCount: number;
+};
+/**
+ * Packs whole column groups, after the row-label columns, into bands no
+ * wider than `printableWidthPx`. A group is never split: a column member's
+ * measures stay together. Groups keep their order, and each band takes as
+ * many as fit.
+ */
+export declare function planColumnBands({ columns, printableWidthPx, maxBands, }: {
+    columns: readonly ColumnBandColumn[];
+    printableWidthPx: number;
+    maxBands: number;
+}): ColumnBandPlan;
+/**
+ * A band's caption: the column level, the members it covers, and their
+ * positions ("Yard: Tacoma to Newark (4 to 6 of 6)"). Documents and card PDFs
+ * caption bands alike.
+ */
+export declare function columnBandCaption({ groupLevelLabel, groupLabels, firstGroup, lastGroup, }: {
+    groupLevelLabel: string;
+    groupLabels: readonly string[];
+    firstGroup: number;
+    lastGroup: number;
+}): string;

package/dist/types/shared/format-utils/pdf-table-layout/index.d.ts

@@ -0,0 +1,6 @@
+export * from './page-size.js';
+export * from './table-page-geometry.js';
+export * from './table-column-widths.js';
+export * from './table-column-semantics.js';
+export * from './wide-table-layout.js';
+export * from './column-bands.js';

package/dist/types/shared/format-utils/pdf-table-layout/page-size.d.ts

@@ -0,0 +1,7 @@
+/** Page sizes Puppeteer's `page.pdf()` accepts, with its capitalization. */
+export type PdfPageSize = 'Letter' | 'Legal' | 'Tabloid' | 'Ledger' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6';
+/**
+ * Normalizes a page size in any case to Puppeteer's name. An unknown size
+ * warns and falls back to Letter.
+ */
+export declare function normalizePageSize(size?: string | null): PdfPageSize;

package/dist/types/shared/format-utils/pdf-table-layout/table-column-semantics.d.ts

@@ -0,0 +1,106 @@
+/**
+ * A table cell as the PDF renderer receives it: from the structured Fast PDF
+ * path or extracted from the rendered DOM. Every field is optional.
+ */
+export type PdfTableCellInput = {
+    text?: unknown;
+    colspan?: number | string;
+    rowspan?: number | string;
+    className?: string;
+    columnId?: string | null;
+    isHeader?: boolean;
+    isNumeric?: boolean;
+    pdfIsNumeric?: boolean;
+    measuredWidthPx?: number | string | null;
+    [key: string]: unknown;
+};
+export type PdfTableRowInput = {
+    type?: string;
+    cells?: PdfTableCellInput[];
+    [key: string]: unknown;
+};
+/** A header row: its cells, or an object that carries them. */
+export type PdfTableHeaderRowInput = PdfTableCellInput[] | {
+    cells?: PdfTableCellInput[];
+    [key: string]: unknown;
+};
+export type PdfTableColumnMeta = {
+    columnId?: string;
+    label?: unknown;
+    isNumeric?: boolean;
+    measuredWidthPx?: number;
+    [key: string]: unknown;
+};
+export type PdfTableMetadata = {
+    tableType?: string;
+    totalColumns?: number;
+    columns?: PdfTableColumnMeta[];
+    pivotLevels?: unknown;
+    rowLevels?: unknown;
+    [key: string]: unknown;
+};
+export type PdfTableData = {
+    headers?: PdfTableHeaderRowInput[];
+    rows?: PdfTableRowInput[];
+    grandTotal?: PdfTableRowInput | null;
+    metadata?: PdfTableMetadata;
+    [key: string]: unknown;
+};
+export type PdfTableModelOptions = {
+    suppressEmptyColumns?: boolean;
+    [key: string]: unknown;
+};
+/** A normalized cell. */
+export type PdfTableCell = {
+    text: string;
+    colspan: number;
+    rowspan: number;
+    className: string;
+    columnId: string | null;
+    isHeader: boolean;
+    isNumeric?: boolean;
+    pdfIsNumeric?: boolean;
+    measuredWidthPx?: number | null;
+    [key: string]: unknown;
+};
+export type PdfTableRow = {
+    cells: PdfTableCell[];
+    [key: string]: unknown;
+};
+/** One column of the table model, with its resolved meaning and widths. */
+export type PdfTableColumn = {
+    index: number;
+    sourceIndex: number;
+    columnId: string;
+    label: string;
+    type: string;
+    minWidthPx: number;
+    widthPx: number;
+    isNumeric: boolean;
+    declaredNumeric: boolean;
+};
+export type PdfTableProjection = {
+    headers: PdfTableRow[];
+    rows: PdfTableRow[];
+    grandTotal: PdfTableRow | null;
+    columns: PdfTableColumn[];
+};
+export type PdfTableModel = {
+    columns: PdfTableColumn[];
+    hiddenEmptyColumns: {
+        columnId: string;
+        label: string;
+    }[];
+    isPivotTable: boolean;
+    pivotAnchorCount: number;
+    project: (selectedModelIndices?: number[], options?: {
+        preserveHeaderHierarchy?: boolean;
+        preserveBodySpans?: boolean;
+    }) => PdfTableProjection;
+};
+/**
+ * Build the authoritative PDF table model once. Both structured Fast PDF and
+ * DOM-extracted inputs cross this same seam before fit or banded projection.
+ * The returned projector is the only supported way to derive render sections.
+ */
+export declare function buildPdfTableModel(tableData?: PdfTableData, options?: PdfTableModelOptions): PdfTableModel;

package/dist/types/shared/format-utils/pdf-table-layout/table-column-widths.d.ts

@@ -0,0 +1,13 @@
+export type PdfColumnType = 'boolean' | 'numeric' | 'datetime' | 'id' | 'text';
+export declare function getColumnWidthBounds(type?: string): Readonly<{
+    min: number;
+    max: number;
+}>;
+export declare function estimateColumnWidthPx({ type, label, sampleValues, grandTotalValue, measuredWidthPx, declaredNumeric, }?: {
+    type?: string;
+    label?: unknown;
+    sampleValues?: unknown[];
+    grandTotalValue?: unknown;
+    measuredWidthPx?: number | string | null;
+    declaredNumeric?: boolean;
+}): number;

package/dist/types/shared/format-utils/pdf-table-layout/table-page-geometry.d.ts

@@ -0,0 +1,19 @@
+/** Page margins and body padding for table PDFs. */
+export declare const TABLE_PAGE_GEOMETRY: Readonly<{
+    marginsMm: Readonly<{
+        top: 8;
+        right: 10;
+        bottom: 12;
+        left: 10;
+    }>;
+    printBodyPaddingMm: 0;
+}>;
+export declare function getTablePdfMargins(): {
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+};
+export declare function getTablePrintBodyPaddingCss(): string;
+/** The left and right margins plus body padding, in CSS pixels. */
+export declare function getTableHorizontalInsetPx(): number;

package/dist/types/shared/format-utils/pdf-table-layout/wide-table-layout.d.ts

@@ -0,0 +1,46 @@
+import { PdfPageSize } from './page-size.js';
+import { PdfTableData, PdfTableModelOptions, PdfTableRow } from './table-column-semantics.js';
+export type WideTableStrategy = 'auto' | 'fit' | 'horizontal_paginate';
+export type PdfPageOrientation = 'portrait' | 'landscape';
+export type WideTableLayoutOptions = PdfTableModelOptions & {
+    pageSize?: string;
+    orientation?: string;
+    wideTableStrategy?: string;
+};
+export type WideTableSectionColumn = {
+    columnId: string;
+    label: string;
+    widthPx: number;
+    isNumeric: boolean;
+};
+/** One printed table: the whole table, or one band of a wide one. */
+export type WideTableSection = {
+    headers: PdfTableRow[];
+    rows: PdfTableRow[];
+    grandTotal: PdfTableRow | null;
+    bandLabel: string | null;
+    columns: WideTableSectionColumn[];
+};
+export type WideTableLayout = {
+    sections: WideTableSection[];
+    layoutApplied: {
+        requestedPageSize: PdfPageSize;
+        requestedOrientation: PdfPageOrientation;
+        effectivePageSize: PdfPageSize;
+        effectiveOrientation: PdfPageOrientation;
+        usedBanding: boolean;
+        bandCount: number;
+        totalColumns: number;
+        anchorColumns: string[];
+        autoAdjustedLayout: boolean;
+        strategyApplied: 'fit' | 'horizontal_paginate';
+        hiddenEmptyColumnCount: number;
+        hiddenEmptyColumns: string[];
+    };
+};
+/**
+ * Lays a table out on paper: it fits on the requested page, or on a wider or
+ * landscape page, or it prints in column bands that repeat the anchor
+ * (row label) columns.
+ */
+export declare function buildWideTableLayout(tableData: PdfTableData, options?: WideTableLayoutOptions): WideTableLayout;

package/dist/types/shared/format-utils/presentation-execution.d.ts

@@ -2,7 +2,7 @@ import { ResolvedRawTemporalFormat } from './raw-temporal.js';
 import { ReportRuntimeContext } from '../report-runtime-context/index.js';
 import { NumericPresentationTarget } from './numeric-presentation.js';
 import { ResolvedTemporalBucketFormat } from './temporal-bucket.js';
-import { NumericCanonicalFormat } from './types/index.js';
+import { DurationCanonicalFormat, MeasureCanonicalFormat, NumericCanonicalFormat } from './types/index.js';
 export type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -25,6 +25,11 @@ export type ResolvedNumericPresentationEntry = {
     target: NumericPresentationTarget;
     format: NumericCanonicalFormat;
 };
+export type ResolvedDurationPresentationEntry = {
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+    format: DurationCanonicalFormat;
+};
 export type ResolvedTemporalBucketPresentationEntry = {
     scope: PresentationScope;
     target: TemporalBucketPresentationTarget;
@@ -39,7 +44,7 @@ export type ResolvedRawTemporalPresentationEntry = {
     target: RawTemporalPresentationTarget;
     format: ResolvedRawTemporalFormat;
 };
-export type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
+export type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedDurationPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
 export type PresentationExecutionSnapshot = {
     version: 1;
     reportContext: ReportRuntimeContext;
@@ -67,6 +72,16 @@ export declare function findResolvedNumericFormat(input: {
     scope: PresentationScope;
     target: NumericPresentationTarget;
 }): NumericCanonicalFormat | undefined;
+/**
+ * Finds the resolved numeric or duration format for a measure target. Value
+ * formatters use this; `findResolvedNumericFormat` is for numeric-only
+ * consumers such as precision and currency lookups.
+ */
+export declare function findResolvedMeasureFormat(input: {
+    snapshot: PresentationExecutionSnapshot;
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+}): MeasureCanonicalFormat | undefined;
 export declare function findResolvedRawTemporalFormat(input: {
     snapshot: PresentationExecutionSnapshot;
     scope: PresentationScope;

package/dist/types/shared/format-utils/table-structure.d.ts

@@ -27,6 +27,8 @@ export type FastPathDataRow = {
     type?: string;
     subtotalLevel?: string | null;
     index?: number;
+    /** A printed Matrix row that must stay on the page of the row before (P6). */
+    keepWithPrevious?: boolean;
     cells: FastPathTableCell[];
 };
 export type FastPathGrandTotal = {
@@ -39,5 +41,12 @@ export type FastPathTableStructure = {
     metadata?: Record<string, unknown> & {
         columnOrder?: string[];
         columns?: FastPathColumnHint[];
+        /**
+         * A printed Matrix's column groups, which bands never split: per column,
+         * its group index, or `null` for a row-label column.
+         */
+        columnGroups?: readonly (number | null)[];
+        groupLabels?: readonly string[];
+        groupLevelLabel?: string;
     };
 };

package/dist/types/shared/format-utils/types/format-types.d.ts

@@ -51,6 +51,12 @@ export type DurationCanonicalFormat = {
     suffix?: string;
     negativeStyle?: 'minus' | 'parentheses';
 };
+/**
+ * Formats a table measure value can resolve to: a numeric style, or a
+ * duration rendered from a numeric amount of `inputUnit`. Every surface that
+ * renders a measure value (table cells, totals, exports) must accept both.
+ */
+export type MeasureCanonicalFormat = NumericCanonicalFormat | DurationCanonicalFormat;
 export type StringCanonicalFormat = {
     type: 'string';
     prefix?: string;
@@ -58,6 +64,7 @@ export type StringCanonicalFormat = {
 };
 export type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | RawTemporalFormat | DurationCanonicalFormat | StringCanonicalFormat | TemporalBucketFormat;
 export declare function isNumericCanonicalFormat(format: unknown): format is NumericCanonicalFormat;
+export declare function isMeasureCanonicalFormat(format: unknown): format is MeasureCanonicalFormat;
 export interface NumberFormatOptions {
     style: 'decimal' | 'currency' | 'percent' | 'scientific';
     locale?: string;
@@ -113,18 +120,26 @@ export interface DateFormatOptions {
     /** Locale for date formatting */
     locale?: string;
 }
+export type ColumnNumberStyle = 'decimal' | 'currency' | 'percent' | 'scientific' | 'duration';
+/** Duration options on a table column (`numberFormat.style: 'duration'`). */
+export type ColumnDurationFormat = Pick<DurationCanonicalFormat, 'inputUnit' | 'outputStyle' | 'largestUnit' | 'smallestUnit' | 'maxUnits'>;
 export interface ColumnSettings {
     type: 'none' | 'text' | 'number' | 'date' | 'badge' | 'link' | 'progress';
     textAlign?: 'left' | 'center' | 'right';
     width?: number;
     numberFormat?: {
-        style: 'decimal' | 'currency' | 'percent' | 'scientific';
+        style: ColumnNumberStyle;
         currency?: string;
         locale?: string;
         minimumFractionDigits?: number;
         maximumFractionDigits?: number;
         useGrouping?: boolean;
         percentValueMode?: 'fraction' | 'whole';
+        prefix?: string;
+        suffix?: string;
+        negativeStyle?: 'minus' | 'parentheses';
+        /** Duration options; read only when `style` is `duration`. */
+        duration?: ColumnDurationFormat;
         showDataBar?: boolean;
         dataBarColor?: string;
         dataBarMinValue?: number;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.514",
+  "version": "0.1.516",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -132,6 +132,11 @@
       "import": "./dist/pdf-export-policy/index.js",
       "require": "./dist/pdf-export-policy/index.cjs"
     },
+    "./format-utils/pdf-table-layout": {
+      "types": "./dist/types/pdf-table-layout.d.ts",
+      "import": "./dist/pdf-table-layout/index.js",
+      "require": "./dist/pdf-table-layout/index.cjs"
+    },
     "./value-format-preferences": {
       "types": "./dist/types/value-format-preferences.d.ts",
       "import": "./dist/value-format-preferences/index.js",