react-semaphor 0.1.295 → 0.1.297

package/dist/types/main.d.ts

@@ -76,6 +76,20 @@ declare type Actions_2 = {
     addSheet: (sheet: TSheet) => void;
     deleteSheet: (sheetId: string) => void;
     setSheetTitle: (sheetId: string, title: string) => void;
+    updateSheetDocument: (sheetId: string, updater: (document: DocumentDefinition) => DocumentDefinition) => void;
+    updateDocumentSectionCard: (sheetId: string, sectionId: string, card: TCard, options?: {
+        calculatedFields?: Field[];
+    }) => void;
+    setSelectedDocumentSectionId: (sheetId: string, sectionId: string | null) => void;
+    setDocumentInspectorTab: (sheetId: string, tab: DocumentInspectorTab) => void;
+    setDocumentInputFilterValues: (sheetId: string, valuesByInputId: Record<string, TFilterValue | undefined>) => void;
+    setDocumentInputFilterValue: (sheetId: string, inputId: string, filterValue: TFilterValue) => void;
+    removeDocumentInputFilterValue: (sheetId: string, inputId: string) => void;
+    setDocumentInputFilterModes: (sheetId: string, modesByInputId: Record<string, DocumentFilterMode>) => void;
+    setDocumentInputFilterMode: (sheetId: string, inputId: string, filterMode: DocumentFilterMode) => void;
+    setDocumentInputControlValues: (sheetId: string, valuesByInputId: Record<string, unknown>) => void;
+    setDocumentInputControlValue: (sheetId: string, inputId: string, value: unknown) => void;
+    clearDocumentInputRuntime: (sheetId?: string) => void;
     setSelectedSheetId: (sheetId: string | null) => void;
     setSheetLayout: (sheetId: string, layout: default_2.Layout[]) => void;
     setSheetLayouts: (sheetId: string, layouts: default_2.Layouts) => void;
@@ -284,6 +298,8 @@ declare type Actions_3 = TableActions & ExplorerActions & DrillActions & {
     setOnTableChange: (onTableChange: (tableNmae: string) => void) => void;
     setOnSave: (onSave: (card: TFrame) => void) => void;
     setOnClose: (onClose: () => void) => void;
+    setEditorContext: (context: EditorContext) => void;
+    clearEditorContext: () => void;
 };
 
 /**
@@ -314,21 +330,16 @@ declare type AddFrameOptions = {
 };
 
 /**
- * Segmented control that flips the editor between Drag-and-drop and SQL
- * modes. Replaces the earlier single-switch toggle — two labeled buttons
- * read more clearly than a toggle whose state requires translating an
- * icon.
- *
- * Layout matches the Filter split-button: a bordered shell with two
- * ghost-button segments inside. The active segment gets a muted fill;
- * the inactive segment is transparent so the surface behind shows
- * through.
+ * Single-button mode toggle (action pattern). The label reflects where
+ * a click will take you, not where you currently are — e.g. while in
+ * drag-and-drop mode the button shows `</> SQL`. Compact, matches the
+ * "Edit / Done" toggle convention.
  */
 export declare function AdvancedModeToggle({ className }: AdvancedModeToggleProps): JSX.Element | null;
 
 declare interface AdvancedModeToggleProps {
-    /** @deprecated Kept for API compatibility; the segmented control
-     * handles its own layout. */
+    /** @deprecated Kept for API compatibility; the toggle handles its
+     * own layout. */
     className?: string;
     /** @deprecated The old DevModeSwitch prop has no analogue here. */
     labelClassName?: string;
@@ -1448,6 +1459,18 @@ export declare type DashboardProps = {
         cardControlDefinitions?: ControlDefinition[];
         controlBindings?: ControlBinding[];
     };
+    /**
+     * Document-local runtime values for print/render entry points. Values are
+     * keyed by document input id and are intentionally separate from dashboard
+     * filters/controls.
+     */
+    documentInputValues?: DocumentInputRuntimeValues;
+    /**
+     * Render target for print entry points. Generic dashboard PDF exports also
+     * use cardDisplay.mode="print"; document-specific print handling must only
+     * run when this is explicitly "document".
+     */
+    renderMode?: 'dashboard' | 'document';
     customStyle?: TStyle;
     currentTheme?: Theme;
     version?: string;
@@ -1493,6 +1516,9 @@ export declare type DashboardStore = {
     selectedFrameId?: string | null;
     selectedCardId?: string | null;
     selectedCard?: TCard | null;
+    selectedDocumentSectionIdsBySheetId: Record<string, string | null>;
+    documentInspectorTabsBySheetId: Record<string, DocumentInspectorTab>;
+    documentInputRuntimeBySheetId: Record<string, DocumentInputRuntimeState>;
     /**
      * Pending sheet-wide frame rewrites produced while visual editing. These stay
      * draft-only until the editor Save path applies the current frame.
@@ -1705,6 +1731,235 @@ export declare type DimensionInputReference = {
 
 export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
 
+export declare type DocumentChartSection = {
+    id: string;
+    type: 'chart';
+    title?: string;
+    card: TCard;
+    heightPx: number;
+};
+
+export declare type DocumentControlInputDefinition = DocumentInputBase & {
+    kind: 'control';
+    control: ControlDefinition;
+    exports?: DocumentInputExportKey[];
+};
+
+export declare type DocumentDefinition = {
+    version: 1;
+    page: DocumentPageSetup;
+    runtime?: DocumentRuntimeSettings;
+    inputs?: DocumentInputDefinition[];
+    defaultInputValues?: Record<string, unknown>;
+    header?: DocumentHeaderRegion;
+    footer?: DocumentFooterRegion;
+    sections: DocumentSection[];
+    theme?: DocumentTheme;
+};
+
+export declare type DocumentFilterInputDefinition = DocumentInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+    exports?: DocumentInputExportKey[];
+};
+
+declare type DocumentFilterMode = 'include' | 'exclude';
+
+export declare type DocumentFooterRegion = DocumentRegionBase & {
+    region: 'footer';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_footer';
+    };
+};
+
+export declare type DocumentHeaderRegion = DocumentRegionBase & {
+    region: 'header';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_header';
+    };
+};
+
+export declare type DocumentImageRegionBlock = DocumentRegionBlockBase & {
+    type: 'image';
+    role?: 'logo';
+    src: string;
+    alt?: string;
+    widthPx?: number;
+};
+
+export declare type DocumentInputBase = {
+    id: string;
+    label: string;
+    variableName: string;
+    requiredAtExecution: boolean;
+    documentPlacement?: 'input_bar';
+    description?: string;
+};
+
+export declare type DocumentInputDefinition = DocumentFilterInputDefinition | DocumentControlInputDefinition;
+
+export declare type DocumentInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
+
+export declare type DocumentInputRuntimeState = {
+    filterValuesByInputId: Record<string, TFilterValue | undefined>;
+    filterModesByInputId: Record<string, DocumentFilterMode>;
+    controlValuesByInputId: Record<string, unknown>;
+};
+
+export declare type DocumentInputRuntimeValues = {
+    sheetId?: string;
+    filterValuesByInputId?: Record<string, TFilterValue | undefined>;
+    controlValuesByInputId?: Record<string, unknown>;
+    generatedAt?: string;
+};
+
+export declare type DocumentInspectorTab = 'section' | 'page' | 'header' | 'footer' | 'inputs';
+
+export declare type DocumentPageBreakSection = {
+    id: string;
+    type: 'page_break';
+};
+
+export declare type DocumentPageSetup = {
+    size: 'letter' | 'a4';
+    orientation: 'portrait' | 'landscape';
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        unit: 'in' | 'mm';
+    };
+};
+
+export declare type DocumentRegion = DocumentHeaderRegion | DocumentFooterRegion;
+
+export declare type DocumentRegionBase = {
+    enabled: boolean;
+    heightPx?: number;
+    layout: DocumentRegionLayout;
+    blocks: DocumentRegionBlock[];
+};
+
+export declare type DocumentRegionBlock = DocumentTextRegionBlock | DocumentImageRegionBlock;
+
+export declare type DocumentRegionBlockBase = {
+    id: string;
+    area?: 'left' | 'center' | 'right' | 'title' | 'metadata' | 'note' | 'pageInfo';
+};
+
+export declare type DocumentRegionLayout = {
+    type: 'preset';
+    preset: 'mvp_header' | 'mvp_footer';
+};
+
+export declare type DocumentRuntimeSettings = {
+    generatedAtFormat?: string;
+};
+
+export declare type DocumentSection = DocumentTextSection | DocumentTableSection | DocumentChartSection | DocumentSpacerSection | DocumentPageBreakSection;
+
+export declare type DocumentSpacerSection = {
+    id: string;
+    type: 'spacer';
+    heightPx: number;
+};
+
+export declare type DocumentTableDensity = 'comfortable' | 'standard' | 'compact' | 'dense';
+
+export declare type DocumentTableGridLines = 'none' | 'outer' | 'inner' | 'horizontal' | 'vertical' | 'top' | 'right' | 'bottom' | 'left' | 'full';
+
+export declare type DocumentTableHeaderStyle = 'plain' | 'filled' | 'accent';
+
+export declare type DocumentTableSection = {
+    id: string;
+    type: 'table';
+    title?: string;
+    card: TCard;
+    table: {
+        totalsRow?: boolean;
+        columnFormatting?: Record<string, unknown>;
+        repeatHeaderOnPageBreak?: boolean;
+        rowHeightPx?: number;
+        style?: DocumentTableStyle;
+        totalsStyle?: DocumentTableTotalsStyle;
+    };
+};
+
+export declare type DocumentTableStyle = {
+    density?: DocumentTableDensity;
+    headerStyle?: DocumentTableHeaderStyle;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    stripedRows?: boolean;
+    gridLines?: DocumentTableGridLines;
+    wrapText?: boolean;
+};
+
+export declare type DocumentTableTotalsFontWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+
+export declare type DocumentTableTotalsStyle = {
+    backgroundColor?: string;
+    textColor?: string;
+    fontWeight?: DocumentTableTotalsFontWeight;
+    borderTop?: boolean;
+};
+
+export declare type DocumentTextContent = DocumentTextNode[];
+
+export declare type DocumentTextInlineFormat = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+};
+
+export declare type DocumentTextNode = {
+    type: 'text';
+    value: string;
+    format?: DocumentTextInlineFormat;
+} | {
+    type: 'variable';
+    ref: DocumentVariableRef;
+    format?: DocumentTextInlineFormat;
+};
+
+export declare type DocumentTextRegionBlock = DocumentRegionBlockBase & {
+    type: 'text';
+    role?: 'title' | 'metadata' | 'note' | 'pageInfo';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+
+export declare type DocumentTextSection = {
+    id: string;
+    type: 'text';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+
+export declare type DocumentTextStyle = {
+    fontSize?: number;
+    fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+};
+
+export declare type DocumentTheme = {
+    fontFamily?: string;
+    primaryColor?: string;
+};
+
+export declare type DocumentVariableRef = {
+    source: 'input';
+    inputId: string;
+    export: DocumentInputExportKey;
+} | {
+    source: 'documentMeta';
+    key: 'generatedAt' | 'pageNumber' | 'pageCount';
+};
+
 export declare interface DomainCalculatedDimension {
     name: string;
     label: string;
@@ -1728,6 +1983,16 @@ export declare interface DomainCalculatedMetric {
     aggregationStrategy?: AggregationStrategy;
 }
 
+export declare function downloadDocumentPdf(apiServiceUrl: string, authToken: AuthToken | undefined, options: {
+    sheetId: string;
+    title: string;
+    pageSize: string;
+    orientation: string;
+    inputValues: DocumentInputRuntimeValues;
+    timezone?: string;
+    password?: string;
+}): Promise<void>;
+
 export declare function downloadPdf(apiServiceUrl: string, authToken: AuthToken | undefined, password?: string, sheetSelection?: 'current' | 'all', expandedState?: Record<string, boolean>): Promise<void>;
 
 declare type DraftDeliveryConfig = {
@@ -2034,6 +2299,19 @@ export declare interface DynamicDrillInteraction {
     /* Excluded from this release type: drillField */
 }
 
+export declare type EditorContext = {
+    type: 'dashboard';
+} | {
+    type: 'documentSection';
+    sheetId: string;
+    sectionId: string;
+    cardId: string;
+    documentFilterValues?: TFilterValue[];
+    documentControlDefinitions?: ControlDefinition[];
+    documentControlValues?: Record<string, unknown>;
+    missingRequiredInputLabels?: string[];
+};
+
 export declare type EditorStore = {
     tempQueryData?: {
         queryKey: string[];
@@ -2071,6 +2349,7 @@ export declare type EditorStore = {
     onSchemaChange?: (schemaName: string) => void;
     onSave?: (card: TFrame) => void | Promise<void>;
     onClose?: () => void;
+    editorContext?: EditorContext;
     /** Draft slots for mode switching - preserves work when toggling between dev/standard */
     modeDrafts: ModeDrafts;
 };
@@ -2477,6 +2756,8 @@ declare type FixedMonthDefaultDateFilter = {
     month: number;
 };
 
+export declare type FlatTableTotalsBehavior = 'sum' | 'avg' | 'count' | 'label';
+
 export declare function fmt(str: string): string;
 
 /**
@@ -3178,6 +3459,7 @@ export declare interface QueryExecutionResponse {
     subtotalColumns?: string[];
     columnSubtotalMeta?: any;
     columnKeyMap?: QueryColumnKeyMap;
+    tableTotalsByColumnId?: Record<string, string | number | null>;
     metadata?: any;
 }
 
@@ -3216,6 +3498,16 @@ export declare function resolveDatamodelName(datamodelName: string): string;
 
 export declare const resolveDataType: (value: any) => string;
 
+export declare type ResolvedDocumentInput = {
+    inputId: string;
+    variableName: string;
+    rawValue: unknown;
+    displayValue: string;
+    filterValues?: TFilterValue[];
+    controlValue?: unknown;
+    exports: Record<string, string | number | boolean | null>;
+};
+
 declare type ResolvedPrimaryDateField = {
     sourceDataset: string;
     sourceField: string;
@@ -3565,7 +3857,7 @@ export declare type TableConfig = {
  * the Linear-style spec). Drives row padding, cell font size, and header
  * font size via a shared density spec in DataTable.
  */
-declare type TableDensity = 'compact' | 'comfortable' | 'spacious';
+declare type TableDensity = 'dense' | 'compact' | 'standard' | 'comfortable' | 'spacious';
 
 export declare type TableItem = DropdownItem;
 
@@ -3578,6 +3870,17 @@ declare type TablePreferences = {
     enableDevModePagination?: boolean;
     forceClientPagination?: boolean;
     density?: TableDensity;
+    documentWrapText?: boolean;
+};
+
+export declare type TableTotalsRequest = {
+    source: 'documentFlatTable';
+    columns: Array<{
+        fieldId: string;
+        role: 'detail' | 'groupby' | 'metric';
+        behavior: FlatTableTotalsBehavior;
+        label?: string;
+    }>;
 };
 
 /**
@@ -4567,6 +4870,7 @@ export declare type TSelectedRecord = ComboBoxOption;
 
 export declare type TSheet = {
     id: string;
+    kind?: 'dashboard' | 'document';
     title?: string;
     description?: string;
     layout?: ReactGridLayout.Layout[];
@@ -4574,6 +4878,7 @@ export declare type TSheet = {
     cards?: TCard[];
     frames?: TFrame[];
     calculatedFields?: Field[];
+    document?: DocumentDefinition;
 };
 
 /**

package/dist/types/shared.d.ts

@@ -483,6 +483,216 @@ declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowfla
 
 declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
 
+declare type DocumentChartSection = {
+    id: string;
+    type: 'chart';
+    title?: string;
+    card: TCard;
+    heightPx: number;
+};
+
+declare type DocumentControlInputDefinition = DocumentInputBase & {
+    kind: 'control';
+    control: ControlDefinition;
+    exports?: DocumentInputExportKey[];
+};
+
+declare type DocumentDefinition = {
+    version: 1;
+    page: DocumentPageSetup;
+    runtime?: DocumentRuntimeSettings;
+    inputs?: DocumentInputDefinition[];
+    defaultInputValues?: Record<string, unknown>;
+    header?: DocumentHeaderRegion;
+    footer?: DocumentFooterRegion;
+    sections: DocumentSection[];
+    theme?: DocumentTheme;
+};
+
+declare type DocumentFilterInputDefinition = DocumentInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+    exports?: DocumentInputExportKey[];
+};
+
+declare type DocumentFooterRegion = DocumentRegionBase & {
+    region: 'footer';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_footer';
+    };
+};
+
+declare type DocumentHeaderRegion = DocumentRegionBase & {
+    region: 'header';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_header';
+    };
+};
+
+declare type DocumentImageRegionBlock = DocumentRegionBlockBase & {
+    type: 'image';
+    role?: 'logo';
+    src: string;
+    alt?: string;
+    widthPx?: number;
+};
+
+declare type DocumentInputBase = {
+    id: string;
+    label: string;
+    variableName: string;
+    requiredAtExecution: boolean;
+    documentPlacement?: 'input_bar';
+    description?: string;
+};
+
+declare type DocumentInputDefinition = DocumentFilterInputDefinition | DocumentControlInputDefinition;
+
+declare type DocumentInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
+
+declare type DocumentPageBreakSection = {
+    id: string;
+    type: 'page_break';
+};
+
+declare type DocumentPageSetup = {
+    size: 'letter' | 'a4';
+    orientation: 'portrait' | 'landscape';
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        unit: 'in' | 'mm';
+    };
+};
+
+declare type DocumentRegionBase = {
+    enabled: boolean;
+    heightPx?: number;
+    layout: DocumentRegionLayout;
+    blocks: DocumentRegionBlock[];
+};
+
+declare type DocumentRegionBlock = DocumentTextRegionBlock | DocumentImageRegionBlock;
+
+declare type DocumentRegionBlockBase = {
+    id: string;
+    area?: 'left' | 'center' | 'right' | 'title' | 'metadata' | 'note' | 'pageInfo';
+};
+
+declare type DocumentRegionLayout = {
+    type: 'preset';
+    preset: 'mvp_header' | 'mvp_footer';
+};
+
+declare type DocumentRuntimeSettings = {
+    generatedAtFormat?: string;
+};
+
+declare type DocumentSection = DocumentTextSection | DocumentTableSection | DocumentChartSection | DocumentSpacerSection | DocumentPageBreakSection;
+
+declare type DocumentSpacerSection = {
+    id: string;
+    type: 'spacer';
+    heightPx: number;
+};
+
+declare type DocumentTableDensity = 'comfortable' | 'standard' | 'compact' | 'dense';
+
+declare type DocumentTableGridLines = 'none' | 'outer' | 'inner' | 'horizontal' | 'vertical' | 'top' | 'right' | 'bottom' | 'left' | 'full';
+
+declare type DocumentTableHeaderStyle = 'plain' | 'filled' | 'accent';
+
+declare type DocumentTableSection = {
+    id: string;
+    type: 'table';
+    title?: string;
+    card: TCard;
+    table: {
+        totalsRow?: boolean;
+        columnFormatting?: Record<string, unknown>;
+        repeatHeaderOnPageBreak?: boolean;
+        rowHeightPx?: number;
+        style?: DocumentTableStyle;
+        totalsStyle?: DocumentTableTotalsStyle;
+    };
+};
+
+declare type DocumentTableStyle = {
+    density?: DocumentTableDensity;
+    headerStyle?: DocumentTableHeaderStyle;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    stripedRows?: boolean;
+    gridLines?: DocumentTableGridLines;
+    wrapText?: boolean;
+};
+
+declare type DocumentTableTotalsFontWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+
+declare type DocumentTableTotalsStyle = {
+    backgroundColor?: string;
+    textColor?: string;
+    fontWeight?: DocumentTableTotalsFontWeight;
+    borderTop?: boolean;
+};
+
+declare type DocumentTextContent = DocumentTextNode[];
+
+declare type DocumentTextInlineFormat = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+};
+
+declare type DocumentTextNode = {
+    type: 'text';
+    value: string;
+    format?: DocumentTextInlineFormat;
+} | {
+    type: 'variable';
+    ref: DocumentVariableRef;
+    format?: DocumentTextInlineFormat;
+};
+
+declare type DocumentTextRegionBlock = DocumentRegionBlockBase & {
+    type: 'text';
+    role?: 'title' | 'metadata' | 'note' | 'pageInfo';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+
+declare type DocumentTextSection = {
+    id: string;
+    type: 'text';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+
+declare type DocumentTextStyle = {
+    fontSize?: number;
+    fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+};
+
+declare type DocumentTheme = {
+    fontFamily?: string;
+    primaryColor?: string;
+};
+
+declare type DocumentVariableRef = {
+    source: 'input';
+    inputId: string;
+    export: DocumentInputExportKey;
+} | {
+    source: 'documentMeta';
+    key: 'generatedAt' | 'pageNumber' | 'pageCount';
+};
+
 declare interface DrillDownInteraction {
     mode: 'drillDown';
     /**
@@ -1224,7 +1434,7 @@ declare type StyleProps = {
  * the Linear-style spec). Drives row padding, cell font size, and header
  * font size via a shared density spec in DataTable.
  */
-declare type TableDensity = 'compact' | 'comfortable' | 'spacious';
+declare type TableDensity = 'dense' | 'compact' | 'standard' | 'comfortable' | 'spacious';
 
 declare type TablePreferences = {
     columnSettingsMap?: ColumnSettingsMap;
@@ -1235,6 +1445,7 @@ declare type TablePreferences = {
     enableDevModePagination?: boolean;
     forceClientPagination?: boolean;
     density?: TableDensity;
+    documentWrapText?: boolean;
 };
 
 /**
@@ -1933,6 +2144,7 @@ declare type TPointStyle = 'circle' | 'cross' | 'crossRot' | 'dash' | 'line' | '
 
 declare type TSheet = {
     id: string;
+    kind?: 'dashboard' | 'document';
     title?: string;
     description?: string;
     layout?: ReactGridLayout.Layout[];
@@ -1940,6 +2152,7 @@ declare type TSheet = {
     cards?: TCard[];
     frames?: TFrame[];
     calculatedFields?: Field[];
+    document?: DocumentDefinition;
 };
 
 /**