react-semaphor 0.1.504 → 0.1.506

package/dist/types/lib/pdf-fast-path/candidate-eligibility.d.ts

@@ -0,0 +1,17 @@
+import { TChartType } from '../charts/types.js';
+import { ExportFormat } from '../utils/export-utils.js';
+export declare const PDF_ROW_LIMIT_GUIDANCE: string;
+export declare function isExistingStructuredFastPdfCardType(cardType: TChartType | undefined): boolean;
+export declare function shouldAttemptExistingFastPdfCandidate({ cardType, rowCount, hasServerPagination, hasRequiredStructure, }: {
+    cardType: TChartType | undefined;
+    rowCount: number;
+    hasServerPagination: boolean;
+    hasRequiredStructure: boolean;
+}): boolean;
+export declare function isExistingStructuredPdfOptionAvailable(cardType: TChartType | undefined, knownRowCount: number | null): boolean;
+export declare function shouldAutoSelectCsvForPdfRowLimit({ cardType, knownRowCount, selectedFormat, csvSupported, }: {
+    cardType: TChartType | undefined;
+    knownRowCount: number | null;
+    selectedFormat: ExportFormat;
+    csvSupported: boolean;
+}): boolean;

package/dist/types/lib/pdf-fast-path/extract-table-structure.d.ts

@@ -0,0 +1,5 @@
+import { FastPathTableStructure } from '../../shared/format-utils/table-structure.js';
+export declare function extractDataTableStructure(root: Element | null): FastPathTableStructure | null;
+export declare function extractAggregateTableStructure(root: Element | null): FastPathTableStructure | null;
+export declare function extractPivotTableStructure(root: Element | null): FastPathTableStructure | null;
+export declare function extractFastPathStructure(frameId: string, cardType: string): FastPathTableStructure | null;

package/dist/types/lib/pdf-fast-path/index.d.ts

@@ -0,0 +1,27 @@
+import { FastPathTableStructure } from '../../shared/format-utils/table-structure.js';
+import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
+export type FastPathPayload = {
+    cardType: string;
+    reportTitle: string;
+    tableStructure: FastPathTableStructure;
+    filterLine?: string;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    timezone?: string;
+    pageSize?: string;
+    orientation?: string;
+    wideTableStrategy?: 'auto' | 'fit' | 'horizontal_paginate';
+    password?: string;
+    rowCount: number;
+};
+export declare function buildFastPathPayload(params: {
+    cardType: string;
+    reportTitle: string;
+    tableStructure: FastPathTableStructure;
+    filterLine?: string;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    timezone?: string;
+    pageSize?: string;
+    orientation?: string;
+    wideTableStrategy?: 'auto' | 'fit' | 'horizontal_paginate';
+    password?: string;
+}): FastPathPayload;

package/dist/types/lib/pdf-fast-path/pivot-fast-path-utils.d.ts

@@ -0,0 +1,12 @@
+export declare function countPivotBodyRows(records: any[]): number;
+export declare function getPivotFastPathRowCount({ exportData, pivotTableConfig, pivotData, }: {
+    exportData: any;
+    pivotTableConfig?: {
+        data?: {
+            rowData?: any[];
+        };
+    } | null;
+    pivotData?: {
+        records?: any[];
+    } | null;
+}): number;

package/dist/types/lib/pdf-fast-path/prepare-server-table-pdf-export.d.ts

