react-semaphor 0.1.515 → 0.1.516

package/dist/types/components/text-variables/variable-picker.d.ts

@@ -0,0 +1,27 @@
+import { TextVariableKind, TextVariableOption, TextVariableSelection } from '../../lib/text-variables/text-variable-types.js';
+export declare function TextVariableKindIcon({ kind, className, }: {
+    kind: TextVariableKind;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+type VariablePickerProps = {
+    options: readonly TextVariableOption[];
+    /** What the chip shows now (editing a chip). */
+    selection?: TextVariableSelection;
+    /** The chip's input no longer exists. */
+    missing?: boolean;
+    /**
+     * `search`: the picker has its own search box. `typeahead`: the text typed
+     * after {{ is the search, and the editor keeps focus.
+     */
+    mode: {
+        kind: 'search';
+    } | {
+        kind: 'typeahead';
+        query: string;
+        activeOptionId?: string;
+    };
+    onPick: (selection: TextVariableSelection) => void;
+    onRemove?: () => void;
+};
+export declare function VariablePicker({ options, selection, missing, mode, onPick, onRemove, }: VariablePickerProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/visual/settings/table-presentation-settings.d.ts

@@ -4,6 +4,10 @@ import { ReactNode } from 'react';
 type TablePresentationSettingsProps = {
     style: ResolvedTablePresentationStyle;
     onDensityChange: (density: TableDensity) => void;
+    /** The densities offered, in order. Defaults to all of them. A current
+     * value outside the list is still shown, so nothing changes until the
+     * author picks. */
+    densityOptions?: readonly TableDensity[];
     onStyleChange: (update: Partial<TableStylePreferences>) => void;
     totals?: {
         enabled?: boolean;
@@ -20,8 +24,30 @@ type TablePresentationSettingsProps = {
      * the surrounding "Appearance" tab can hand custom content in without
      * forking the layout. */
     extraSection?: ReactNode;
+    /** What the totals colors reset to; a Document passes its own. */
+    totalsDefaults?: Required<TableTotalsStylePreferences>;
+    /** The top-rule styles offered; a Document leaves out Double. */
+    totalsBorderStyleOptions?: readonly Required<TableTotalsStylePreferences>['borderTopStyle'][];
     onReset?: () => void;
     className?: string;
 };
-export declare function TablePresentationSettings({ style, onDensityChange, onStyleChange, totals, showFullStyle, showBorderStyle, extraSection, onReset, className, }: TablePresentationSettingsProps): import("react/jsx-runtime").JSX.Element;
+export declare function TablePresentationSettings({ style, onDensityChange, densityOptions, onStyleChange, totals, showFullStyle, showBorderStyle, extraSection, totalsDefaults, totalsBorderStyleOptions, onReset, className, }: TablePresentationSettingsProps): import("react/jsx-runtime").JSX.Element;
+export declare function TableSettingsSection({ label, action, children, }: {
+    label: string;
+    /** Optional right-aligned slot in the section header — use for a master
+     * toggle that gates the whole section (e.g. "Show totals row"). The
+     * styling rows below should only render when the master is on. */
+    action?: ReactNode;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function TableSettingsRow({ label, htmlFor, children, }: {
+    label: string;
+    htmlFor?: string;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function TableSettingsSwitchRow({ label, checked, onCheckedChange, }: {
+    label: string;
+    checked: boolean;
+    onCheckedChange: (checked: boolean) => void;
+}): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("../chunks/common-types-nBuCd3u2.cjs"),e=require("../chunks/validators-DVYAnnX0.cjs"),t=require("../chunks/field-dependencies-DIab72rQ.cjs"),r=require("../chunks/token-types-Ahh5u4iT.cjs"),l=require("../chunks/pivot-result-identity-uTiylUNr.cjs"),o=require("../chunks/report-runtime-context-DzvHBPxl.cjs"),i=["concatenate","conditional-category","date-part","date-difference","null-to-zero","safe-ratio","nested-conditional","membership-test","uppercase","lowercase","trim-whitespace","replace-text","first-characters","character-count","starts-with","number-to-text","start-of-month","start-of-quarter","start-of-year","year-number","add-days","round-number","round-down","round-up","absolute-value","cap-maximum","floor-minimum","fill-blanks","null-if-zero","is-blank"];exports.CONTROL_CARD_DEFAULT_VALUE=a.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=a.EMPTY_SELECTION;exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.LEGACY_CALCULATED_FIELD_ENTITY_MARKER=e.LEGACY_CALCULATED_FIELD_ENTITY_MARKER;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getCalculatedFieldComputeStage=e.getCalculatedFieldComputeStage;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.hasSyntheticCalculatedFieldOwner=e.hasSyntheticCalculatedFieldOwner;exports.inspectCalculatedField=e.inspectCalculatedField;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedMetric=e.isCalculatedMetric;exports.isDerivedField=e.isDerivedField;exports.normalizeCalculatedFieldRepresentation=e.normalizeCalculatedFieldRepresentation;exports.shouldDropInheritedCalculationAggregate=e.shouldDropInheritedCalculationAggregate;exports.collectDatasetNamesFromExplorerField=t.collectDatasetNamesFromExplorerField;exports.collectDatasetNamesFromFilterGroup=t.collectDatasetNamesFromFilterGroup;exports.collectExecutionDatasetNamesFromExplorerField=t.collectExecutionDatasetNamesFromExplorerField;exports.collectPreferredDatasetNamesFromExplorerField=t.collectPreferredDatasetNamesFromExplorerField;exports.collectQualifiedDatasetNamesFromExplorerField=t.collectQualifiedDatasetNamesFromExplorerField;exports.datasetRefFromSource=t.datasetRefFromSource;exports.dependencyDisplayIdentity=t.dependencyDisplayIdentity;exports.humanizeDatasetName=t.humanizeDatasetName;exports.resolveFieldDatasetDependencies=t.resolveFieldDatasetDependencies;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=r.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=l.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=l.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=o.DEFAULT_CALENDAR_CONTEXT;exports.CALCULATED_FIELD_TEMPLATE_IDS=i;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=require("../chunks/common-types-nBuCd3u2.cjs"),e=require("../chunks/validators-DFeDcdpA.cjs"),t=require("../chunks/field-dependencies-EB485TdB.cjs"),r=require("../chunks/token-types-aWrzwonf.cjs"),l=require("../chunks/pivot-result-identity-gquWljbd.cjs"),o=require("../chunks/report-runtime-context-CzSrCBsu.cjs"),i=["concatenate","conditional-category","date-part","date-difference","null-to-zero","safe-ratio","nested-conditional","membership-test","uppercase","lowercase","trim-whitespace","replace-text","first-characters","character-count","starts-with","number-to-text","start-of-month","start-of-quarter","start-of-year","year-number","add-days","round-number","round-down","round-up","absolute-value","cap-maximum","floor-minimum","fill-blanks","null-if-zero","is-blank"];exports.CONTROL_CARD_DEFAULT_VALUE=a.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=a.EMPTY_SELECTION;exports.CALCULATED_FIELD_ENTITY_MARKER=e.CALCULATED_FIELD_ENTITY_MARKER;exports.DATE_FORMAT_VALUES=e.DATE_FORMAT_VALUES;exports.LEGACY_CALCULATED_FIELD_ENTITY_MARKER=e.LEGACY_CALCULATED_FIELD_ENTITY_MARKER;exports.PivotMarkerEnum=e.PivotMarkerEnum;exports.getCalculatedFieldComputeStage=e.getCalculatedFieldComputeStage;exports.getFieldRuntimeColumnName=e.getFieldRuntimeColumnName;exports.hasCalculatedFieldMarker=e.hasCalculatedFieldMarker;exports.hasCalculatedFormulaInputs=e.hasCalculatedFormulaInputs;exports.hasSyntheticCalculatedFieldOwner=e.hasSyntheticCalculatedFieldOwner;exports.inspectCalculatedField=e.inspectCalculatedField;exports.isCalculatedDimension=e.isCalculatedDimension;exports.isCalculatedMetric=e.isCalculatedMetric;exports.isDerivedField=e.isDerivedField;exports.normalizeCalculatedFieldRepresentation=e.normalizeCalculatedFieldRepresentation;exports.shouldDropInheritedCalculationAggregate=e.shouldDropInheritedCalculationAggregate;exports.collectDatasetNamesFromExplorerField=t.collectDatasetNamesFromExplorerField;exports.collectDatasetNamesFromFilterGroup=t.collectDatasetNamesFromFilterGroup;exports.collectExecutionDatasetNamesFromExplorerField=t.collectExecutionDatasetNamesFromExplorerField;exports.collectPreferredDatasetNamesFromExplorerField=t.collectPreferredDatasetNamesFromExplorerField;exports.collectQualifiedDatasetNamesFromExplorerField=t.collectQualifiedDatasetNamesFromExplorerField;exports.datasetRefFromSource=t.datasetRefFromSource;exports.dependencyDisplayIdentity=t.dependencyDisplayIdentity;exports.humanizeDatasetName=t.humanizeDatasetName;exports.resolveFieldDatasetDependencies=t.resolveFieldDatasetDependencies;exports.DEFAULT_SEMANTIC_DOMAIN_ACCESS=r.DEFAULT_SEMANTIC_DOMAIN_ACCESS;exports.resolveQueryColumnKeyMapEntry=l.resolveQueryColumnKeyMapEntry;exports.resolveUniqueQueryColumnKeyMapEntry=l.resolveUniqueQueryColumnKeyMapEntry;exports.DEFAULT_CALENDAR_CONTEXT=o.DEFAULT_CALENDAR_CONTEXT;exports.CALCULATED_FIELD_TEMPLATE_IDS=i;

package/dist/types/index.js

@@ -1,9 +1,9 @@
 import { C as r, E as s } from "../chunks/common-types-C6cAQgyh.js";
-import { C as o, D as i, L as n, P as c, f as d, g as m, k as u, j as E, l as p, e as C, c as D, b as F, d as A, n as f, h as _ } from "../chunks/validators-CkHsAvwB.js";
-import { c as T, g as h, f as x, b as N, e as y, d as I, a as M, h as R, r as b } from "../chunks/field-dependencies-DXW4jtvJ.js";
-import { D as S } from "../chunks/token-types-Dl0hcKBX.js";
-import { r as O, a as v } from "../chunks/pivot-result-identity-8M-bZrw9.js";
-import { D as w } from "../chunks/report-runtime-context-Cs65Mrxj.js";
+import { C as o, D as i, L as n, P as c, f as d, g as m, k as u, j as E, l as p, e as C, c as D, b as F, d as A, n as f, h as _ } from "../chunks/validators-CsdOtZI6.js";
+import { c as T, g as h, f as x, b as N, e as y, d as I, a as M, h as R, r as b } from "../chunks/field-dependencies-v-lJNzC7.js";
+import { D as S } from "../chunks/token-types-BC6RcUY8.js";
+import { r as O, a as v } from "../chunks/pivot-result-identity-BzUQiCEV.js";
+import { D as w } from "../chunks/report-runtime-context-CxIoGyNM.js";
 const e = [
   "concatenate",
   "conditional-category",

package/dist/types/lib/dashboard-inputs/text-variable-options.d.ts

@@ -0,0 +1,15 @@
+import { DashboardInputVariableRef, ResolvedDashboardInputContext } from '../types/common-types.js';
+import { TextVariableChipFace, TextVariableOption, TextVariableSelection } from '../text-variables/text-variable-types.js';
+/** What resolves a reference to its input. */
+type DashboardVariableLookup = Pick<ResolvedDashboardInputContext, 'variablesById' | 'variablesByName'>;
+/** The dashboard inputs a text visual can show, each part with its value now. */
+export declare function getDashboardTextVariableOptions(context?: Pick<ResolvedDashboardInputContext, 'resolvedInputs'>): TextVariableOption[];
+/** What a reference shows, as the picker names it; undefined when missing. */
+export declare function getDashboardVariableSelection(ref: DashboardInputVariableRef, context?: DashboardVariableLookup): TextVariableSelection | undefined;
+/** The reference a picker selection stands for. */
+export declare function getDashboardVariableRefFromSelection(selection: TextVariableSelection): DashboardInputVariableRef;
+/** How a reference reads as a chip: the input's name, or Missing input. */
+export declare function getDashboardVariableChipFace(ref: DashboardInputVariableRef, context?: DashboardVariableLookup): TextVariableChipFace;
+/** `name.part`, for copying a variable as a typed token. */
+export declare function getDashboardVariableToken(ref: DashboardInputVariableRef, context?: DashboardVariableLookup): string;
+export {};

package/dist/types/lib/document/document-canvas-actions.d.ts

@@ -0,0 +1,22 @@
+import { DocumentKpiSection, DocumentTableSection } from '../types/common-types.js';
+import { DashboardCardLocation } from '../../shared/dashboard-authoring/document-section-cards.js';
+/**
+ * Canvas editing actions for the Document page: the floating section
+ * toolbar, the gutters between sections, and the insert picker. The sheet
+ * provides them only while editing; each routes through `editDocument`.
+ */
+export type DocumentCanvasActions = {
+    /** Section ids in document order, for Move up and Move down. */
+    sectionIds: readonly string[];
+    moveSection: (sectionId: string, delta: -1 | 1) => void;
+    duplicateSection: (sectionId: string) => void;
+    deleteSection: (sectionId: string) => void;
+    openFullEditor: (section: DocumentTableSection | DocumentKpiSection) => void;
+    copyCard: (source: DashboardCardLocation, index: number) => void;
+    /** The page region whose settings the side panel shows, if any. */
+    selectedRegion: 'header' | 'footer' | null;
+    selectRegion: (region: 'header' | 'footer') => void;
+};
+export declare const DocumentCanvasActionsContext: import('react').Context<DocumentCanvasActions | null>;
+/** The canvas actions, or null outside the editing surface. */
+export declare function useDocumentCanvasActions(): DocumentCanvasActions | null;

package/dist/types/lib/document/document-edits.d.ts

@@ -0,0 +1,119 @@
+import { DocumentDefinition, DocumentKpiSection, DocumentSection, DocumentTableSection, DocumentTextContent, DocumentTextStyle, TCard, TDashboard } from '../types/common-types.js';
+import { Field } from '../types/explorer-types.js';
+import { DashboardCardLocation } from '../../shared/dashboard-authoring/document-section-cards.js';
+import { DocumentPanelTarget } from './document-panel-target.js';
+import { DocumentIdFactory, DocumentSectionKindId } from './document-section-kinds.js';
+/**
+ * The only write to a Document's sections. Every structural change (insert,
+ * copy, move, duplicate, remove, card replacement, KPI list edits) and every
+ * kind-specific option update is a `DocumentEdit`, applied by one pure
+ * function. The store's `editDocument` wraps it and persists the result;
+ * page, header, footer and input edits stay on `updateSheetDocument`.
+ */
+export type DocumentEdit = {
+    type: 'insert';
+    kind: DocumentSectionKindId;
+    index: number;
+} | {
+    type: 'copyCard';
+    source: DashboardCardLocation;
+    index: number;
+} | {
+    type: 'replaceWithCopy';
+    sectionId: string;
+    source: DashboardCardLocation;
+} | {
+    type: 'move';
+    sectionId: string;
+    toIndex: number;
+} | {
+    type: 'duplicate';
+    sectionId: string;
+} | {
+    type: 'remove';
+    sectionId: string;
+} | {
+    type: 'rename';
+    sectionId: string;
+    title: string;
+} | {
+    type: 'updateText';
+    sectionId: string;
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+} | {
+    type: 'updateTableOptions';
+    sectionId: string;
+    options: Partial<DocumentTableSection['table']>;
+} | {
+    type: 'updateKpiOptions';
+    sectionId: string;
+    options: Partial<DocumentKpiSection['kpi']>;
+} | {
+    type: 'setSpacerHeight';
+    sectionId: string;
+    heightPx: number;
+} | {
+    type: 'replaceCard';
+    sectionId: string;
+    oldCardId: string;
+    card: TCard;
+    calculatedFields?: Field[];
+}
+/** A placeholder KPI when neither `card` nor `source` is given. */
+ | {
+    type: 'addKpi';
+    sectionId: string;
+    card?: TCard;
+    source?: DashboardCardLocation;
+} | {
+    type: 'removeKpi';
+    sectionId: string;
+    cardId: string;
+} | {
+    type: 'moveKpi';
+    sectionId: string;
+    cardId: string;
+    toIndex: number;
+};
+export type DocumentEditResult = {
+    document: DocumentDefinition;
+    /** Where the panel goes next: the inserted, moved or edited section, or a removed section's neighbor. */
+    target: DocumentPanelTarget;
+    /** The sheet's full calculated fields after a copy brought new ones; persist as the sheet's list. */
+    calculatedFields?: Field[];
+    /** Card ids removed (`to: null`) or replaced by a new id, for reference cleanup. */
+    retargetedCardIds?: Array<{
+        from: string;
+        to: string | null;
+    }>;
+};
+export type DocumentEditContext = {
+    dashboard: Pick<TDashboard, 'sheets'>;
+    sheetId: string;
+    ids: DocumentIdFactory;
+};
+/** A refused edit: the command does not apply to the section, or would break the saved shape. */
+export declare class DocumentEditError extends Error {
+    constructor(message: string);
+}
+export declare const DOCUMENT_SPACER_MIN_HEIGHT_PX = 8;
+export declare const DOCUMENT_SPACER_MAX_HEIGHT_PX = 240;
+/** Fresh section and card ids. */
+export declare function createDocumentIdFactory(): DocumentIdFactory;
+export declare function clampDocumentSpacerHeight(heightPx: number): number;
+/**
+ * The index a section ends up at when dropped before or after another one.
+ * Returns the current index when either section is missing.
+ */
+export declare function getDocumentSectionDropIndex(sections: readonly Pick<DocumentSection, 'id'>[], sectionId: string, targetSectionId: string, placement: 'before' | 'after'): number;
+/**
+ * Cards a Document can copy: every executable table, pivot table, Matrix or KPI in
+ * the dashboard, including other document sections, except the given
+ * section's own cards. Linked library visuals are not offered: their stored
+ * card is completed by hydration, so a copy could be incomplete.
+ */
+export declare function listCopyableDocumentCardLocations(dashboard: Pick<TDashboard, 'sheets'>, options?: {
+    excludeSectionId?: string;
+}): DashboardCardLocation[];
+export declare function applyDocumentEdit(document: DocumentDefinition, edit: DocumentEdit, context: DocumentEditContext): DocumentEditResult;

package/dist/types/lib/document/document-kpi-figure.d.ts

@@ -0,0 +1,27 @@
+import { TCard } from '../types/common-types.js';
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { MetricComparisonSentiment } from '../../shared/analytics-protocol/index.js';
+/**
+ * What a KPI shows in print: its value and, when the card compares, one
+ * comparison line. Reads the result exactly as the dashboard KPI cards do
+ * (`kpi-result-values`), without their interactive layout.
+ */
+export type DocumentKpiFigure = {
+    label: string;
+    value: number | null;
+    /** Shown instead of a value when there is none. */
+    emptyMessage?: string;
+    comparison?: {
+        /** "Previous", "Target", or the author's label. */
+        label: string;
+        value: number;
+        /** Change against the comparison, as a ratio (0.042 = +4.2%). Null when the comparison is 0. */
+        change: number | null;
+        sentiment: MetricComparisonSentiment;
+    };
+};
+export declare function resolveDocumentKpiFigure({ card, data, comparisonMetadata, }: {
+    card: TCard;
+    data?: Record<string, unknown>[] | null;
+    comparisonMetadata?: ComparisonMetadataMap;
+}): DocumentKpiFigure;

package/dist/types/lib/document/document-kpi-layout.d.ts

@@ -0,0 +1,29 @@
+import { DocumentKpiSection } from '../types/common-types.js';
+/**
+ * Fixed geometry of a KPI section. The renderer sets these heights exactly,
+ * so the pagination estimate equals the printed height and a KPI section is
+ * placed on a page as one block.
+ */
+export declare const DOCUMENT_KPI_SECTION_TITLE_HEIGHT_PX = 24;
+export declare const DOCUMENT_KPI_TILE_ROW_HEIGHT_PX = 72;
+export declare const DOCUMENT_KPI_LINE_HEIGHT_PX = 28;
+/** Top and bottom rule plus the inner padding of the lines grid. */
+export declare const DOCUMENT_KPI_LINES_FRAME_HEIGHT_PX = 18;
+/** Top and bottom rule of the tile row. */
+export declare const DOCUMENT_KPI_TILES_FRAME_HEIGHT_PX = 2;
+export type DocumentKpiLayout = {
+    kind: 'tiles';
+    columns: number;
+} | {
+    kind: 'lines';
+    columns: 1 | 2;
+    rows: number;
+};
+/**
+ * The layout a KPI section prints with. A `tiles` section with more cards
+ * than tiles allow (save rejects it, but a runtime guard costs nothing) prints
+ * as two-column lines.
+ */
+export declare function resolveDocumentKpiLayout(section: Pick<DocumentKpiSection, 'cards' | 'kpi'>): DocumentKpiLayout;
+/** Printed height of a KPI section; the renderer uses the same numbers. */
+export declare function estimateKpiSectionHeightPx(section: Pick<DocumentKpiSection, 'cards' | 'kpi' | 'title'>): number;

package/dist/types/lib/document/document-kpi-section-edits.d.ts

@@ -0,0 +1,15 @@
+import { DocumentKpiSection, TCard } from '../types/common-types.js';
+/**
+ * Pure edits for a KPI section that keep the saved shape valid (1 to 8 KPI
+ * cards, at most 6 in tiles). Each returns the same section when the edit is
+ * not allowed, so callers can compare by reference. Phase 1.3's
+ * `applyDocumentEdit` builds its `addKpi`, `removeKpi` and `updateKpiOptions`
+ * cases on these.
+ */
+export declare function canAddDocumentKpiCard(section: DocumentKpiSection): boolean;
+/** Whether the next card forces the section from tiles to lines. */
+export declare function addingDocumentKpiCardSwitchesToLines(section: DocumentKpiSection): boolean;
+export declare function addDocumentKpiSectionCard(section: DocumentKpiSection, card: TCard): DocumentKpiSection;
+export declare function removeDocumentKpiSectionCard(section: DocumentKpiSection, cardId: string): DocumentKpiSection;
+export declare function canUseDocumentKpiTiles(section: DocumentKpiSection): boolean;
+export declare function updateDocumentKpiSectionOptions(section: DocumentKpiSection, options: Partial<DocumentKpiSection['kpi']>): DocumentKpiSection;

package/dist/types/lib/document/document-matrix-bands.d.ts

@@ -0,0 +1,66 @@
+/** A report allows this many bands (B4). */
+export declare const DOCUMENT_MATRIX_MAX_BANDS = 6;
+/**
+ * Row labels in a band get their unwrapped width, up to this share of the
+ * page, as the card PDF's banding limits its anchor columns (35%).
+ */
+export declare const DOCUMENT_MATRIX_LABEL_SHARE = 0.35;
+export type DocumentMatrixBand = {
+    /** Column indices the band prints: the row labels, then its groups. */
+    columns: number[];
+    /** "Yard: Tacoma to Newark (4 to 6 of 6)" (B6). */
+    caption: string;
+};
+/**
+ * What the measuring instance measured, before any page's label rule, so the
+ * same Matrix can be planned for another page (the landscape suggestion).
+ */
+export type DocumentMatrixMeasuredColumns = {
+    /** Each column's width in the tightest layout (labels wrapped). */
+    columnWidthsPx: readonly number[];
+    /** Each row-label column's width with its labels on one line. */
+    labelNaturalWidthsPx?: readonly (number | undefined)[];
+    /** Each column's group, or `null` for a row-label column. */
+    columnGroups: readonly (number | null)[];
+};
+export type DocumentMatrixFit = {
+    kind: 'fits';
+} | {
+    kind: 'bands';
+    bands: DocumentMatrixBand[];
+    measured: DocumentMatrixMeasuredColumns;
+} | {
+    kind: 'too_wide';
+    /** `group`: one group is wider than the page beside the row labels. */
+    reason: 'group' | 'bands';
+    bandCount?: number;
+    groupLevelLabel: string;
+    measured: DocumentMatrixMeasuredColumns;
+};
+/** The order band pages print in (B3). */
+export type DocumentMatrixBandOrder = 'across' | 'down';
+/**
+ * Plans how a Matrix prints on a page body `bodyWidthPx` wide, from each
+ * column's measured width and group.
+ */
+export declare function planDocumentMatrixFit({ columnWidthsPx, labelNaturalWidthsPx, columnGroups, groupLabels, groupLevelLabel, bodyWidthPx, }: {
+    /** Each column's width in the tightest layout (labels wrapped). */
+    columnWidthsPx: readonly number[];
+    /** Each row-label column's width with its labels on one line. */
+    labelNaturalWidthsPx?: readonly (number | undefined)[];
+    columnGroups: readonly (number | null)[];
+    groupLabels: readonly string[];
+    groupLevelLabel: string;
+    bodyWidthPx: number;
+}): DocumentMatrixFit;
+/**
+ * How many bands the same Matrix needs on another page body width, with the
+ * label rule applied at that width, as the measuring layer would apply it.
+ */
+export declare function countDocumentMatrixBands(fit: Extract<DocumentMatrixFit, {
+    measured: DocumentMatrixMeasuredColumns;
+}>, bodyWidthPx: number): number | undefined;
+/** The message for a Matrix too wide to print (B4). */
+export declare function documentMatrixTooWideMessage(fit: Extract<DocumentMatrixFit, {
+    kind: 'too_wide';
+}>): string;

package/dist/types/lib/document/document-matrix-print.d.ts

@@ -0,0 +1,11 @@
+import { DocumentTableSection } from '../types/common-types.js';
+/**
+ * How a Document prints a Matrix section (Plan 2, K1). These are print
+ * settings of the section, not of the Matrix: the section applies them to the
+ * layout read's presentation (`applyMatrixPrintOrganization`), so the card's
+ * definition never changes.
+ */
+export type DocumentMatrixPrintOptions = NonNullable<DocumentTableSection['table']['matrix']>;
+/** Report-style defaults, as in `/design/document-matrix-report`. */
+export declare const DOCUMENT_MATRIX_PRINT_DEFAULTS: Required<DocumentMatrixPrintOptions>;
+export declare function resolveDocumentMatrixPrint(section: Pick<DocumentTableSection, 'table'>): Required<DocumentMatrixPrintOptions>;

package/dist/types/lib/document/document-pagination.d.ts

@@ -1,3 +1,4 @@
+import { DocumentMatrixBandOrder } from './document-matrix-bands.js';
 import { DocumentTableRowMeasurementState } from './document-table-pagination-model.js';
 import { getDocumentTablePrintModel, DocumentTableLayoutMeasurement } from './document-table-print-model.js';
 import { DocumentTextRenderContext } from './document-variables.js';
@@ -11,14 +12,51 @@ export type DocumentGeneratedPageSection = {
 export type DocumentTableSlice = {
     startIndex: number;
     endIndex: number;
+    /** The row slice's position; band pages of one slice share it. */
     pageIndex: number;
     pageCount: number;
     totalRows: number;
     rowsPerPage: number;
+    /** A Matrix printed in column bands: which band this page draws (2c). */
+    band?: {
+        index: number;
+        count: number;
+    };
 };
-export type DocumentTablePaginationPlan = {
+/**
+ * What a table section tells the paginator about its rows, beyond their count
+ * (Plan 2, L4). Every field is optional: a section that reports none
+ * paginates as before.
+ */
+export type DocumentTableRowFacts = {
+    /** Per row: a page may not break before it (keep rules). */
+    keepWithPrevious?: readonly boolean[];
+    /** Per row: header rows a page that starts there repeats (Indented Matrix). */
+    continuationRowCounts?: readonly number[];
+    /** The section prints nothing: it is empty and set to hide when empty. */
+    hidden?: boolean;
+};
+/** What an empty section set to hide when empty reports (Plan 2, L6). */
+export declare const DOCUMENT_TABLE_HIDDEN_ROW_FACTS: DocumentTableRowFacts;
+/** How a table section reports its row count, and optionally its row facts. */
+export type DocumentTableRowCountChange = (sectionId: string, rowCount: number, facts?: DocumentTableRowFacts) => void;
+/**
+ * Whether the paginator has what it needs for a table section (Plan 2, N3):
+ * a settled row count, and a measured height for every row unless the
+ * section prints none. Print holds the PDF until this holds for every
+ * section.
+ */
+export declare function isDocumentTableSectionMeasured({ rowCount, facts, measurement, }: {
+    rowCount: number | undefined;
+    facts: DocumentTableRowFacts | undefined;
+    measurement: DocumentTableLayoutMeasurement | undefined;
+}): boolean;
+export type DocumentTablePaginationPlan = DocumentTableRowFacts & {
     rowCount: number;
     rowsPerPage: number;
+    /** A Matrix wider than the page prints each row slice once per band (2c). */
+    bandCount?: number;
+    bandOrder?: DocumentMatrixBandOrder;
     footerRowCount?: number;
     fallbackRowHeightPx?: number;
     rowMeasurementState?: DocumentTableRowMeasurementState;
@@ -27,7 +65,6 @@ export type DocumentTablePaginationPlan = {
     rowHeightsPx?: Array<number | undefined>;
     chromeHeightPx?: number;
     renderedMinHeightPx?: number;
-    measuredRowsPerPage?: number;
 };
 export type DocumentPaginationMetricsMode = 'preview' | 'print';
 export type DocumentGeneratedPage = {
@@ -46,12 +83,28 @@ type DocumentPaginationOptions = {
     textRenderContext?: DocumentTextRenderContext;
 };
 export declare function paginateDocumentSectionsByManualBreaks(sections: DocumentSection[], options?: DocumentPaginationOptions): DocumentGeneratedPage[];
-export declare function buildDocumentTablePaginationPlans({ document, tableRowCountsBySectionId, tableLayoutMeasurementsBySectionId, shouldPaginateTables, pageMetricsMode, }: {
+/**
+ * The order a table's pages print in: one page per row slice, or, for a
+ * Matrix in bands, one per slice and band (B3).
+ */
+export declare function orderDocumentTableBandPages(sliceCount: number, bandCount: number, bandOrder?: DocumentMatrixBandOrder): {
+    pageIndex: number;
+    band: number;
+}[];
+export declare function buildDocumentTablePaginationPlans({ document, tableRowCountsBySectionId, tableRowFactsBySectionId, tableLayoutMeasurementsBySectionId, shouldPaginateTables, pageMetricsMode, }: {
     document: DocumentDefinition;
     tableRowCountsBySectionId: Record<string, number>;
+    /** Row facts a section reported with its count (Matrix keep rules). */
+    tableRowFactsBySectionId?: Record<string, DocumentTableRowFacts>;
     tableLayoutMeasurementsBySectionId?: Record<string, DocumentTableLayoutMeasurement>;
     shouldPaginateTables: boolean;
     pageMetricsMode?: DocumentPaginationMetricsMode;
 }): Record<string, DocumentTablePaginationPlan>;
 export declare function isDocumentTablePaginationEligible(section: DocumentSection): section is DocumentTableSection;
 export declare function getDocumentTableRowsPerPage(document: DocumentDefinition, printModel: ReturnType<typeof getDocumentTablePrintModel>, pageMetricsMode?: DocumentPaginationMetricsMode): number;
+/**
+ * The page (1-based) each section starts on. A table split across pages
+ * starts on the page with its first slice, and a page break is on the page
+ * it ends.
+ */
+export declare function getDocumentSectionStartPages(pages: readonly Pick<DocumentGeneratedPage, 'sections' | 'breakAfterSection'>[]): Record<string, number>;

package/dist/types/lib/document/document-panel-target.d.ts

@@ -0,0 +1,19 @@
+/**
+ * What the Document side panel shows: the document (page, header and footer,
+ * inputs), the header, the footer, or one section (and, for a KPI section,
+ * optionally one KPI). `applyDocumentEdit` returns where the panel goes after
+ * an edit. The dashboard store keeps one per sheet, and the sheet derives
+ * its selected section from it.
+ */
+export type DocumentPanelTarget = {
+    kind: 'document';
+    group?: 'page' | 'headerFooter' | 'inputs';
+} | {
+    kind: 'header';
+} | {
+    kind: 'footer';
+} | {
+    kind: 'section';
+    sectionId: string;
+    cardId?: string;
+};

package/dist/types/lib/document/document-section-editor.d.ts

@@ -1,8 +1,9 @@
-import { DocumentChartSection, DocumentTableSection, TCard, TFrame } from '../types/common-types.js';
-type DataBackedDocumentSection = DocumentTableSection | DocumentChartSection;
-export declare const DOCUMENT_TABLE_CARD_TYPES: readonly ["table", "pivotTable"];
-export declare function createDocumentSectionEditorFrame(section: DataBackedDocumentSection): TFrame;
-export declare function getActiveDocumentSectionCard(frame: TFrame): TCard | null;
+import { DocumentSection, TCard, TFrame } from '../types/common-types.js';
+/**
+ * The transient frame the visual editor opens for one card of a section.
+ * It holds that card only: a KPI section is never edited, or rendered, as one
+ * multi-card frame (that would trigger the dashboard's KPI-plus-info layout).
+ * Omit `cardId` for a single-card section.
+ */
+export declare function createDocumentSectionEditorFrame(section: DocumentSection, cardId?: string): TFrame;
 export declare function getDocumentSectionEditorCard(frame: TFrame, cardId: string): TCard | null;
-export declare function isSupportedDocumentTableCardType(card: Pick<TCard, 'type'>): boolean;
-export {};

package/dist/types/lib/document/document-section-kinds.d.ts

@@ -0,0 +1,49 @@
+import { TChartType } from '../charts/types.js';
+import { DocumentSection, TCard } from '../types/common-types.js';
+/**
+ * Author-facing identity of a Document section. It differs from the storage
+ * `type`: Table, Pivot and Matrix are all stored as `type: 'table'` and are
+ * told apart by `card.type`.
+ */
+export type DocumentSectionKindId = 'text' | 'table' | 'matrix' | 'kpi' | 'spacer' | 'page_break'
+/** Existing sections only. */
+ | 'pivot'
+/** Contract-only: not addable, not rendered. */
+ | 'chart';
+export type DocumentIdFactory = {
+    section(): string;
+    card(): string;
+};
+export type DocumentSectionKind = {
+    id: DocumentSectionKindId;
+    label: string;
+    /** Picker copy, one line. */
+    description: string;
+    group: 'data' | 'content' | 'layout';
+    /** Offered when adding a section. */
+    addable: boolean;
+    /** Card types a section of this kind accepts. Empty for non-data kinds. */
+    cardTypes: readonly TChartType[];
+    /** A new section with defaults. Data kinds start with a placeholder card and no data source. */
+    create(ids: DocumentIdFactory): DocumentSection;
+};
+/** A placeholder KPI card with no data source yet. */
+export declare function createDocumentKpiCard(cardId: string): TCard;
+export declare const DOCUMENT_SECTION_KINDS: Readonly<Record<DocumentSectionKindId, DocumentSectionKind>>;
+/** Author-facing kind of a stored section. */
+export declare function getDocumentSectionKind(section: DocumentSection): DocumentSectionKind;
+/** Whether a section of this kind may hold a card of this type. */
+export declare function documentSectionAcceptsCardType(section: DocumentSection, cardType: TChartType): boolean;
+/** Why a section refuses a card type, or null when it accepts it. */
+export declare function getDocumentSectionCardTypeError(section: DocumentSection, cardType: TChartType): string | null;
+/**
+ * The section with `oldCardId` replaced by `card`. Throws when the section
+ * does not own `oldCardId`, or its kind does not accept `card.type`.
+ */
+export declare function replaceDocumentSectionCard(section: DocumentSection, oldCardId: string, card: TCard): DocumentSection;
+/** The addable kinds, in registry order, grouped for the insert picker. */
+export declare function getAddableDocumentSectionKindGroups(): {
+    kinds: DocumentSectionKind[];
+    id: DocumentSectionKind["group"];
+    label: string;
+}[];

package/dist/types/lib/document/document-section-query-options.d.ts

@@ -0,0 +1,25 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardCardQueryOptions } from '../hooks/use-dashboard-frame-query.js';
+import { ControlDefinition, DashboardInputValues } from '../types/common-types.js';
+import { TableTotalsRequest } from '../types/explorer-types.js';
+/** Inputs, filters and controls the Document sheet has already resolved for its sections. */
+export type DocumentSectionRuntime = {
+    documentFilterValues: TFilterValue[];
+    documentControlDefinitions: ControlDefinition[];
+    documentControlValues: Record<string, unknown>;
+    documentDashboardInputValues?: DashboardInputValues;
+    missingRequiredInputLabels: string[];
+};
+/**
+ * Query options for every card of a Document section, so table and KPI
+ * sections run their cards in the same section runtime: section-scoped inputs,
+ * document filter and control values, and no carried dashboard context.
+ */
+export declare function buildDocumentSectionQueryOptions({ sectionId, runtime, tableTotalsRequest, }: {
+    sectionId: string;
+    runtime: Omit<DocumentSectionRuntime, 'missingRequiredInputLabels'>;
+    /** Flat-table grand totals; table sections only. */
+    tableTotalsRequest?: TableTotalsRequest;
+}): DashboardCardQueryOptions;
+/** The query key marker every Document section query carries. */
+export declare const DOCUMENT_SECTION_QUERY_MARKER = "documentSection";