react-semaphor 0.1.515 → 0.1.516

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/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/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';