react-semaphor 0.1.544 → 0.1.546

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[];

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

@@ -73,6 +73,75 @@ export declare function validateDashboardFilterTargetForCard(params: {
     sourceIndex: ReturnType<typeof buildDashboardCardSourceIndex>;
     target: DashboardFilterTarget;
 }): DashboardFilterTargetValidation;
+/**
+ * Where a filter input lands on a card: the one decision execution
+ * (`resolveDashboardFilterMappings`) and every description of reach (the
+ * dashboard outline, the change resolver's reach warnings and filter-effect
+ * check) make, in one order: the card's mapping entry (excluded, or a bound
+ * target the card must still address), then SQL Auto, then the automatic and
+ * inherited targets. A selected value only supplies the automatic target's
+ * data type when the input states none.
+ */
+export type DashboardFilterCardTarget = {
+    status: 'excluded';
+} | {
+    status: 'bound';
+    bindingId: string;
+    target: DashboardFilterTarget;
+    validation: Extract<DashboardFilterTargetValidation, {
+        status: 'valid';
+    }>;
+}
+/**
+ * A bound target the card can't run, no longer addresses, or whose type the
+ * filter's values can't take: the card blocks until it is mapped again.
+ */
+ | {
+    status: 'unsupportedTarget' | 'stale' | 'incompatible';
+    bindingId: string;
+} | {
+    status: 'sql';
+} | {
+    status: 'automatic';
+    target: DashboardFilterTarget;
+}
+/**
+ * The card's data takes the filter's field (the one applicability rule) but
+ * not through a source its query uses, such as a dataset it selects or
+ * joins: the value applies as it is, as it does for a filter with no card
+ * mappings.
+ */
+ | {
+    status: 'passthrough';
+} | {
+    status: 'ambiguous';
+} | {
+    status: 'notApplicable';
+};
+/** The filter's mapping marks the card "Don't apply" (the first step of `decideDashboardFilterCardTarget`). */
+export declare function isDashboardFilterCardExcluded(input: NormalizedFilterDashboardInput, cardId: string): boolean;
+export declare function decideDashboardFilterCardTarget(input: NormalizedFilterDashboardInput, card: TCard, sourceIndex?: ReturnType<typeof buildDashboardCardSourceIndex>, selectedValue?: TFilterValue): DashboardFilterCardTarget;
+/** How a filter applies to a card, whatever value it holds. */
+export type DashboardFilterCardReach = 
+/** The mapping marks the card "Don't apply". */
+'excluded'
+/** The mapping binds the filter to a field of the card. */
+ | 'bound'
+/** The card executes the filter's own field (or a proven binding's), so it applies with no mapping. */
+ | 'automatic'
+/** A SQL card takes the filter's value as is. */
+ | 'sql'
+/** More than one field of the card could take it: the card blocks until it is mapped. */
+ | 'ambiguous'
+/** The mapping binds a target the card can't run or no longer has: the card blocks until it is mapped again. */
+ | 'blocked' | 'notApplicable';
+/**
+ * Whether a filter in scope reaches a card, read without a value, from the
+ * decision execution makes (`decideDashboardFilterCardTarget`). The dashboard
+ * outline and the change resolver read it, so they report what the card runs
+ * (MCP dashboard editing SPEC 3.6, 5.4).
+ */
+export declare function describeDashboardFilterCardReach(input: NormalizedFilterDashboardInput, card: TCard): DashboardFilterCardReach;
 export declare function resolveDashboardFilterMappings({ card, inputs, resolvedInputs, activeFilterValues, shouldApplyDashboardFilters, }: {
     card: TCard;
     inputs: NormalizedFilterDashboardInput[];