react-semaphor 0.1.543 → 0.1.545

package/dist/types/lib/dashboard-viewer/viewer-state.d.ts

@@ -1,16 +1,13 @@
 import { DashboardInputValues, TDashboard } from '../types/common-types.js';
 import { TFilterValue } from '../../components/surfboard/filter/types.js';
 import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { HostFilterValue } from '../../shared/dashboard-authoring/filter-model/filter-values.js';
 import { ViewerTableSettings } from '../../shared/dashboard-viewer/table-settings.js';
 import { Bookmark, BookmarkState } from '../../shared/dashboard-viewer/viewer-contract.js';
 /** The report runtime's calendar, as filter defaults read it. */
 /** The viewer's report calendar, from report preferences (card query assembly CQ-D8). */
 export type ViewerCalendar = CalendarContext;
-/** A host filter default: a full filter value, or the short `{ filterId, values }` embed form. */
-export type HostFilterValue = TFilterValue | {
-    readonly filterId: string;
-    readonly values: string[] | number[];
-};
+export type { HostFilterValue };
 /** Host app defaults, exactly as hydration receives them today (embed props). */
 export type HostDefaults = {
     readonly filterValues?: readonly HostFilterValue[];
@@ -19,7 +16,11 @@ export type HostDefaults = {
     readonly selectedSheetId?: string;
 };
 export type ViewerBaseline = {
-    readonly filterValues: readonly TFilterValue[];
+    /**
+     * The host's filter defaults as input slots (M5 `hostFilterValuesToSlots`).
+     * Authored defaults are not seeded: input resolution hydrates them.
+     */
+    readonly hostInputValues: DashboardInputValues;
     /** Passed to `setDashboardWithFilterValues` as `runtimeOverrides`. */
     readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
     /** The host's sheet when valid, else the author's first sheet. */
@@ -55,9 +56,10 @@ export type RememberedSettingsWrite = {
 };
 /** The store values a view consists of. */
 export type ViewerValues = {
-    readonly filterValues: readonly TFilterValue[];
+    /** Runtime-only values no filter defines (one filter model SPEC 5.8). */
+    readonly adHocFilterValues: readonly TFilterValue[];
     readonly controlOverrides: Readonly<Record<string, unknown>> | undefined;
-    /** Runtime input slots: a bookmark's slots only (overlay). Never completed as `cleared`. */
+    /** Runtime input slots: the host's defaults with a bookmark's slots over them. Never completed as `cleared`. */
     readonly dashboardInputValues: DashboardInputValues;
     /** Card inline filter values when they differ from the cards' defaults. Absent: the defaults. */
     readonly inlineFilterValuesMap?: Readonly<Record<string, readonly TFilterValue[]>>;
@@ -90,7 +92,7 @@ export type ViewerLiveState = {
     readonly previousDashboard: TDashboard;
     /** The baseline of the previous hydration; a changed host prop wins over the live value. */
     readonly previousBaseline: ViewerBaseline | null;
-    readonly filterValues: readonly TFilterValue[];
+    readonly adHocFilterValues: readonly TFilterValue[];
     /**
      * Live control values, flattened. `undefined` when the control contract
      * changed: the baseline's control defaults apply again.

package/dist/types/lib/download-pdf.d.ts

@@ -44,7 +44,41 @@ export type VisualPdfParams = {
     presentationExecutionSnapshot: PresentationExecutionSnapshot;
     timezone?: string;
 };
-type VisualPrintRuntimeOverrides = {
+type DashboardPdfParams = {
+    /** The viewer's table settings captured at the click (PLAN B20). */
+    viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
+    authToken: AuthToken;
+    theme: string;
+    filterValues: TFilterValue[];
+    defaultControlValues?: Record<string, unknown>;
+    controlDefinitions?: ControlDefinition[];
+    cardControlDefinitions?: ControlDefinition[];
+    controlBindings?: ControlBinding[];
+    dashboardId: string;
+    fileName: string;
+    password?: string;
+    cardTitle?: string;
+    filterLine?: string;
+    timezone?: string;
+    dashboardTitle?: string;
+    selectedSheetId?: string;
+    sheetSelection?: 'current' | 'all';
+    visualId?: string;
+    frameId?: string;
+    tableMode?: boolean;
+    pdfMode?: 'document';
+    documentSheetId?: string;
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+    printInputCapture?: PrintInputCapture;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    documentInputValues?: DocumentInputRuntimeValues;
+    cardType?: string;
+    pageSize?: string;
+    orientation?: string;
+    expandedState?: Record<string, boolean>;
+    wideTableStrategy?: 'auto' | 'fit' | 'horizontal_paginate';
+};
+export type VisualPrintRuntimeOverrides = {
     filterValues?: TFilterValue[];
     /** Replaces the store's viewer table settings (`{}` where the authored table applies, such as the editor preview). */
     viewerTableSettings?: Readonly<Record<string, ViewerTableSettings>>;
@@ -73,6 +107,46 @@ export declare function appendControlContractParams(urlParams: URLSearchParams,
     cardControlDefinitions?: ControlDefinition[];
     controlBindings?: ControlBinding[];
 }): void;
+/**
+ * The render state the print view needs to reproduce what the user saw. It is
+ * posted with the presentation snapshot and stored server-side behind the
+ * snapshot reference; it never travels in a URL. Key names match the print
+ * view's props contract in the app (`PrintViewState`).
+ */
+type PrintViewStateInput = Pick<DashboardPdfParams, 'filterValues' | 'defaultControlValues' | 'controlDefinitions' | 'cardControlDefinitions' | 'controlBindings' | 'documentInputValues' | 'dashboardInputExecutionSnapshot' | 'printInputCapture' | 'expandedState' | 'viewerTableSettings'>;
+export declare function buildPrintViewState(params: PrintViewStateInput): {
+    viewerTableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    expandedState?: Record<string, boolean> | undefined;
+    printInputCapture?: PrintInputCapture | undefined;
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot | undefined;
+    documentInputValues?: DocumentInputRuntimeValues | undefined;
+    controlBindings?: ControlBinding[] | undefined;
+    cardControlDefinitions?: ControlDefinition[] | undefined;
+    controlDefinitions?: ControlDefinition[] | undefined;
+    filterValues: TFilterValue[];
+    controlValues: Record<string, unknown>;
+};
+/** A rendered export the server refused or could not make, with its error code when it sent one. */
+export declare class RenderedExportError extends Error {
+    readonly code: string | null;
+    constructor(message: string, code: string | null);
+}
+export type PrintViewStateBody = ReturnType<typeof buildPrintViewState>;
+/**
+ * The one transport for every file the renderer draws from the print view
+ * (PDF and PNG, PNG exports SPEC §3.1): the view state goes into a print
+ * render record, `query` (identity and options) and the record reference go
+ * to `GET /v1/pdf`, and the returned link is saved as `fileName`. Undefined
+ * when another rendered export is running in this dashboard; nothing is sent.
+ */
+export declare function requestRenderedFile(apiServiceUrl: string, request: {
+    authToken: AuthToken;
+    viewState: PrintViewStateBody;
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
+    password?: string;
+    query: URLSearchParams;
+    fileName: string;
+}): Promise<PdfDownloadResponse | undefined>;
 export declare function getDashboardParamsForPrint(authToken: AuthToken | undefined, options?: {
     selectedSheetId?: string | null;
     sheetSelection?: 'current' | 'all';

package/dist/types/lib/hooks/index.d.ts

@@ -6,8 +6,6 @@ import { useDebounce } from './use-debounce.js';
 import { useDebouncedEditorValue } from './use-debounced-editor-value.js';
 import { useClickOutside } from './use-click-outside.js';
 import { useStableValue, rowsEqual } from './use-stable-value.js';
-import { useExportPolling } from './use-export-polling.js';
-import { useExportRecovery } from './use-export-recovery.js';
 import { useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart } from './use-calendar-context.js';
 import { useValueFormatPreferences } from './use-value-format-preferences.js';
-export { useDashboard, useCard, useDataColumns, useAddNewFrame, useDebounce, useDebouncedEditorValue, useClickOutside, useStableValue, rowsEqual, useExportPolling, useExportRecovery, useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart, useValueFormatPreferences, };
+export { useDashboard, useCard, useDataColumns, useAddNewFrame, useDebounce, useDebouncedEditorValue, useClickOutside, useStableValue, rowsEqual, useCalendarContext, useResolvedDateStyle, useResolvedDateTimeDateStyle, useResolvedDateTimeTimeStyle, useResolvedDefaultCurrency, useResolvedValueFormatLocale, useReportPreferenceSources, useResolvedValueFormatPreferences, useTimezone, useWeekStart, useValueFormatPreferences, };

package/dist/types/lib/hooks/use-date-filter.d.ts

@@ -4,6 +4,11 @@ type UseDateFilterOptions = FilterStorageOptions;
 type DateFilterChangeOptions = {
     temporalPrecision?: TemporalPrecision;
 };
+/**
+ * The public hook: the filter resolves through the filter model, so any
+ * dashboard filter works, and its value is its input's slot on the current
+ * tab (one filter model SPEC 4.7).
+ */
 export declare function useDateFilterHook(filterId: string): {
     records: Record<string, unknown>[] | undefined;
     isLoading: boolean;

package/dist/types/lib/hooks/use-text-filter.d.ts

@@ -1,5 +1,10 @@
 import { TFilter, TFilterValue, TSelectedRecord, FilterStorageOptions } from '../../components/surfboard/filter/types.js';
 import { FilterMode } from '../filter-values/filter-mode.js';
+/**
+ * The public hook: the filter resolves through the filter model, so any
+ * dashboard filter works, and its value is its input's slot on the current
+ * tab (one filter model SPEC 4.7).
+ */
 export declare function useTextFilterHook(filterId: string): {
     isLoading: boolean;
     isFetching: boolean;

package/dist/types/lib/matrix-table/matrix-delivery-policy.d.ts

@@ -13,8 +13,9 @@ export declare const MATRIX_EXPORT_CONTENT: readonly [{
 /**
  * What a Matrix download or attachment may be: PDF, CSV and Excel for the
  * layout, CSV and Excel for Flat content, which is a data file only
- * (XL-D16). Downloads off leaves PDF of the layout. One policy for the export
- * dialog and Briefing attachments.
+ * (XL-D16). A PNG is the Matrix as it opens, so it belongs to the current
+ * layout only (PNG exports PN-SI-9). Downloads off leaves PDF and PNG of the
+ * layout. One policy for the export dialog and Briefing attachments.
  */
 export declare function matrixDeliveryOptions(allowDownload?: boolean, content?: MatrixExportContent): {
     contents: ({
@@ -27,7 +28,7 @@ export declare function matrixDeliveryOptions(allowDownload?: boolean, content?:
         readonly value: "flat";
         readonly label: "Flat aggregate table";
     })[];
-    formats: import('../types/index.js').BriefingAttachmentFormat[];
+    formats: ("csv" | "xlsx" | "pdf" | "png")[];
 };
 /** Matrix delivery requires an effective capture, never resident cells. */
-export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "unavailable" | "window" | "ordinary";
+export declare function resolveMatrixExportEngine(card: TCard | null | undefined, hasContext: boolean): "window" | "unavailable" | "ordinary";

package/dist/types/lib/matrix-table/matrix-delivery.d.ts

@@ -758,4 +758,8 @@ export declare function buildMatrixDeliveryPayload(input: {
 /** A Matrix data file request (CSV or Excel) for the direct path or a job. */
 export type MatrixFileExportRequest = ReturnType<typeof buildMatrixDeliveryPayload> & {
     format: ExportFileFormat;
+    /** One logical export (BA-D17): the direct attempt, its fallback and Run in background share it. */
+    exportRequestId: string;
+    /** 'background' skips the direct attempt (Run in background, BA-D11). */
+    delivery?: 'direct' | 'background';
 };

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

@@ -0,0 +1,158 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { CardViewStateMap } from '../dashboard-view-state/index.js';
+import { DashboardInputValues, ResolvedDashboardInputContext, TCard, TDashboard } from '../types/common-types.js';
+import { PaginationConfig } from '../types/explorer-types.js';
+import { ResolvedPrimaryDateField, SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
+import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+import { prepareMatrixCard, MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { CardQueryContext, CompiledCardQueryContext } from './build-card-query-context.js';
+import { DashboardCardQueryContractResult } from './build-dashboard-card-query-contract.js';
+import { CardQueryBlock, CompiledDashboardCardFilters } from './compile-dashboard-card-filters.js';
+import { DocumentSectionCardRuntime } from './document-section-card-query.js';
+import { CardRequestPayload } from './card-server-request.js';
+/**
+ * The one assembly of a card's query (card query assembly plan, CQ-D1): live
+ * cards, Matrix cards, exports, PDFs, Briefings, query keys, summaries, drill
+ * captures and the assistant all ask this module, so the same state always
+ * means the same query. Nothing else builds a card's query context or
+ * compiles it (the `check:guards` guard, CQ-INV-2).
+ *
+ * A caller's differences are data in its source and its place (CQ-D2); the
+ * module decides what each means. It is pure: hooks read the store and pass
+ * what they read.
+ */
+/**
+ * The state a card's query is built from: the dashboard store's current
+ * values, a capture's, or a print's.
+ */
+export type CardQuerySource = {
+    dashboard: TDashboard;
+    /**
+     * Runtime-only values no filter defines (chart clicks, summary chips; one
+     * filter model SPEC 5.8). Authored filter values are `dashboardInputValues`.
+     */
+    adHocFilterValues: TFilterValue[] | undefined;
+    controlValues: Record<string, unknown> | undefined;
+    inlineFilterValuesMap: Record<string, TFilterValue[] | undefined> | undefined;
+    cardControlValuesMap: Record<string, Record<string, unknown>> | undefined;
+    dashboardInputValues: DashboardInputValues | undefined;
+    /**
+     * Carried contexts in effect on the dashboard. Required so that every
+     * caller decides; see `buildCardQueryContext`. A section never receives them.
+     */
+    transientContexts: readonly TransientInputContext[] | undefined;
+    /** Drill paths by card. Required so that every caller decides; a section card does not drill. */
+    cardViewStates: CardViewStateMap | undefined;
+    /**
+     * Viewer table settings by card (dashboard bookmarks). Required so that
+     * every caller decides; a section card is not a viewer-customizable table.
+     */
+    viewerTableSettings: Readonly<Record<string, ViewerTableSettings>> | undefined;
+    /**
+     * The viewer's report calendar (report preferences): input defaults
+     * resolve in it and cards compile in its zone (CQ-D8). Null only before
+     * the report context loads.
+     */
+    calendar: CalendarContext | null;
+    /**
+     * The editor's preview: its card filter values win for the cards it shows,
+     * and it previews the authored table (no viewer table settings).
+     */
+    editor?: {
+        inlineFilterValuesMap: Record<string, TFilterValue[] | undefined>;
+    };
+};
+/** Where a card runs: a sheet of the dashboard, or a Document section with its own runtime. */
+export type CardQueryPlace = {
+    kind: 'sheet';
+    sheetId: string | null | undefined;
+} | {
+    kind: 'documentSection';
+    section: DocumentSectionCardRuntime;
+};
+export type AssembledCardQuery = {
+    /** The card the query runs: a section's card carries its document's control definitions. */
+    card: TCard;
+    context: CardQueryContext;
+    /** The inputs resolved for the card, when the dashboard resolves inputs. */
+    inputContext: ResolvedDashboardInputContext | undefined;
+};
+/** How a dashboard's cards compile (CQ-D3); one per dashboard, payload and calendar. */
+export type CardQueryCompileScope = {
+    calendarContext: CalendarContext;
+    /** Whether every card the dashboard date reaches has a timestamp field. */
+    allowGlobalDateMinutePrecision: boolean;
+    semanticExecutionPayload: SemanticExecutionPayload | undefined;
+    globalCacheConfig: TDashboard['globalCacheConfig'];
+};
+export type CompiledCardQuery = {
+    status: 'ready';
+    card: TCard;
+    queryContext: CompiledCardQueryContext;
+    compiledFilters: CompiledDashboardCardFilters;
+    resolvedPrimaryDateField: ResolvedPrimaryDateField;
+} | ({
+    status: 'blocked';
+    card: TCard;
+    cardId: string;
+    resolvedPrimaryDateField: ResolvedPrimaryDateField;
+} & CardQueryBlock);
+/** The compiler's inputs for a card at its place, from a source. */
+export declare function assembleCardQueryContext({ card, place, source, }: {
+    card: TCard;
+    place: CardQueryPlace;
+    source: CardQuerySource;
+}): AssembledCardQuery;
+export declare function resolveCardQueryCompileScope(dashboard: TDashboard, semanticExecutionPayload: SemanticExecutionPayload | undefined, calendar: CalendarContext | null): CardQueryCompileScope;
+/** Compiles an assembled card in its dashboard's scope. */
+export declare function compileCardQuery(assembled: Pick<AssembledCardQuery, 'card' | 'context'>, scope: CardQueryCompileScope): CompiledCardQuery;
+/**
+ * The request contract of an assembled card: its compiled filters, query
+ * identity and request payload.
+ */
+export declare function buildCardQueryContract(assembled: Pick<AssembledCardQuery, 'card' | 'context'>, scope: CardQueryCompileScope, options?: {
+    resolvePaginationConfig?: (queryInputIdentity: string) => PaginationConfig | undefined;
+}): DashboardCardQueryContractResult & {
+    resolvedPrimaryDateField: ResolvedPrimaryDateField;
+};
+export type AssembledCardQueryResult = (Extract<CompiledCardQuery, {
+    status: 'ready';
+}> & {
+    matrix?: ReturnType<typeof prepareMatrixCard>;
+    /**
+     * The request the card posts to /api/v1/query, from these same assembled
+     * inputs (`withRequest`; not for Matrix, which runs on its window path).
+     */
+    request?: CardRequestPayload;
+}) | BlockedCardQuery;
+/**
+ * A card query that cannot run, and why (SPEC 4.8): the compile's `mapping`
+ * and `requiredInput`, or the assembly's `metadata`, `configuration` and
+ * `coverage`. `message` is set for every reason except `mapping`, whose
+ * wording each surface owns.
+ */
+export type BlockedCardQuery = {
+    status: 'blocked';
+    cardId: string;
+    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
+    reason: CardQueryBlock['reason'] | 'metadata' | 'configuration' | 'coverage';
+    missingRequiredLabels: string[];
+    message?: string;
+};
+/**
+ * A card's compiled query, as the Matrix runtime and every capture run it: a
+ * Matrix card is prepared from the catalog (its spec owns its filters, and
+ * the dashboard date's precision covers only the cards it reaches).
+ */
+export declare function assembleCardQuery({ card: targetCard, place, source, semanticExecutionPayload, matrixCatalog, withRequest, }: {
+    card: TCard;
+    place: CardQueryPlace;
+    source: CardQuerySource;
+    semanticExecutionPayload: SemanticExecutionPayload | undefined;
+    /** Columns metadata for every Matrix target the dashboard date covers. */
+    matrixCatalog: MatrixCardCatalog | undefined;
+    /** Also build the card's request (the analytics agent replays it on the server, D3b-2). */
+    withRequest?: boolean;
+}): AssembledCardQueryResult;

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

@@ -33,8 +33,8 @@ export type BuildCardQueryContextParams = {
      * sort while the viewer sees their own.
      */
     viewerTableSettings: ViewerTableSettings | undefined;
-    filters: TFilter[] | undefined;
-    filterValues: TFilterValue[] | undefined;
+    /** Runtime-only values no filter defines (SPEC 5.8); authored values are input slots. */
+    adHocFilterValues: TFilterValue[] | undefined;
     selectedSheetId: string | null | undefined;
     inlineFilterValuesMap: Record<string, TFilterValue[] | undefined> | undefined;
     dashboardControls?: ControlDefinition[] | undefined;
@@ -73,4 +73,4 @@ export type CompiledCardQueryContext = Omit<CardQueryContext, 'filterCompilation
     globalDateComparisonSelection?: GlobalDateComparisonSelection;
     dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
 };
-export declare function buildCardQueryContext({ card, dashboard, transientContexts, cardViewState, viewerTableSettings, filters, filterValues, selectedSheetId, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputContext, includeAuthoredFilters, }: BuildCardQueryContextParams): CardQueryContext;
+export declare function buildCardQueryContext({ card, dashboard, transientContexts, cardViewState, viewerTableSettings, adHocFilterValues, selectedSheetId, inlineFilterValuesMap, dashboardControls, dashboardControlValues, cardControlValuesMap, dashboardInputContext, includeAuthoredFilters, }: BuildCardQueryContextParams): CardQueryContext;

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

@@ -5,7 +5,7 @@ import { TableConfig } from '../types/query-types.js';
 import { CardQueryContext, CompiledCardQueryContext } from './build-card-query-context.js';
 import { CalendarContext } from '../../shared/report-runtime-context/index.js';
 import { DashboardCardQueryRequestPayloadBase } from '../../shared/dashboard-authoring/card-query-request.js';
-import { CompiledDashboardCardFilters, CompileDashboardCardFiltersParams } from './compile-dashboard-card-filters.js';
+import { CardQueryBlock, CompiledDashboardCardFilters, CompileDashboardCardFiltersParams } from './compile-dashboard-card-filters.js';
 export type { DashboardCardQueryRequestPayloadBase } from '../../shared/dashboard-authoring/card-query-request.js';
 export type DashboardCardQueryContract = {
     status: 'ready';
@@ -16,12 +16,11 @@ export type DashboardCardQueryContract = {
     tableConfig: TableConfig;
     compiledFilters: CompiledDashboardCardFilters;
 };
-export type DashboardCardQueryContractResult = DashboardCardQueryContract | {
+export type DashboardCardQueryContractResult = DashboardCardQueryContract | ({
     status: 'blocked';
     cardId: string;
-    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
     tableConfig: TableConfig;
-};
+} & CardQueryBlock);
 /** Test/invariant helper for fixtures that cannot contain mapped inputs. */
 export declare function requireReadyDashboardCardQueryContract(result: DashboardCardQueryContractResult): DashboardCardQueryContract;
 export type DashboardCardQueryExecutionOptions = {
@@ -36,11 +35,21 @@ export type DashboardCardQueryExecutionOptions = {
     resolvePaginationConfig?: (queryInputIdentity: string) => PaginationConfig | undefined;
 };
 /** One final compilation for interactive requests and immutable input captures. */
-export declare function compileDashboardCardQueryContext(card: TCard, context: CardQueryContext, execution: Omit<CompileDashboardCardFiltersParams, 'card' | 'cardConfig' | 'input'>): {
+export declare function compileDashboardCardQueryContext(card: TCard, context: CardQueryContext, execution: Omit<CompileDashboardCardFiltersParams, 'card' | 'cardConfig' | 'input'>): ({
+    status: "blocked";
+    cardId: string;
+} & {
+    reason: "mapping";
+    mappingDispositions: import('./dashboard-filter-mapping-resolution.js').DashboardFilterMappingDisposition[];
+    missingRequiredLabels: [];
+}) | ({
     status: "blocked";
     cardId: string;
+} & {
+    reason: "requiredInput";
     mappingDispositions: import('./dashboard-filter-mapping-resolution.js').DashboardFilterMappingDisposition[];
-} | {
+    missingRequiredLabels: string[];
+}) | {
     status: "ready";
     queryContext: CompiledCardQueryContext;
     compiledFilters: CompiledDashboardCardFilters & {

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

@@ -6,18 +6,22 @@ import { TransientInputContext } from '../dashboard-inputs/transient-input-conte
 import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
 import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
 import { CompiledCardQueryContext } from './build-card-query-context.js';
-import { CompiledDashboardCardFilters } from './compile-dashboard-card-filters.js';
 import { CardRequestPayload } from './card-server-request.js';
 import { DocumentSectionCardRuntime } from './document-section-card-query.js';
 import { MatrixCardCatalog, prepareMatrixCard } from '../matrix-table/matrix-card-adapter.js';
+import { BlockedCardQuery } from './assemble-card-query.js';
 export type DashboardExecutionSnapshot = {
     selectedSheetId: string | null;
     filterValues: TFilterValue[];
     controlValues: Record<string, unknown>;
 };
 type BuildDashboardExecutionSnapshotParams = {
-    dashboard: Pick<TDashboard, 'filters' | 'sheets'> | undefined;
-    filterValues: TFilterValue[] | undefined;
+    dashboard: TDashboard | undefined;
+    /** Authored filter values: input slots (one filter model Phase 4a). */
+    dashboardInputValues: DashboardInputValues | undefined;
+    adHocFilterValues: TFilterValue[] | undefined;
+    /** The report calendar defaults resolve in. */
+    calendar: CalendarContext | null;
     selectedSheetId: string | null | undefined;
     sheetSelection?: 'current' | 'all';
     dashboardControlValues?: Record<string, unknown>;
@@ -25,7 +29,7 @@ type BuildDashboardExecutionSnapshotParams = {
     semanticExecutionPayload?: SemanticExecutionPayload;
     timezone?: string;
 };
-export declare function buildDashboardExecutionSnapshot({ dashboard, filterValues, selectedSheetId, sheetSelection, dashboardControlValues, cardControlValuesMap, semanticExecutionPayload, timezone, }: BuildDashboardExecutionSnapshotParams): DashboardExecutionSnapshot;
+export declare function buildDashboardExecutionSnapshot({ dashboard, dashboardInputValues, adHocFilterValues, calendar, selectedSheetId, sheetSelection, dashboardControlValues, cardControlValuesMap, semanticExecutionPayload, timezone, }: BuildDashboardExecutionSnapshotParams): DashboardExecutionSnapshot;
 export type BuildDashboardCardExecutionSnapshotParams = {
     dashboard: TDashboard | undefined;
     cardId: string;
@@ -41,7 +45,7 @@ export type BuildDashboardCardExecutionSnapshotParams = {
      * sort. Required so that every caller decides; see `buildCardQueryContext`.
      */
     viewerTableSettings: Readonly<Record<string, ViewerTableSettings>> | undefined;
-    filterValues: TFilterValue[] | undefined;
+    adHocFilterValues: TFilterValue[] | undefined;
     inlineFilterValuesMap: Record<string, TFilterValue[] | undefined> | undefined;
     dashboardControlValues?: Record<string, unknown> | undefined;
     cardControlValuesMap?: Record<string, Record<string, unknown> | undefined> | undefined;
@@ -80,14 +84,8 @@ export type DashboardCardExecutionSnapshot = {
     /** The request the card posts to /api/v1/query (`withRequest`; never for Matrix). */
     request?: CardRequestPayload;
 };
-export type DashboardCardExecutionSnapshotResult = DashboardCardExecutionSnapshot | {
-    status: 'blocked';
-    cardId: string;
-    mappingDispositions: CompiledDashboardCardFilters['mappingDispositions'];
-    reason?: 'metadata' | 'configuration' | 'coverage';
-    message?: string;
-} | null;
+export type DashboardCardExecutionSnapshotResult = DashboardCardExecutionSnapshot | BlockedCardQuery | null;
 export declare function requireReadyDashboardCardExecutionSnapshot(result: DashboardCardExecutionSnapshotResult): DashboardCardExecutionSnapshot | null;
 /** One card's compiled query from captured or current values, through the card query assembly. */
-export declare function buildDashboardCardExecutionSnapshot({ dashboard, cardId, transientContexts, cardViewStates, viewerTableSettings, semanticExecutionPayload, filterValues, inlineFilterValuesMap, dashboardControlValues, cardControlValuesMap, dashboardInputValues, calendar, matrixCatalog, cardOverride, sheetId, documentSection, editor, withRequest, }: BuildDashboardCardExecutionSnapshotParams): DashboardCardExecutionSnapshotResult;
+export declare function buildDashboardCardExecutionSnapshot({ dashboard, cardId, transientContexts, cardViewStates, viewerTableSettings, semanticExecutionPayload, adHocFilterValues, inlineFilterValuesMap, dashboardControlValues, cardControlValuesMap, dashboardInputValues, calendar, matrixCatalog, cardOverride, sheetId, documentSection, editor, withRequest, }: BuildDashboardCardExecutionSnapshotParams): DashboardCardExecutionSnapshotResult;
 export {};

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

@@ -12,8 +12,11 @@ import { ResolvedCardDateFields } from './resolve-card-primary-date-field.js';
  * they must not merge or retarget values before handing them to the compiler.
  */
 export type DashboardCardFilterCompilationInput = {
-    filterDefinitions: TFilter[];
-    filterValues: TFilterValue[];
+    /**
+     * Runtime-only values no filter defines (chart clicks, summary chips;
+     * one filter model SPEC 5.8). Authored values live in input slots.
+     */
+    adHocFilterValues: TFilterValue[];
     selectedSheetId: string | null | undefined;
     inlineFilterValues: TFilterValue[];
     shouldApplyDashboardFilters: boolean;
@@ -44,24 +47,31 @@ export type CompiledDashboardCardFilters = {
     globalDateComparison: GlobalDateComparisonContext | undefined;
     mappingDispositions: DashboardFilterMappingDisposition[];
 };
+/**
+ * Why a card's query cannot run (one filter model SPEC 4.8). `requiredInput`
+ * is reported over `mapping` when both apply: the viewer can resolve it.
+ */
+export type CardQueryBlock = {
+    reason: 'mapping';
+    mappingDispositions: DashboardFilterMappingDisposition[];
+    missingRequiredLabels: [];
+} | {
+    reason: 'requiredInput';
+    mappingDispositions: DashboardFilterMappingDisposition[];
+    missingRequiredLabels: string[];
+};
 export type DashboardCardFilterCompilationResult = (CompiledDashboardCardFilters & {
     status: 'ready';
-}) | {
+}) | ({
     status: 'blocked';
     cardId: string;
-    mappingDispositions: DashboardFilterMappingDisposition[];
-};
+} & CardQueryBlock);
+/** What a card shows, and exports and captures refuse with, for a `requiredInput` block. */
+export declare function describeMissingRequiredInputs(labels: readonly string[]): string;
 /** Test/invariant helper for call sites that construct a provably unmapped input. */
 export declare function requireReadyDashboardCardFilters(result: DashboardCardFilterCompilationResult): CompiledDashboardCardFilters & {
     status: 'ready';
 };
-/**
- * Whether a filter input still applies when a carried context turns the
- * dashboard's own filters off (`resolveContextAwareFilterPolicy`): only inputs
- * authored for specific cards and the cards' inline filters do. The one rule
- * for the compiler and for any reader that says which filters a view applies.
- */
-export declare function filterInputSurvivesCarriedContext(input: Pick<NormalizedDashboardInput, 'kind' | 'scope' | 'compatibility'>): boolean;
 export declare function composeCardFilterValues(card: TCard, input: DashboardCardFilterCompilationInput): {
     status: 'ready';
     filterValues: TFilterValue[];