@@ -0,0 +1,37 @@
+import { TablePreferences } from '../../components/visual/data-table/types/data-table.js';
+import { CardNumericPresentationContext } from '../formatters/numeric-presentation.js';
+import { DashboardCardQueryContract } from '../query-context/build-dashboard-card-query-contract.js';
+import { TCard } from '../types/common-types.js';
+import { CardConfig } from '../types/explorer-types.js';
+import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
+import { FastPathTableStructure } from '../../shared/format-utils/table-structure.js';
+export type ServerTablePdfExportDecision = {
+    action: 'use_fast_pdf';
+    sourceRecordCount: number;
+    renderedBodyRowCount: number;
+    tableStructure: FastPathTableStructure;
+} | {
+    action: 'use_rendered_pdf';
+    reason: 'unsupported_card_type' | 'server_paginated_sql_with_python' | 'missing_invalid_or_empty_total_count' | 'complete_result_query_failed' | 'empty_fresh_result' | 'invalid_presentation_metadata' | 'table_structure_unavailable';
+} | {
+    action: 'stop_pdf_export';
+    reason: 'known_row_count_exceeds_limit' | 'fresh_row_count_exceeds_limit' | 'complete_result_truncated' | 'rendered_body_row_count_exceeds_limit';
+    customerMessage: string;
+};
+type PrepareServerTablePdfExportInput = {
+    apiServiceUrl: string;
+    authToken: string;
+    card: TCard;
+    displayedTotalCount: unknown;
+    queryContract: DashboardCardQueryContract;
+    effectiveCardConfig?: CardConfig;
+    tablePreferences?: TablePreferences;
+    numericPresentation?: CardNumericPresentationContext;
+    reportContext: ReportRuntimeContext;
+};
+/**
+ * Acquires and prepares one complete Fast PDF candidate for a server-paginated
+ * regular/detail table. It never loops pages or rewrites authored SQL.
+ */
+export declare function prepareServerTablePdfExport({ apiServiceUrl, authToken, card, displayedTotalCount, queryContract, effectiveCardConfig, tablePreferences, numericPresentation, reportContext, }: PrepareServerTablePdfExportInput): Promise<ServerTablePdfExportDecision>;
+export {};

package/dist/types/lib/print-state/capture-expanded-state.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Print State Protocol - State Capture Utilities
+ *
+ * Captures the current expanded state of elements following the print protocol.
+ * Used by export-dialog.tsx to capture state before PDF generation.
+ *
+ * Protocol Contract:
+ * - Elements must have `data-spr-expand-id="unique-stable-id"`
+ * - Elements must have `aria-expanded="true|false"`
+ * - Elements must be clickable (respond to .click())
+ */
+/**
+ * Captures the current expanded state of all elements following the print protocol.
+ *
+ * @returns Record of expand IDs to their expanded boolean state
+ *
+ * @example
+ * // In a component with expandable sections:
+ * // <button data-spr-expand-id="section:123" aria-expanded="true">...</button>
+ * // <button data-spr-expand-id="section:456" aria-expanded="false">...</button>
+ *
+ * const state = captureExpandedStateFromDom();
+ * // Returns: { "section:123": true, "section:456": false }
+ */
+export declare function captureExpandedStateFromDom(): Record<string, boolean>;
+/**
+ * Checks if any expandable elements exist in the DOM that follow the print protocol.
+ *
+ * @returns true if any elements with data-spr-expand-id exist
+ */
+export declare function hasExpandableElements(): boolean;
+/**
+ * Captures only the expanded elements (optimization to reduce state size).
+ * Since collapsed is the default state, we only need to track what's expanded.
+ *
+ * @returns Record of expand IDs that are currently expanded (value is always true)
+ */
+export declare function captureExpandedOnlyState(): Record<string, boolean>;

package/dist/types/lib/print-state/use-expose-print-state.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Print state structure exposed to window for Lambda/Puppeteer access.
+ */
+export type PrintState = {
+    expandedState?: Record<string, boolean>;
+};
+declare global {
+    interface Window {
+        __SEMAPHOR_PRINT_STATE__?: PrintState;
+    }
+}
+/**
+ * Hook that exposes print state to the window object for Lambda/Puppeteer to access.
+ *
+ * Used by visual-view.tsx and view-container.tsx during PDF rendering to make
+ * the captured expanded state available to the PDF generator.
+ *
+ * @param isPdfRender - Whether the current render is for PDF generation
+ * @param printState - The print state to expose (expandedState, etc.)
+ *
+ * @example
+ * // In visual-view.tsx or view-container.tsx:
+ * const expandedState = useMemo(() => {
+ *   const param = searchParams.get('expandedState');
+ *   return param ? JSON.parse(param) : null;
+ * }, [searchParams]);
+ *
+ * useExposePrintState(isPdfRender, expandedState ? { expandedState } : null);
+ */
+export declare function useExposePrintState(isPdfRender: boolean, printState: PrintState | null): void;

package/dist/types/lib/python/default-code.d.ts

