react-semaphor 0.1.514 → 0.1.516

package/dist/types/shared/analytics-protocol/matrix-definition-contract.d.ts

@@ -794,9 +794,12 @@ declare const analyticalIntentShape: z.ZodObject<{
 type MatrixAnalyticalIntentSchema = z.ZodEffects<typeof analyticalIntentShape>;
 /** Analytical definition only; acquisition windows are sibling operation inputs. */
 export declare const matrixAnalyticalIntentSchema: MatrixAnalyticalIntentSchema;
+/** The placeholder a subtotal label uses for its member's name. */
+export declare const MATRIX_TOTAL_MEMBER_PLACEHOLDER = "{member}";
 export declare const matrixTotalPresentationSchema: z.ZodObject<{
     visible: z.ZodBoolean;
     position: z.ZodEnum<["before", "after"]>;
+    /** As written; a subtotal's `{member}` becomes its member's name. */
     label: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     visible: boolean;
@@ -2255,6 +2258,7 @@ declare const presentationFields: {
             grand: z.ZodObject<{
                 visible: z.ZodBoolean;
                 position: z.ZodEnum<["before", "after"]>;
+                /** As written; a subtotal's `{member}` becomes its member's name. */
                 label: z.ZodOptional<z.ZodString>;
             }, "strict", z.ZodTypeAny, {
                 visible: boolean;
@@ -2268,6 +2272,7 @@ declare const presentationFields: {
             levels: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodObject<{
                 visible: z.ZodBoolean;
                 position: z.ZodEnum<["before", "after"]>;
+                /** As written; a subtotal's `{member}` becomes its member's name. */
                 label: z.ZodOptional<z.ZodString>;
             }, "strict", z.ZodTypeAny, {
                 visible: boolean;
@@ -2278,6 +2283,11 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>>;
+            /**
+             * Skip a subtotal that only repeats one row: an expanded group with
+             * exactly one child shows no subtotal. Off when absent.
+             */
+            skipRedundant: z.ZodOptional<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             grand: {
                 visible: boolean;
@@ -2289,6 +2299,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         }, {
             grand: {
                 visible: boolean;
@@ -2300,11 +2311,13 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         }>;
         columns: z.ZodObject<{
             grand: z.ZodObject<{
                 visible: z.ZodBoolean;
                 position: z.ZodEnum<["before", "after"]>;
+                /** As written; a subtotal's `{member}` becomes its member's name. */
                 label: z.ZodOptional<z.ZodString>;
             }, "strict", z.ZodTypeAny, {
                 visible: boolean;
@@ -2318,6 +2331,7 @@ declare const presentationFields: {
             levels: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodObject<{
                 visible: z.ZodBoolean;
                 position: z.ZodEnum<["before", "after"]>;
+                /** As written; a subtotal's `{member}` becomes its member's name. */
                 label: z.ZodOptional<z.ZodString>;
             }, "strict", z.ZodTypeAny, {
                 visible: boolean;
@@ -2328,6 +2342,11 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>>;
+            /**
+             * Skip a subtotal that only repeats one row: an expanded group with
+             * exactly one child shows no subtotal. Off when absent.
+             */
+            skipRedundant: z.ZodOptional<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             grand: {
                 visible: boolean;
@@ -2339,6 +2358,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         }, {
             grand: {
                 visible: boolean;
@@ -2350,6 +2370,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         }>;
     }, "strict", z.ZodTypeAny, {
         columns: {
@@ -2363,6 +2384,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         };
         rows: {
             grand: {
@@ -2375,6 +2397,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         };
     }, {
         columns: {
@@ -2388,6 +2411,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         };
         rows: {
             grand: {
@@ -2400,6 +2424,7 @@ declare const presentationFields: {
                 position: "before" | "after";
                 label?: string | undefined;
             }>>;
+            skipRedundant?: boolean | undefined;
         };
     }>;
     conditionalFormatting: z.ZodOptional<z.ZodEffects<z.ZodObject<{
@@ -3907,6 +3932,7 @@ declare const definitionInputShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -3919,6 +3945,7 @@ declare const definitionInputShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -4306,6 +4333,7 @@ declare const definitionInputShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -4318,6 +4346,7 @@ declare const definitionInputShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -4714,6 +4743,7 @@ declare const configShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -4726,6 +4756,7 @@ declare const configShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -5046,6 +5077,7 @@ declare const configShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -5058,6 +5090,7 @@ declare const configShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -5388,6 +5421,7 @@ declare const authoringConfigShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -5400,6 +5434,7 @@ declare const authoringConfigShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -5720,6 +5755,7 @@ declare const authoringConfigShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -5732,6 +5768,7 @@ declare const authoringConfigShape: z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -6158,6 +6195,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -6170,6 +6208,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -6494,6 +6533,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -6506,6 +6546,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -6836,6 +6877,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -6848,6 +6890,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -7127,6 +7170,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -7139,6 +7183,7 @@ declare const exportRequestShape: z.ZodUnion<[z.ZodObject<{
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {

package/dist/types/shared/analytics-protocol/matrix-member-presentation.d.ts

@@ -10,6 +10,10 @@ export declare function resolveMatrixMemberPresentation(input: {
     total?: MatrixTotalPresentation;
     childrenEmpty?: boolean;
     rowLayout?: 'compact' | 'tabular';
+    /** The axis's `totals.skipRedundant`. */
+    skipRedundant?: boolean;
+    /** The group has exactly one child: its first child page holds one member and no cursor after it. */
+    singleChild?: boolean;
 }): {
     expandable: boolean;
     expanded: boolean;

package/dist/types/shared/dashboard-authoring/document-section-cards.d.ts

@@ -0,0 +1,56 @@
+import { DocumentSection, TCard, TDashboard } from '../../lib/types/common-types.js';
+/**
+ * The one traversal of cards inside Document sections, shared by the package
+ * and the app. Read with `getDocumentSectionCards`, rewrite with
+ * `mapDocumentSectionCards`, and list every executable card with
+ * `listDashboardCardLocations`.
+ *
+ * These accept the V1 document shape (`document.sections`) only. Raw stored
+ * templates, including the V2 `document.body.sections` fallback, are checked
+ * by the app's structural validator before they reach these helpers.
+ */
+/** Most cards a KPI section holds. */
+export declare const DOCUMENT_KPI_SECTION_MAX_CARDS = 8;
+/** Most cards a KPI section in the `tiles` layout may hold. More need `lines`. */
+export declare const DOCUMENT_KPI_SECTION_MAX_TILES = 6;
+/** Every card a section owns, in display order: `[card]` for table and chart, `cards` for KPI. */
+export declare function getDocumentSectionCards(section: DocumentSection): readonly TCard[];
+/**
+ * The same section with each card mapped. Returns the input section when no
+ * card changed, so callers can compare by reference.
+ */
+export declare function mapDocumentSectionCards(section: DocumentSection, map: (card: TCard) => TCard): DocumentSection;
+/** Where an executable card lives in a dashboard. */
+export type DashboardCardLocation = {
+    kind: 'sheetCard';
+    sheetId: string;
+    cardId: string;
+    card: TCard;
+} | {
+    kind: 'frameCard';
+    sheetId: string;
+    frameId: string;
+    cardId: string;
+    card: TCard;
+} | {
+    kind: 'documentSectionCard';
+    sheetId: string;
+    sectionId: string;
+    cardId: string;
+    card: TCard;
+};
+/**
+ * Every executable card location in a dashboard, sheet by sheet: sheet cards,
+ * then frame cards, then document section cards (every KPI card included).
+ */
+export declare function listDashboardCardLocations(dashboard: Pick<TDashboard, 'sheets'>): readonly DashboardCardLocation[];
+export type DocumentSectionShapeIssue = {
+    /** Path relative to the section, for example `cards[2].type`. Empty for the section itself. */
+    path: string;
+    message: string;
+};
+/**
+ * Structural rules for a stored KPI section, for persistence boundaries that
+ * receive untrusted JSON. Returns no issues for a valid section.
+ */
+export declare function getDocumentKpiSectionShapeIssues(section: unknown): DocumentSectionShapeIssue[];

package/dist/types/shared/dashboard-authoring/index.d.ts

@@ -10,6 +10,7 @@ export * from './temporal-result-owner.js';
 export * from './temporal-bucket-authoring.js';
 export * from './canonical-result-keys.js';
 export * from './dashboard-card-source-index.js';
+export * from './document-section-cards.js';
 export * from './dashboard-filter-mapping-types.js';
 export * from './dashboard-filter-automatic-target.js';
 export * from './dashboard-filter-sql-subscription.js';

package/dist/types/shared/dashboard-authoring/matrix-delivery.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { MatrixConfig, MatrixViewState, MatrixExportRequest } from '../analytics-protocol/index.js';
+import { MatrixConfig, MatrixExportLayout, MatrixExportRequest, MatrixExportRow, MatrixFailure, MatrixViewState } from '../analytics-protocol/index.js';
 import { ReportRuntimeContext } from '../report-runtime-context/index.js';
 export type MatrixExportContent = 'current' | 'all' | 'flat';
 export declare function captureMatrixExport(input: {
@@ -23,6 +23,7 @@ export declare function captureMatrixExport(input: {
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -35,6 +36,7 @@ export declare function captureMatrixExport(input: {
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -373,6 +375,7 @@ export declare function captureMatrixExport(input: {
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
             rows: {
                 grand: {
@@ -385,6 +388,7 @@ export declare function captureMatrixExport(input: {
                     position: "before" | "after";
                     label?: string | undefined;
                 }>>;
+                skipRedundant?: boolean | undefined;
             };
         };
         layout: {
@@ -803,6 +807,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                     rows: {
                         grand: {
@@ -815,6 +820,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                 };
                 layout: {
@@ -1153,6 +1159,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                     rows: {
                         grand: {
@@ -1165,6 +1172,7 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
                             position: "before" | "after";
                             label?: string | undefined;
                         }>>;
+                        skipRedundant?: boolean | undefined;
                     };
                 };
                 layout: {
@@ -1451,3 +1459,30 @@ export declare function buildMatrixDeliveryEnvelope<TSource extends {
         acquisition?: "continuation" | undefined;
     };
 };
+/**
+ * The full Matrix result a Document prints (tech spec D-M1), read from the
+ * delivery-authorized layout route. `request` is the effective definition that
+ * ran (after control resolution), so rows are formatted exactly as the PDF path
+ * formats them. A failure never carries rows.
+ */
+export type MatrixLayoutReadResult = {
+    status: 'ok';
+    request: MatrixExportRequest;
+    layout: MatrixExportLayout;
+    rows: readonly MatrixExportRow[];
+    usage: {
+        rows: number;
+        cells: number;
+        bytes: number;
+    };
+} | {
+    status: 'failed';
+    failure: {
+        code: MatrixFailure['code'];
+        /** Set when a retained-result budget tripped. */
+        limit?: 'rows' | 'bytes';
+        message: string;
+        retryable: boolean;
+    };
+};
+export declare const matrixLayoutReadResultSchema: z.ZodType<MatrixLayoutReadResult, z.ZodTypeDef, unknown>;

package/dist/types/shared/format-utils/formatters/duration-formatter.d.ts

@@ -1,2 +1,5 @@
-import { DurationFormatOptions } from '../types/index.js';
+import { DurationCanonicalFormat, DurationFormatOptions } from '../types/index.js';
+import { ExactNumericValue } from '../../analytics-protocol/scalar-value.js';
 export declare function formatDuration(value: number | string | null | undefined, options?: DurationFormatOptions): string;
+/** Formats a value with a canonical duration format. */
+export declare function formatDurationCanonical(value: number | ExactNumericValue | string | null | undefined, format: DurationCanonicalFormat): string;

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

@@ -1,5 +1,5 @@
-export { formatNumber, formatCurrency, formatPercent, formatScientific, formatNumericCanonical, formatNumberWithColumnSettings, formatNumberCustom, } from './number-formatter.js';
-export { formatDuration } from './duration-formatter.js';
+export { formatNumber, formatCurrency, formatPercent, formatScientific, formatNumericCanonical, formatMeasureCanonical, formatNumberWithColumnSettings, formatNumberCustom, } from './number-formatter.js';
+export { formatDuration, formatDurationCanonical } from './duration-formatter.js';
 export { formatMetricComparison, type FormattedMetricComparison, type FormattedMetricComparisonPart, type FormatMetricComparisonOptions, type MetricComparisonDisplayMode, } from './metric-comparison-formatter.js';
 export { formatDate, formatRelativeTime, resolveTimezone, getTimezoneAbbreviation, getTimezoneName, parseWithSourceTimezone, } from './date-formatter.js';
 export { formatCellValue, formatRowForExport } from './cell-formatter.js';

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

@@ -2,6 +2,11 @@ import { MatrixPath, MatrixPresentation, MatrixWindow, SemaphorScalarValue, Sema
 import { ReportRuntimeContext } from '../../report-runtime-context/index.js';
 /** Null hierarchy members stay identifiable even when null cells render blank. */
 export declare function matrixMemberLabel(path: MatrixPath, levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
+/**
+ * The one label every surface gives a total row or column. An authored
+ * subtotal label is used as written, with each `{member}` replaced by the
+ * member's label ("Total for {member}").
+ */
 export declare function matrixTotalLabel(role: 'member' | 'subtotal' | 'grand_total', text: string, authored?: string): string;
 export declare function matrixAxisLabel(path: MatrixPath, role: 'member' | 'subtotal' | 'grand_total', totals: MatrixPresentation['totals']['rows'], levels?: ReadonlyMap<string, (value: SemaphorScalarValue) => string>): string;
 /** Acquired absence is presentation; pending/error states remain the caller's UI. */

package/dist/types/shared/format-utils/formatters/number-formatter.d.ts

@@ -1,4 +1,4 @@
-import { FormatOptions, NumberFormatOptions, NumericCanonicalFormat } from '../types/index.js';
+import { ColumnDurationFormat, ColumnNumberStyle, FormatOptions, MeasureCanonicalFormat, NumberFormatOptions, NumericCanonicalFormat } from '../types/index.js';
 import { ExactNumericValue } from '../../analytics-protocol/scalar-value.js';
 type NumericValue = number | ExactNumericValue;
 /**
@@ -21,12 +21,17 @@ export declare function formatPercent(value: NumericValue | null | undefined, op
  */
 export declare function formatScientific(value: NumericValue | null | undefined, options?: NumberFormatOptions): string;
 export declare function formatNumericCanonical(value: number | ExactNumericValue | null | undefined, format: NumericCanonicalFormat): string;
+/**
+ * Formats a table measure value with its resolved format: numeric styles go
+ * through `formatNumericCanonical`, durations through the duration formatter.
+ */
+export declare function formatMeasureCanonical(value: number | ExactNumericValue | null | undefined, format: MeasureCanonicalFormat): string;
 /**
  * Format a number value based on ColumnSettings.numberFormat
  * Used for export formatting
  */
 export declare function formatNumberWithColumnSettings(value: number | ExactNumericValue | null | undefined, numberFormat: {
-    style?: 'decimal' | 'currency' | 'percent' | 'scientific';
+    style?: ColumnNumberStyle;
     currency?: string;
     locale?: string;
     minimumFractionDigits?: number;
@@ -38,6 +43,7 @@ export declare function formatNumberWithColumnSettings(value: number | ExactNume
     negativeStyle?: 'minus' | 'parentheses';
     prefix?: string;
     suffix?: string;
+    duration?: ColumnDurationFormat;
 } | undefined, defaultLocale?: string): string;
 /**
  * Legacy wrapper for backward compatibility with existing code

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

@@ -18,6 +18,7 @@ export * from './exporters/index.js';
 export * from './export-policy.js';
 export * from './matrix-continuation.js';
 export * from './matrix-export-presentation.js';
+export * from './matrix-print.js';
 export { fromSemanticFormat } from './semantic-format.js';
 export type * from './table-structure.js';
 export * from './pdf-export-policy.js';