@@ -0,0 +1 @@
+export declare const PYTHON_DEFAULT_CODE = "import pandas as pd\ndf = pd.DataFrame(data)  # 'data' contains the query result\nresult = df.to_dict('records')  # must return 'result' as [dict] type\n";

package/dist/types/lib/query-context/build-card-control-context.d.ts

@@ -0,0 +1,16 @@
+import { ControlBinding, ControlDefinition, TCard } from '../types/common-types.js';
+export type BuildCardControlContextParams = {
+    card: TCard;
+    presentationControlIds: ReadonlySet<string>;
+    dashboardControls?: ControlDefinition[];
+    dashboardControlValues?: Record<string, unknown>;
+    cardControlValues?: Record<string, unknown>;
+};
+export type CardControlContext = {
+    controlValues: Record<string, unknown>;
+    controlDefinitions: ControlDefinition[];
+    cardControlDefinitions: ControlDefinition[];
+    controlBindings: ControlBinding[];
+};
+export declare function buildCardControlContext(params: BuildCardControlContextParams): CardControlContext;
+export declare function projectCardControlContextForQuery(card: TCard, context: CardControlContext, presentationControlIds: ReadonlySet<string>): CardControlContext;

package/dist/types/lib/query-context/build-card-query-context.d.ts

@@ -0,0 +1,45 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { ControlBinding, ControlDefinition, ResolvedDashboardDateComparisonInput, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
+import { GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { CardConfig } from '../types/explorer-types.js';
+import { resolveFiltersFromInteractionStates } from '../stores/interaction-store.js';
+import { ClickFilterEvent, InteractionState } from '../types/interaction-types.js';
+import { DashboardCardFilterCompilationInput } from './compile-dashboard-card-filters.js';
+import { ResolvedCardDateFields } from './resolve-card-primary-date-field.js';
+export type InteractionStateMap = Record<string, InteractionState | undefined>;
+export type BuildCardQueryContextParams = {
+    card: TCard;
+    dashboard: Pick<TDashboard, 'sheets'>;
+    interactionStates: InteractionStateMap | undefined;
+    currentDashboardId: string | undefined;
+    filters: TFilter[] | undefined;
+    filterValues: TFilterValue[] | undefined;
+    selectedSheetId: string | null | undefined;
+    inlineFilterValuesMap: Record<string, TFilterValue[] | undefined> | undefined;
+    dashboardControls?: ControlDefinition[] | undefined;
+    dashboardControlValues?: Record<string, unknown> | undefined;
+    cardControlValuesMap?: Record<string, Record<string, unknown> | undefined> | undefined;
+    dashboardInputContext?: ResolvedDashboardInputContext | undefined;
+    /** False when the analytical definition already owns its authored filters. */
+    includeAuthoredFilters?: boolean;
+};
+export type CardQueryContext = {
+    resolvedDateFields?: ResolvedCardDateFields;
+    filterCompilationInput: DashboardCardFilterCompilationInput;
+    controlValues: Record<string, unknown>;
+    controlDefinitions: ControlDefinition[];
+    cardControlDefinitions: ControlDefinition[];
+    controlBindings: ControlBinding[];
+    resolvedFilters: ReturnType<typeof resolveFiltersFromInteractionStates>;
+    finalConfig: CardConfig;
+    queryRelevantConfig: CardConfig;
+    finalFiltersKey: string;
+    appliedClickFilters: ClickFilterEvent[] | undefined;
+};
+export type CompiledCardQueryContext = Omit<CardQueryContext, 'filterCompilationInput'> & {
+    cardFilterValues: TFilterValue[];
+    queryFilterDefinitions: TFilter[];
+    globalDateComparisonSelection?: GlobalDateComparisonSelection;
+    dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
+};
+export declare function buildCardQueryContext({ card, dashboard, interactionStates, currentDashboardId, filters, filterValues, selectedSheetId, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputContext, includeAuthoredFilters, }: BuildCardQueryContextParams): CardQueryContext;

package/dist/types/lib/query-context/build-dashboard-card-query-contract.d.ts

@@ -0,0 +1,67 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { getCacheConfig } from '../stores/utils.js';
+import { ControlBinding, ControlDefinition, TCard } from '../types/common-types.js';
+import { CardConfig } from '../types/explorer-types.js';
+import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
+import { TableConfig } from '../types/query-types.js';
+import { CardQueryContext, CompiledCardQueryContext } from './build-card-query-context.js';
+import { GlobalDateComparisonContext } from '../../shared/analytics-protocol/index.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { CompiledDashboardCardFilters, CompileDashboardCardFiltersParams } from './compile-dashboard-card-filters.js';
+import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
+export type DashboardCardQueryRequestPayloadBase = {
+    cardId: string;
+    sql: string;
+    python: string;
+    resultOwner: TemporalResultOwner;
+    active_filters: TFilterValue[];
+    controlValues: Record<string, unknown>;
+    controlDefinitions: ControlDefinition[];
+    cardControlDefinitions: ControlDefinition[];
+    controlBindings: ControlBinding[];
+    cache_config: ReturnType<typeof getCacheConfig>;
+    queryConfig: TCard['queryConfig'];
+    tableConfig: TableConfig;
+    cardType: TCard['type'];
+    cardTitle: string;
+    cardConfig: CardConfig;
+    cardDataSource: TCard['dataSource'];
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    globalDateComparison?: GlobalDateComparisonContext;
+    calendarContext: CalendarContext;
+};
+export type DashboardCardQueryContract = {
+    status: 'ready';
+    queryKey: string[];
+    requestPayloadBase: DashboardCardQueryRequestPayloadBase;
+    tableConfig: TableConfig;
+    compiledFilters: CompiledDashboardCardFilters;
+};
+export type DashboardCardQueryContractResult = DashboardCardQueryContract | {
+    status: 'blocked';
+    cardId: string;
+    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
+    tableConfig: TableConfig;
+};
+/** Test/invariant helper for fixtures that cannot contain mapped inputs. */
+export declare function requireReadyDashboardCardQueryContract(result: DashboardCardQueryContractResult): DashboardCardQueryContract;
+export type DashboardCardQueryExecutionOptions = {
+    selectedLensId?: string;
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    calendarContext: CalendarContext;
+    allowGlobalDateMinutePrecision?: boolean;
+    globalDateComparisonReferenceTime?: string;
+};
+/** One final compilation for interactive requests and immutable input captures. */
+export declare function compileDashboardCardQueryContext(card: TCard, context: CardQueryContext, execution: Omit<CompileDashboardCardFiltersParams, 'card' | 'cardConfig' | 'input'>): {
+    status: "blocked";
+    cardId: string;
+    mappingDispositions: import('./dashboard-filter-mapping-resolution.js').DashboardFilterMappingDisposition[];
+} | {
+    status: "ready";
+    queryContext: CompiledCardQueryContext;
+    compiledFilters: CompiledDashboardCardFilters & {
+        status: "ready";
+    };
+};
+export declare function buildDashboardCardQueryContract(card: TCard, context: CardQueryContext, execution: DashboardCardQueryExecutionOptions): DashboardCardQueryContractResult;

package/dist/types/lib/query-context/build-dashboard-execution-snapshot.d.ts

@@ -0,0 +1,54 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInputValues, TCard, TDashboard } from '../types/common-types.js';
+import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
+import { BuildCardQueryContextParams, CompiledCardQueryContext } from './build-card-query-context.js';
+import { CompiledDashboardCardFilters } from './compile-dashboard-card-filters.js';
+import { DashboardInputResolveMode } from '../dashboard-inputs/resolve-dashboard-input-context.js';
+import { prepareMatrixCard, MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
+export type DashboardExecutionSnapshot = {
+    selectedSheetId: string | null;
+    filterValues: TFilterValue[];
+    controlValues: Record<string, unknown>;
+};
+type BuildDashboardExecutionSnapshotParams = {
+    dashboard: Pick<TDashboard, 'filters' | 'sheets'> | undefined;
+    filterValues: TFilterValue[] | undefined;
+    selectedSheetId: string | null | undefined;
+    sheetSelection?: 'current' | 'all';
+    dashboardControlValues?: Record<string, unknown>;
+    cardControlValuesMap?: Record<string, Record<string, unknown> | undefined> | undefined;
+    semanticExecutionPayload?: SemanticExecutionPayload;
+    timezone?: string;
+};
+export declare function buildDashboardExecutionSnapshot({ dashboard, filterValues, selectedSheetId, sheetSelection, dashboardControlValues, cardControlValuesMap, semanticExecutionPayload, timezone, }: BuildDashboardExecutionSnapshotParams): DashboardExecutionSnapshot;
+export type BuildDashboardCardExecutionSnapshotParams = Omit<BuildCardQueryContextParams, 'card' | 'dashboard' | 'selectedSheetId' | 'currentDashboardId' | 'dashboardInputContext'> & {
+    dashboard: TDashboard | undefined;
+    cardId: string;
+    currentDashboardId?: string;
+    dashboardInputValues?: DashboardInputValues;
+    dashboardInputMode?: DashboardInputResolveMode;
+    semanticExecutionPayload?: SemanticExecutionPayload;
+    timezone?: string;
+    /** Current columns metadata for all Matrix targets participating in coverage. */
+    matrixCatalog?: MatrixCardCatalog;
+    /** Editor drafts replace their persisted card only for this computation. */
+    cardOverride?: TCard;
+    sheetId?: string | null;
+};
+export type DashboardCardExecutionSnapshot = {
+    status: 'ready';
+    card: TCard;
+    sheetId: string;
+    queryContext: CompiledCardQueryContext;
+    matrix?: ReturnType<typeof prepareMatrixCard>;
+};
+export type DashboardCardExecutionSnapshotResult = DashboardCardExecutionSnapshot | {
+    status: 'blocked';
+    cardId: string;
+    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
+    reason?: 'metadata' | 'configuration' | 'coverage';
+    message?: string;
+} | null;
+export declare function requireReadyDashboardCardExecutionSnapshot(result: DashboardCardExecutionSnapshotResult): DashboardCardExecutionSnapshot | null;
+export declare function buildDashboardCardExecutionSnapshot({ dashboard, cardId, interactionStates, currentDashboardId, semanticExecutionPayload, filters, filterValues, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputValues, dashboardInputMode, timezone, matrixCatalog, cardOverride, sheetId, }: BuildDashboardCardExecutionSnapshotParams): DashboardCardExecutionSnapshotResult;
+export {};

package/dist/types/lib/query-context/build-dashboard-frame-base-query-contexts.d.ts

@@ -0,0 +1,50 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { ControlDefinition, DashboardInputValues, TCard, TDashboard, TFrame } from '../types/common-types.js';
+import { CardQueryContext, InteractionStateMap } from './build-card-query-context.js';
+export type DashboardFrameDocumentQueryState = {
+    isExplicitDocumentSectionRuntime: boolean;
+    isDocumentSectionEditing: boolean;
+    editedDocumentSectionCardId?: string;
+    editorDocumentSheetId?: string;
+    editorDocumentSectionId?: string;
+    explicitDocumentSheetId?: string;
+    explicitDocumentSectionId?: string;
+    editorDocumentFilterValues?: TFilterValue[];
+    editorDocumentControlDefinitions?: ControlDefinition[];
+    editorDocumentControlValues?: Record<string, unknown>;
+    editorMissingRequiredInputLabels?: string[];
+    explicitDocumentFilterValues?: TFilterValue[];
+    explicitDocumentControlDefinitions?: ControlDefinition[];
+    explicitDocumentControlValues?: Record<string, unknown>;
+    explicitDocumentDashboardInputValues?: DashboardInputValues;
+};
+export type BuildDashboardFrameBaseQueryContextsParams = {
+    cards: TCard[];
+    dashboard: TDashboard;
+    filters?: TFilter[];
+    dashboardControls?: ControlDefinition[];
+    filterValues?: TFilterValue[];
+    controlValues?: Record<string, unknown>;
+    dashboardInputValues?: DashboardInputValues;
+    dashboardInlineFilterValuesMap: Record<string, TFilterValue[]>;
+    editorInlineFilterValuesMap: Record<string, TFilterValue[] | undefined>;
+    dashboardCardControlValuesMap: Record<string, Record<string, unknown>>;
+    interactionStates?: InteractionStateMap;
+    filteringCards?: TCard[];
+    selectedSheetId?: string | null;
+    currentDashboardId?: string;
+    isVisualEditing: boolean;
+    getCardFrame: (cardId: string) => TFrame | undefined;
+    lastRequestPayloadMap?: Map<string, Record<string, unknown>>;
+    documentState: DashboardFrameDocumentQueryState;
+};
+export type DashboardFrameBaseQueryContext = CardQueryContext & {
+    card: TCard;
+    interval: number;
+    isFilteringCard: boolean;
+    isSingleCardFrame: boolean;
+    isDocumentSectionRuntime: boolean;
+    missingRequiredInputLabels: string[];
+    dashboardInputMissingRequiredLabels: string[];
+};
+export declare function buildDashboardFrameBaseQueryContexts({ cards, dashboard, filters, dashboardControls, filterValues, controlValues, dashboardInputValues, dashboardInlineFilterValuesMap, editorInlineFilterValuesMap, dashboardCardControlValuesMap, interactionStates, filteringCards, selectedSheetId, currentDashboardId, isVisualEditing, getCardFrame, lastRequestPayloadMap, documentState, }: BuildDashboardFrameBaseQueryContextsParams): DashboardFrameBaseQueryContext[];

package/dist/types/lib/query-context/build-global-date-comparison-context.d.ts

@@ -0,0 +1,9 @@
+import { TCard } from '../types/common-types.js';
+import { DashboardDateComparisonOwner, GlobalDateComparisonContext, GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { DashboardDateComparisonResolution } from '../dashboard-inputs/dashboard-date-comparison-plan.js';
+export declare function buildGlobalDateComparisonContext(card: Pick<TCard, 'preferences'>, selection: GlobalDateComparisonSelection | undefined, referenceTime?: string, owner?: DashboardDateComparisonOwner): GlobalDateComparisonContext | undefined;
+export declare function buildDashboardDateComparisonContext(params: {
+    card: TCard;
+    resolution: DashboardDateComparisonResolution;
+    referenceTime?: string;
+}): GlobalDateComparisonContext | undefined;

package/dist/types/lib/query-context/build-query-relevant-card-config.d.ts

@@ -0,0 +1,15 @@
+import { CardConfig, DataSource, FilterGroup } from '../types/explorer-types.js';
+import { TChartType } from '../charts/types.js';
+import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
+import { ShelfDefinitionCard } from '../utils/card-definition.js';
+export declare function buildQueryRelevantFilterGroup(group?: FilterGroup, omitTemporalPresentation?: boolean): FilterGroup | undefined;
+type BuildQueryRelevantCardConfigOptions = {
+    cardType?: TChartType;
+    dataSource?: DataSource;
+    temporalResultOwner?: TemporalResultOwner;
+};
+export declare function buildQueryRelevantCardConfig(config: CardConfig | undefined, options: BuildQueryRelevantCardConfigOptions & {
+    cardType: TChartType;
+}): CardConfig | undefined;
+export declare function buildShelfQueryRelevantCardConfig(card: ShelfDefinitionCard, execution?: Omit<BuildQueryRelevantCardConfigOptions, 'cardType'>): CardConfig | undefined;
+export {};

package/dist/types/lib/query-context/compile-dashboard-card-filters.d.ts

@@ -0,0 +1,72 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { NormalizedDashboardInput, ResolvedDashboardInput, ResolvedDashboardDateComparisonInput, TCard } from '../types/common-types.js';
+import { GlobalDateComparisonContext, GlobalDateComparisonSelection } from '../../shared/analytics-protocol/index.js';
+import { ResolvedPrimaryDateField, SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
+import { CardConfig } from '../types/explorer-types.js';
+import { DashboardFilterMappingDisposition } from './dashboard-filter-mapping-resolution.js';
+import { resolveMaterializedCardFilterValues } from './global-date-filter-materialization.js';
+import { ResolvedCardDateFields } from './resolve-card-primary-date-field.js';
+/**
+ * Hydrated filter state that still needs card-specific composition and
+ * materialization. Upstream adapters may resolve values and drill policy, but
+ * they must not merge or retarget values before handing them to the compiler.
+ */
+export type DashboardCardFilterCompilationInput = {
+    filterDefinitions: TFilter[];
+    filterValues: TFilterValue[];
+    selectedSheetId: string | null | undefined;
+    inlineFilterValues: TFilterValue[];
+    shouldApplyDashboardFilters: boolean;
+    dashboardInputContext?: DashboardFilterCompilationContext;
+    globalDateComparisonSelection?: GlobalDateComparisonSelection;
+    dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
+};
+type DashboardFilterCompilationContext = {
+    inputs: NormalizedDashboardInput[];
+    resolvedInputs: ResolvedDashboardInput[];
+    activeFilters: TFilterValue[];
+};
+export type CompileDashboardCardFiltersParams = {
+    card: TCard;
+    cardConfig: CardConfig;
+    input: DashboardCardFilterCompilationInput;
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    resolvedFields?: ResolvedCardDateFields;
+    semanticExecutionPayload?: SemanticExecutionPayload;
+    timezone?: string;
+    allowMinutePrecision?: boolean;
+    comparisonReferenceTime?: string;
+};
+export type CompiledDashboardCardFilters = {
+    cardFilterValues: TFilterValue[];
+    queryFilterDefinitions: TFilter[];
+    resolvedPrimaryDateField: ResolvedPrimaryDateField | null;
+    dateComparisonPlan: ReturnType<typeof resolveMaterializedCardFilterValues>['dateComparisonPlan'];
+    globalDateComparison: GlobalDateComparisonContext | undefined;
+    mappingDispositions: DashboardFilterMappingDisposition[];
+};
+export type DashboardCardFilterCompilationResult = (CompiledDashboardCardFilters & {
+    status: 'ready';
+}) | {
+    status: 'blocked';
+    cardId: string;
+    mappingDispositions: DashboardFilterMappingDisposition[];
+};
+/** Test/invariant helper for call sites that construct a provably unmapped input. */
+export declare function requireReadyDashboardCardFilters(result: DashboardCardFilterCompilationResult): CompiledDashboardCardFilters & {
+    status: 'ready';
+};
+export declare function composeCardFilterValues(card: TCard, input: DashboardCardFilterCompilationInput): {
+    status: 'ready';
+    filterValues: TFilterValue[];
+    mappingDispositions: DashboardFilterMappingDisposition[];
+} | {
+    status: 'blocked';
+    mappingDispositions: DashboardFilterMappingDisposition[];
+};
+/**
+ * The single final per-card filter compiler. Every card execution consumer
+ * calls this once and treats its result as immutable query state.
+ */
+export declare function compileDashboardCardFilters({ card, cardConfig, input, resolvedPrimaryDateField, resolvedFields, semanticExecutionPayload, timezone, allowMinutePrecision, comparisonReferenceTime, }: CompileDashboardCardFiltersParams): DashboardCardFilterCompilationResult;
+export {};

package/dist/types/lib/query-context/control-contract-serialization.d.ts

@@ -0,0 +1,11 @@
+import { ControlBinding, ControlDefinition } from '../types/common-types.js';
+type ControlContract = {
+    controlDefinitions?: ControlDefinition[];
+    cardControlDefinitions?: ControlDefinition[];
+    controlBindings?: ControlBinding[];
+};
+type SerializeControlContractOptions = {
+    includePresentation?: boolean;
+};
+export declare function serializeControlContract(contract?: ControlContract, options?: SerializeControlContractOptions): string;
+export {};

package/dist/types/lib/query-context/dashboard-card-query-key.d.ts

@@ -0,0 +1,28 @@
+import { ControlBinding, ControlDefinition, TCard } from '../types/common-types.js';
+import { ResolvedPrimaryDateField } from '../types/semantic-runtime-types.js';
+import { CardConfig } from '../types/explorer-types.js';
+import { GlobalDateComparisonContext } from '../../shared/analytics-protocol/index.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+export declare const isPaginatedCardType: (card: TCard) => boolean;
+export type CreateDashboardCardQueryKeyOptions = {
+    finalFiltersKey: string;
+    selectedLensId?: string;
+    cardFilterValues: unknown;
+    controlValues?: Record<string, unknown>;
+    controlDefinitions?: ControlDefinition[];
+    cardControlDefinitions?: ControlDefinition[];
+    controlBindings?: ControlBinding[];
+    queryRelevantConfig?: CardConfig;
+    resolvedPrimaryDateField?: ResolvedPrimaryDateField;
+    globalDateComparison?: GlobalDateComparisonContext;
+    calendarContext: CalendarContext;
+};
+export declare function dashboardCardQueryKeysShareCalendarIdentity(currentQueryKey: readonly unknown[], previousQueryKey: readonly unknown[] | undefined): boolean;
+export declare function dashboardCardQueryKeysMatch(currentQueryKey: readonly unknown[], previousQueryKey: readonly unknown[] | undefined): boolean;
+/**
+ * Returns the semantic identity of a dashboard-card query key. React Query
+ * callers can rebuild equivalent key arrays during ordinary renders, so
+ * lifecycle effects must depend on this value rather than array identity.
+ */
+export declare function serializeDashboardCardQueryKey(queryKey: readonly unknown[]): string;
+export declare function createDashboardCardQueryKey(card: TCard, { finalFiltersKey, selectedLensId, cardFilterValues, controlValues, controlDefinitions, cardControlDefinitions, controlBindings, queryRelevantConfig, resolvedPrimaryDateField, globalDateComparison, calendarContext, }: CreateDashboardCardQueryKeyOptions): string[];

package/dist/types/lib/query-context/dashboard-filter-mapping-resolution.d.ts

@@ -0,0 +1,36 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { NormalizedFilterDashboardInput, ResolvedDashboardInput, TCard } from '../types/common-types.js';
+export type DashboardFilterMappingSkipReason = 'outsideScope' | 'noSelection' | 'explicitlyExcluded' | 'notApplicable';
+export type DashboardFilterMappingBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'invalidSelection' | 'incompatibleValueType' | 'unsupportedTarget';
+export type DashboardFilterMappingDisposition = {
+    status: 'apply';
+    inputId: string;
+    /** Present only for an explicit persisted card override. */
+    bindingId?: string;
+    filterValue: TFilterValue;
+} | {
+    status: 'skip';
+    inputId: string;
+    bindingId?: string;
+    reason: DashboardFilterMappingSkipReason;
+} | {
+    status: 'block';
+    inputId: string;
+    bindingId?: string;
+    reason: DashboardFilterMappingBlockReason;
+};
+export type DashboardFilterMappingResolution = {
+    status: 'ready';
+    filterValues: TFilterValue[];
+    dispositions: DashboardFilterMappingDisposition[];
+} | {
+    status: 'blocked';
+    dispositions: DashboardFilterMappingDisposition[];
+};
+export declare function resolveDashboardFilterMappings({ card, inputs, resolvedInputs, activeFilterValues, shouldApplyDashboardFilters, }: {
+    card: TCard;
+    inputs: NormalizedFilterDashboardInput[];
+    resolvedInputs: ResolvedDashboardInput[];
+    activeFilterValues?: TFilterValue[];
+    shouldApplyDashboardFilters: boolean;
+}): DashboardFilterMappingResolution;

package/dist/types/lib/query-context/dashboard-query-result-context.d.ts

@@ -0,0 +1,17 @@
+import { CardConfig } from '../types/explorer-types.js';
+import { TemporalResultOwner } from '../../shared/dashboard-authoring/index.js';
+export type DashboardQueryResultContext = {
+    queryIdentity: string;
+    effectiveCardConfig: CardConfig;
+};
+export declare function serializeDashboardQueryIdentity(queryKey: readonly unknown[]): string;
+/**
+ * Binds request-owned state to the response produced by that exact request.
+ * Retained results keep this context, so consumers can avoid pairing old rows
+ * with a newer structural config while the next query is running.
+ */
+export declare function bindDashboardQueryResultContext<T>(response: T, input: DashboardQueryResultContext & {
+    resultOwner: TemporalResultOwner;
+}): T;
+export declare function bindDashboardQueryResultOwnership<T>(response: T, resultOwner: TemporalResultOwner): T;
+export declare function readDashboardQueryResultContext(result: unknown): DashboardQueryResultContext | undefined;