react-semaphor 0.1.507 → 0.1.509

package/dist/types/lib/dashboard-inputs/resolve-field-date-comparison-coverage.d.ts

@@ -1,6 +1,6 @@
+import { CardViewStateMap } from '../dashboard-view-state/index.js';
 import { DashboardInput, TDashboard } from '../types/common-types.js';
 import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
-import { InteractionStateMap } from '../query-context/build-card-query-context.js';
 import { FieldDateComparisonCoverage } from './dashboard-date-comparison-plan.js';
 import { ResolveDashboardInputContextInput } from './resolve-dashboard-input-context.js';
 import { DashboardInputRuntimeTarget } from './dashboard-input-values.js';
@@ -11,7 +11,10 @@ export declare function resolveDashboardFieldDateComparisonCoverage(params: {
     }>;
     dashboardInputTarget: DashboardInputRuntimeTarget;
     runtimeValues: ResolveDashboardInputContextInput['runtimeValues'];
-    interactionStates?: InteractionStateMap;
+    /** Carried contexts in effect on this dashboard; see `buildCardQueryContext`. */
+    transientContexts: ResolveDashboardInputContextInput['transientContexts'];
+    /** Drill paths by card: a drilled card groups by another field. */
+    cardViewStates: CardViewStateMap | undefined;
     semanticExecutionPayload?: SemanticExecutionPayload;
     timezone?: string;
 }): FieldDateComparisonCoverage;

package/dist/types/lib/dashboard-inputs/resolve-selection-input.d.ts

@@ -0,0 +1,77 @@
+import { SelectionField, SelectionInputValue } from '../../shared/analytics-protocol/selection-contract.js';
+import { DashboardFilterTarget } from '../../shared/dashboard-authoring/index.js';
+import { ScopedDashboardInputTarget } from './dashboard-input-scope.js';
+import { NormalizedFilterDashboardInput, SelectionDashboardInput, TCard } from '../types/common-types.js';
+import { FilterCondition } from '../types/explorer-types.js';
+export type SelectionSkipReason = 
+/** A card never filters itself. */
+'sourceCard'
+/** card.respondsToSelections === false */
+ | 'receiverOptedOut'
+/** settings.targets does not include the card */
+ | 'outsideTargets'
+/** An 'excluded' card mapping */
+ | 'excludedCard'
+/** No automatic, bound, or borrowed target */
+ | 'notApplicable';
+export type SelectionBlockReason = 'ambiguousAutomaticTarget' | 'staleBinding' | 'incompatibleValueType';
+/** What one clicked field does on one target card. */
+export type SelectionConditionDisposition = {
+    status: 'apply';
+    clickedFieldKey: string;
+    target: DashboardFilterTarget;
+    provenance: 'automatic' | 'bound' | 'borrowedFromFilter';
+    /** Set when provenance is 'borrowedFromFilter'. */
+    borrowedFromInputId?: string;
+} | {
+    status: 'skip';
+    clickedFieldKey: string;
+    reason: SelectionSkipReason;
+} | {
+    status: 'block';
+    clickedFieldKey: string;
+    reason: SelectionBlockReason;
+};
+export type ResolvedCardSelection = {
+    inputId: string;
+    sourceCardId: string;
+    /** Tuples projected to the conditions this card can apply, on the target's own fields. Empty tuples removed. */
+    tuples: Array<{
+        conditions: FilterCondition[];
+    }>;
+    /** One per distinct clicked field in the value, in first-seen order. */
+    dispositions: SelectionConditionDisposition[];
+    /** 'apply' when at least one tuple survived projection. */
+    status: 'apply' | 'skip';
+};
+/** Where the target card sits. `cardId` always comes from the card itself. */
+export type SelectionTargetLocation = Omit<ScopedDashboardInputTarget, 'cardId'>;
+/**
+ * The binding a toolbar filter already accepted for the clicked field on this
+ * card. Runtime and authoring both read it here, so "Same as the Region
+ * filter" in the review dialog is exactly what a click will borrow.
+ */
+export declare function findBorrowedSelectionBinding(params: {
+    cardId: string;
+    clicked: SelectionField;
+    filterInputs: NormalizedFilterDashboardInput[];
+}): {
+    inputId: string;
+    target: DashboardFilterTarget;
+} | undefined;
+/**
+ * Decides what one source card's selection does on one target card. A viewer's
+ * click must never take a card down: a blocked condition is dropped exactly
+ * like a skipped one, and its disposition is kept so authoring can show why.
+ * Tuple shape is preserved, so two rows stay (A AND B) OR (C AND D).
+ */
+export declare function resolveSelectionInputForCard(params: {
+    /** The target card. */
+    card: TCard;
+    /** Sheet, sheet kind, and document section of the target card, as the input context already knows them. */
+    target?: SelectionTargetLocation;
+    input: SelectionDashboardInput;
+    value: SelectionInputValue;
+    /** Toolbar filters, for borrowed bindings. */
+    filterInputs: NormalizedFilterDashboardInput[];
+}): ResolvedCardSelection;

package/dist/types/lib/dashboard-inputs/selection-targets.d.ts

@@ -0,0 +1,26 @@
+import { DashboardInputValues, TDashboard } from '../types/common-types.js';
+import { ActiveSelection } from './build-selection-dashboard-inputs.js';
+import { ResolvedCardSelection } from './resolve-selection-input.js';
+export type SelectionTargetResolution = {
+    cardId: string;
+    cardTitle: string;
+    resolution: ResolvedCardSelection;
+};
+/**
+ * What one source card's selection does on every other card, each resolved
+ * where it sits. The same resolver the query path uses, so the count on the
+ * source card and the chip can never disagree with what actually refiltered.
+ */
+export declare function resolveSelectionTargets(params: {
+    dashboard: Pick<TDashboard, 'sheets' | 'inputs' | 'filters' | 'controls'>;
+    selection: Pick<ActiveSelection, 'input' | 'value'>;
+}): SelectionTargetResolution[];
+/** Target cards this selection currently narrows. */
+export declare function countSelectionTargets(params: Parameters<typeof resolveSelectionTargets>[0]): number;
+/** Active selections with the number of cards each one narrows. */
+export declare function listActiveSelectionsWithTargets(params: {
+    dashboard: Pick<TDashboard, 'sheets' | 'inputs' | 'filters' | 'controls' | 'interactionDefaults'>;
+    dashboardInputValues: DashboardInputValues | undefined;
+}): Array<ActiveSelection & {
+    targetCount: number;
+}>;

package/dist/types/lib/dashboard-inputs/transient-input-context.d.ts

@@ -0,0 +1,102 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { DashboardInputValues, NormalizedDashboardInput, ResolvedDashboardInputContext, SelectionDashboardInput } from '../types/common-types.js';
+import { SelectionInputValue, SelectionTuple } from '../../shared/analytics-protocol/selection-contract.js';
+/**
+ * Transient input context: state carried into a destination (another
+ * dashboard after a drill-through, or an insight) as definitions plus values
+ * together. The destination resolver enumerates definitions and then reads
+ * their slots, so a value with no definition is invisible, and the source card
+ * or source filter is normally absent from the destination. A carried
+ * definition is therefore self-contained and lives under one namespace.
+ */
+export type InteractionContextMode = 'interactionFilters' | 'full' | 'none';
+export type TransientInputContext = {
+    /** 'navigation:<fromDashboardId>:<depth>' or 'insight:<sourceCardId>'. */
+    namespace: string;
+    contextMode: InteractionContextMode;
+    /** Carried toolbar filters. Self-contained; see `buildTransientInputContext`. */
+    definitions: NormalizedDashboardInput[];
+    /**
+     * The carried click. Selection inputs travel on their own typed list
+     * everywhere, so no consumer can read one as a filter or a control.
+     */
+    selectionDefinitions: SelectionDashboardInput[];
+    /** Slots keyed by the namespaced definition ids, all under `shared`. */
+    values: DashboardInputValues;
+};
+/** Resolves a relative date preset to the window it means right now. */
+export type ResolveRelativeDateWindow = (relativeMeta: unknown) => [string, string] | undefined;
+export type BuildTransientInputContextParams = {
+    namespace: string;
+    contextMode: InteractionContextMode;
+    /** The clicked selection, already grounded on the source card. Ignored for 'none'. */
+    selection?: {
+        sourceCardId: string;
+        label?: string;
+        tuples: SelectionTuple[];
+    };
+    /**
+     * For 'full': the source dashboard's inputs and the context resolved for the
+     * clicked card at the moment of the click. Only inputs in that resolved
+     * context are carried, so a filter scoped away from the click never travels.
+     */
+    sourceInputs?: {
+        inputs: NormalizedDashboardInput[];
+        resolved: Pick<ResolvedDashboardInputContext, 'resolvedInputs'>;
+        /**
+         * The Global Date predicate the clicked card actually executed, from the
+         * date-materialization owner (`buildMaterializedGlobalDateFilterValue`).
+         * It names that card's primary date field, which is the field identity a
+         * Global Date input does not have on its own.
+         */
+        materializedGlobalDate?: TFilterValue;
+    };
+    /** Card ids on the destination, for pruning carried bindings. */
+    destinationCardIds: string[];
+    /**
+     * When given, a relative preset is resolved to its window at capture time.
+     * Without it the stored values are kept. Either way the carried value holds
+     * no relative meta, so nothing re-expands it later.
+     */
+    resolveRelativeDateWindow?: ResolveRelativeDateWindow;
+};
+/**
+ * Builds the context a destination resolves. Rules, applied to every carried
+ * definition in this order:
+ *
+ * 1. Materialize the effective value: only an input the source resolved to a
+ *    usable filter value is carried, as a `set` slot. A cleared, default-less
+ *    or invalid input does not travel.
+ * 2. Materialize the effective field identity from the anchored value.
+ * 3. Strip browsing and source-only metadata (option source, dependencies,
+ *    population, compatibility, filter reference, force and required flags).
+ * 4. Rescope to the destination: namespaced id, all sheets, shared slot.
+ * 5. Namespace the alias.
+ * 6. Prune bindings to the destination's cards. Every carried filter keeps a
+ *    mapping application, empty when nothing survives, so the destination
+ *    resolves it per card: automatically on the same dataset, otherwise skip.
+ * 7. Never carry a Global Date input. Its executed predicate travels as an
+ *    ordinary field filter with the same operator, values and precision.
+ */
+export declare function buildTransientInputContext(params: BuildTransientInputContextParams): TransientInputContext;
+/** The carried selections of a set of contexts, with the value each one holds. */
+export declare function listTransientSelections(transientContexts: readonly TransientInputContext[] | undefined): Array<{
+    input: SelectionDashboardInput;
+    value: SelectionInputValue;
+}>;
+/**
+ * The context mode that governs a resolution: whether the dashboard's own
+ * toolbar filters apply next to what was carried. A resolution has at most one
+ * governing context (the top navigation entry's, or an insight's runtime), so
+ * the first one decides. Undefined outside a drill: everything applies.
+ */
+export declare function resolveTransientContextMode(transientContexts: readonly TransientInputContext[] | undefined): InteractionContextMode | undefined;
+/** True when a context carries a definition the resolver has to enumerate. */
+export declare function hasCarriedTransientDefinitions(transientContexts: readonly TransientInputContext[] | undefined): boolean;
+/**
+ * Reads carried contexts that crossed a URL or JSON boundary (a print or embed
+ * snapshot). A malformed context is dropped, never thrown on; a carried
+ * selection is validated again where it is read (`listTransientSelections`).
+ * Returns undefined when nothing usable is left.
+ */
+export declare function parseTransientInputContexts(value: unknown): TransientInputContext[] | undefined;

package/dist/types/lib/dashboard-navigation/build-carried-click-context.d.ts

@@ -0,0 +1,50 @@
+import { DashboardInputRuntimeValues } from '../dashboard-inputs/resolve-dashboard-input-context.js';
+import { InteractionContextMode, ResolveRelativeDateWindow, TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+import { CardViewState } from '../dashboard-view-state/index.js';
+import { TCard, TDashboard } from '../types/common-types.js';
+import { ClickFilterCondition } from '../types/interaction-types.js';
+import { SemanticExecutionPayload } from '../types/semantic-runtime-types.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+import { DashboardNavigationTrigger } from './navigation-state.js';
+/**
+ * What a drill carries away from a click, built at the moment of the click
+ * from the state the clicked card was executing under. The one caller-side
+ * owner of that capture: drill-through and drill to insight both use it, so
+ * the context-mode table is implemented once.
+ */
+export type BuildCarriedClickContextParams = {
+    namespace: string;
+    contextMode: InteractionContextMode;
+    /** The clicked card, on the dashboard below. */
+    card: TCard;
+    /** Conditions the matched interaction keeps from the click. */
+    conditions: ClickFilterCondition[];
+    /** Shown by navigation and insight chrome. */
+    label?: string;
+    dashboard: TDashboard;
+    sheetId: string | null | undefined;
+    runtimeValues: DashboardInputRuntimeValues;
+    cardViewState: CardViewState | undefined;
+    /** The carried contexts the clicked card itself resolves under. */
+    sourceTransientContexts: readonly TransientInputContext[] | undefined;
+    /**
+     * Under `full`, whether the source dashboard's own toolbar filters travel.
+     * A drill-through carries them to the other dashboard. An insight renders on
+     * this dashboard, where those filters keep applying live, so carrying a
+     * frozen copy would pin the insight to a value the viewer has since changed.
+     * What the source itself received always travels under `full`.
+     */
+    carryOwnToolbarFilters: boolean;
+    /** Card ids on the destination, for pruning carried bindings. Empty when unknown. */
+    destinationCardIds: string[];
+    semanticExecutionPayload?: SemanticExecutionPayload;
+    calendarContext?: CalendarContext | null;
+    dashboardInputReferenceTime?: string;
+    resolveRelativeDateWindow?: ResolveRelativeDateWindow;
+};
+export type CarriedClickContext = {
+    /** Display-only: the click as the viewer made it, in every context mode. */
+    trigger: DashboardNavigationTrigger;
+    carried: TransientInputContext;
+};
+export declare function buildCarriedClickContext(params: BuildCarriedClickContextParams): CarriedClickContext;

package/dist/types/lib/dashboard-navigation/describe-carried-context.d.ts

@@ -0,0 +1,11 @@
+import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+import { SelectionTuple } from '../../shared/analytics-protocol/selection-contract.js';
+/** One line of "what came along": a field and the value it was narrowed to. */
+export type CarriedContextItem = {
+    fieldName: string;
+    value: string;
+};
+/** The click, as chrome shows it. Works for a display-only trigger too. */
+export declare function describeSelectionTuples(tuples: readonly SelectionTuple[]): CarriedContextItem[];
+/** Everything a carried context applies: the click, then the carried toolbar filters. */
+export declare function describeCarriedContext(context: TransientInputContext): CarriedContextItem[];

package/dist/types/lib/dashboard-navigation/index.d.ts

@@ -0,0 +1 @@
+export * from './navigation-state.js';

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

@@ -0,0 +1,120 @@
+import { BuildTransientInputContextParams, TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+/**
+ * Navigation and insight state: where a viewer drilled through to, what they
+ * carried there, and which insights are open on which cards. Session only,
+ * never persisted. The reducers here are pure; the dashboard store applies
+ * them, each as one transition, so the dashboard to show and the context that
+ * applies on it can never be observed out of step.
+ */
+/** The click shown by navigation chrome, independent of what executes on the destination. */
+export type DashboardNavigationTrigger = NonNullable<BuildTransientInputContextParams['selection']>;
+/** One drill-through: the dashboard it left, the one it opened, and what came along. */
+export type DashboardNavigationEntry = {
+    fromDashboardId: string;
+    fromDashboardTitle?: string;
+    toDashboardId: string;
+    toDashboardTitle?: string;
+    /** Kept even when `contextMode: 'none'` carries no executable selection. */
+    trigger: DashboardNavigationTrigger;
+    carried: TransientInputContext;
+};
+/** The dashboard navigation says to show. Selection of the loaded dashboard follows it. */
+export type DashboardNavigationTarget = {
+    dashboardId: string;
+    title?: string;
+    /** Why the target changed, so a follower can tell a drill from a step back. */
+    reason: 'drillThrough' | 'back';
+};
+/** Transient contexts that are valid only while one dashboard is rendered. */
+export type DashboardTransientContextScope = {
+    dashboardId: string;
+    contexts: readonly TransientInputContext[];
+};
+/** One insight opened from a card, with the runtime it renders under. */
+export type InsightRenderRequest = {
+    insightId: string;
+    sourceCardId: string;
+    displayMode: 'modal' | 'replaceCard';
+    /** The only transient context the insight resolves. Namespace `insight:<sourceCardId>`. */
+    runtime: TransientInputContext;
+};
+export type DashboardNavigationState = {
+    /** Oldest first. The last entry is where the viewer is. */
+    navigationStack: DashboardNavigationEntry[];
+    /** Null until navigation first moves the viewer. */
+    navigationTarget: DashboardNavigationTarget | null;
+    /** Keyed by source card id: a card shows at most one insight. */
+    insightRenderRequests: Record<string, InsightRenderRequest>;
+};
+export declare const INITIAL_DASHBOARD_NAVIGATION_STATE: DashboardNavigationState;
+/** The namespace of the context carried by the entry pushed at `depth`. */
+export declare function navigationNamespace(fromDashboardId: string, depth: number): string;
+export declare function insightNamespace(sourceCardId: string): string;
+export type NavigationRejection = 
+/** An id is missing, so there is nowhere to go or to come back to. */
+'incompleteEntry'
+/** The entry does not leave the dashboard at the current end of the chain. */
+ | 'sourceMismatch'
+/** The carried namespace is not the one this depth owns, so ids could collide with an entry already on the stack. */
+ | 'namespaceMismatch';
+export type NavigateResult = {
+    status: 'navigated';
+    state: DashboardNavigationState;
+} | {
+    status: 'rejected';
+    reason: NavigationRejection;
+    state: DashboardNavigationState;
+};
+/**
+ * Drill through: push the entry and point navigation at its destination.
+ * Insights belong to cards of the dashboard being left, so they close in the
+ * same transition. A rejected entry changes nothing.
+ */
+export declare function navigateToDashboardInState(state: DashboardNavigationState, entry: DashboardNavigationEntry): NavigateResult;
+/**
+ * One step back: pop the top entry and point navigation at the dashboard it
+ * left. What applies there is whatever the new top carried, or nothing at the
+ * root. Returns the same state when there is nowhere to go back to.
+ */
+export declare function goBackInState(state: DashboardNavigationState): DashboardNavigationState;
+/**
+ * Forget the drill history and stay where the viewer is: the carried context
+ * stops applying and there is nothing to go back to. Open insights stay; they
+ * belong to the cards on screen.
+ */
+export declare function clearNavigationInState(state: DashboardNavigationState): DashboardNavigationState;
+/** Opens an insight on a card, replacing the one that card already showed. */
+export declare function openInsightRequestInState(state: DashboardNavigationState, request: InsightRenderRequest): DashboardNavigationState;
+/**
+ * Closes the insight on a card. Also the answer to a card that changes id or
+ * is removed: the runtime's ids derive from `insight:<sourceCardId>`, so a
+ * request cannot follow its card to a new id, and both are authoring actions.
+ */
+export declare function closeInsightRequestInState(state: DashboardNavigationState, sourceCardId: string): DashboardNavigationState;
+export declare function closeAllInsightRequestsInState(state: DashboardNavigationState): DashboardNavigationState;
+/**
+ * The carried context in effect on `dashboardId`: the top entry's, and only on
+ * the dashboard it was carried to. Deeper entries are history, not context; a
+ * `full` drill from B to C already re-carried what B had received from A. The
+ * result is reference-stable per entry, so it is safe as a store selector.
+ */
+export declare function selectActiveTransientContexts(state: Pick<DashboardNavigationState, 'navigationStack'>, dashboardId: string | null | undefined): readonly TransientInputContext[];
+/**
+ * What every live reader resolves a dashboard's cards with. Replay and
+ * navigation-handoff contexts are accepted only for the dashboard named by
+ * their scope. Otherwise the committed navigation entry decides.
+ * Reference-stable for direct store use.
+ */
+export declare function selectEffectiveTransientContexts(state: Pick<DashboardNavigationState, 'navigationStack' | 'navigationTarget'> & {
+    restoredTransientContextScope: DashboardTransientContextScope | null;
+    outgoingTransientContextScope: DashboardTransientContextScope | null;
+}, dashboardId: string | null | undefined): readonly TransientInputContext[];
+/** The context mode governing the dashboard's own toolbar filters, or undefined outside a drill. */
+export declare function selectNavigationContextMode(state: Pick<DashboardNavigationState, 'navigationStack'>, dashboardId: string | null | undefined): TransientInputContext['contextMode'] | undefined;
+/** The click that opened `dashboardId`, including under context mode `none`. */
+export declare function selectNavigationTrigger(state: Pick<DashboardNavigationState, 'navigationStack'>, dashboardId: string | null | undefined): DashboardNavigationTrigger | undefined;
+/** Where "Back" leads from `dashboardId`, or undefined when the viewer did not drill here. */
+export declare function selectBackDestination(state: Pick<DashboardNavigationState, 'navigationStack'>, dashboardId: string | null | undefined): {
+    dashboardId: string;
+    title?: string;
+} | undefined;

package/dist/types/lib/dashboard-navigation/run-one-off-drill.d.ts

@@ -0,0 +1,11 @@
+import { TCard } from '../types/common-types.js';
+import { DrillThroughEvent, DrillToDetailEvent } from '../types/interaction-types.js';
+/** A drill that leaves the card: to another dashboard, or into an insight. */
+export type OneOffDrillEvent = DrillThroughEvent | DrillToDetailEvent;
+/**
+ * Runs a one-off drill from the click that raised it. The carried context is
+ * captured here, at the moment of the click, from the state the clicked card
+ * was executing under; nothing is read again later. Returns false when the
+ * drill has no target to open.
+ */
+export declare function runOneOffDrill(card: TCard, event: OneOffDrillEvent): boolean;

package/dist/types/lib/dashboard-navigation/use-transient-contexts.d.ts

@@ -0,0 +1,17 @@
+import { TransientInputContext } from '../dashboard-inputs/transient-input-context.js';
+/**
+ * Set by an insight viewer around the card it renders: that card resolves only
+ * under the insight's own runtime, never under what navigation carried to the
+ * dashboard behind it.
+ */
+export declare const InsightRuntimeContext: import('react').Context<readonly TransientInputContext[] | null>;
+/** The carried contexts in effect on the dashboard being rendered. */
+export declare function useDashboardTransientContexts(): readonly TransientInputContext[];
+/**
+ * The carried contexts a card resolves under: the enclosing insight's runtime,
+ * otherwise the dashboard's. Every live reader that resolves inputs or builds
+ * a query context for a card reads this one value for both.
+ */
+export declare function useCardTransientContexts(): readonly TransientInputContext[];
+/** Non-reactive read for code that runs outside React (exports, the assistant). */
+export declare function getDashboardTransientContexts(): readonly TransientInputContext[];

package/dist/types/lib/dashboard-view-state/card-view-state.d.ts

@@ -0,0 +1,48 @@
+import { Field, TimeGranularity } from '../types/explorer-types.js';
+import { ClickedMetricValue, ClickFilterCondition } from '../types/interaction-types.js';
+/**
+ * Card view state: session-only state that changes how one card is queried or
+ * shown without changing its authored definition. It lives in the dashboard
+ * store next to the input values, travels in the dashboard input execution
+ * snapshot, and is never persisted with the dashboard.
+ */
+/** One level of a drill: the member the viewer drilled into and the field the card groups by afterwards. */
+export type DrillStep = {
+    /** The field the card groups by after this step. */
+    toField: Field;
+    /**
+     * The member that was drilled into, AND-ed. These are the card's own fields:
+     * a drill narrows the card it happened on, so its conditions stay in that
+     * card's field vocabulary and need no grounding on another source.
+     */
+    conditions: ClickFilterCondition[];
+    /** Breadcrumb text. */
+    label: string;
+    granularity?: TimeGranularity;
+    /** The clicked metric. Display only; never part of the query. */
+    metric?: ClickedMetricValue;
+};
+export type CardDrillPath = {
+    /** Set while the viewer walks an authored hierarchy; absent for a dynamic drill. */
+    hierarchyId?: string;
+    steps: DrillStep[];
+};
+export type CardViewState = {
+    drill?: CardDrillPath;
+};
+export type CardViewStateMap = Record<string, CardViewState>;
+/** Shared empty path, so selectors return a stable reference. */
+export declare const EMPTY_DRILL_STEPS: DrillStep[];
+export declare function drillStepLabel(toField: Field): string;
+export declare function pushDrillStepToViewState(viewState: CardViewState | undefined, step: DrillStep, hierarchyId?: string): CardViewState;
+/** Removes the last step. Returns undefined when nothing is left to keep for the card. */
+export declare function popDrillStepFromViewState(viewState: CardViewState | undefined): CardViewState | undefined;
+/**
+ * Reads card view state that crossed a serialization boundary (the print URL,
+ * a stored export request). A card whose drill path is not well formed is
+ * dropped whole: half a drill path would group by one level and filter by
+ * another.
+ */
+export declare function parseCardViewStateMap(value: unknown): CardViewStateMap;
+/** Only cards that hold a drill path; an export should not carry empty entries. */
+export declare function compactCardViewStateMap(viewStates: CardViewStateMap | undefined, cardIds?: ReadonlySet<string>): CardViewStateMap | undefined;

package/dist/types/lib/dashboard-view-state/drill-path.d.ts

@@ -0,0 +1,20 @@
+import { TCard } from '../types/common-types.js';
+import { CardConfig, FilterGroup } from '../types/explorer-types.js';
+import { ShelfCard } from '../utils/card-definition.js';
+import { CardDrillPath } from './card-view-state.js';
+/**
+ * The card's configuration at the current drill level. Matrix runtime filters
+ * travel separately from the authored definition and its interactions never
+ * replace an axis through ordinary drill shelves, so a non-shelf card keeps
+ * its configuration unchanged.
+ */
+export declare function applyDrillPathToCardConfig(card: TCard, drill: CardDrillPath | undefined): CardConfig;
+/** Grouped by the last step's field, with a sort on the old grouping following it. */
+export declare function applyDrillPathToShelfCardConfig(card: ShelfCard, drill: CardDrillPath | undefined): CardConfig;
+/**
+ * The members drilled into, as one filter group: AND across steps, AND within
+ * a step. Each step keeps the three-level shape selections compile to (root,
+ * one group per step, one group per member) so `explore-query` sees one shape.
+ * Ids derive from position, so the same path always yields the same query key.
+ */
+export declare function drillPathFilterGroup(drill: CardDrillPath | undefined, cardId: string): FilterGroup | undefined;

package/dist/types/lib/dashboard-view-state/index.d.ts

@@ -0,0 +1,2 @@
+export * from './card-view-state.js';
+export * from './drill-path.js';

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

@@ -3,7 +3,6 @@ import { AuthToken, ControlBinding, ControlDefinition, DashboardInputExecutionSn
 import { TChartType } from './charts/types.js';
 import { FastPathTableStructure } from '../shared/format-utils/table-structure.js';
 import { PresentationExecutionSnapshot } from '../shared/format-utils/index.js';
-import { InteractionState } from './types/interaction-types.js';
 import { buildMatrixDeliveryPayload } from './matrix-table/matrix-delivery.js';
 export type MatrixPdfCapture = ReturnType<typeof buildMatrixDeliveryPayload>;
 export type DashboardParams = {
@@ -17,7 +16,6 @@ export type DashboardParams = {
     selectedSheetId?: string;
     dashboardId: string;
     dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
-    interactionExecutionSnapshot?: Record<string, InteractionState>;
     presentationExecutionSnapshot: PresentationExecutionSnapshot;
     timezone?: string;
 };
@@ -35,7 +33,6 @@ export type VisualPdfParams = {
     cardTitle: string;
     dashboardId: string;
     dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
-    interactionExecutionSnapshot?: Record<string, InteractionState>;
     presentationExecutionSnapshot: PresentationExecutionSnapshot;
     timezone?: string;
 };

package/dist/types/lib/formatters/metric-formatting.d.ts

@@ -21,7 +21,7 @@ type ContextResolution = {
 export declare function hasExplicitFormatOptions(formatOptions?: TFormatOptions | null): boolean;
 export declare function getMetricColumnKey(metric?: Pick<MetricField, 'alias' | 'label' | 'name'> | null): string | undefined;
 export declare function findMetricFieldForColumn(card: TCard | undefined, lookup: MetricLookup): MetricField | undefined;
-export declare function findPresentationFieldForColumn(card: TCard | undefined, lookup: MetricLookup): (MetricField | GroupByField | DetailField) | undefined;
+export declare function findPresentationFieldForColumn(card: TCard | undefined, lookup: MetricLookup): (GroupByField | MetricField | DetailField) | undefined;
 export declare function normalizePersistedColumnSettings(settings: PersistedColumnSettings | undefined): ColumnSettings | undefined;
 export declare function normalizePersistedColumnSettingsMap(settings: PersistedColumnSettingsMap | undefined): ColumnSettingsMap;
 export declare function serializeEditedColumnSettings(params: {

package/dist/types/lib/hooks/ai/dashboard-context.d.ts

@@ -1,13 +1,14 @@
+import { CardViewStateMap } from '../../dashboard-view-state/index.js';
 import { TFilterValue } from '../../../components/surfboard/filter/types.js';
 import { DashboardSynopsis, AssistantCardContext, DashboardViewState } from '../../types/assistant-types.js';
-import { TCard, TDashboard } from '../../types/common-types.js';
+import { DashboardInputValues, TCard, TDashboard } from '../../types/common-types.js';
 import { CalendarContext } from '../../../shared/report-runtime-context/index.js';
-import { InteractionState } from '../../types/interaction-types.js';
+import { TransientInputContext } from '../../dashboard-inputs/transient-input-context.js';
 type ReplacedCardContext = {
     insightId: string;
     visibleCard: TCard;
-    filters?: unknown[];
-    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /** The insight's own runtime: the only carried context its card resolves under. */
+    runtime: TransientInputContext;
 };
 export declare function buildDashboardViewState({ dashboard, selectedSheetId, activeFilters, calendarContext, }: {
     dashboard: TDashboard;
@@ -15,19 +16,25 @@ export declare function buildDashboardViewState({ dashboard, selectedSheetId, ac
     activeFilters: TFilterValue[] | undefined;
     calendarContext?: CalendarContext;
 }): DashboardViewState;
-export declare function buildDashboardSynopsis({ dashboard, viewState, interactionStates, inlineFilterValuesMap, replacedCards, }: {
+export declare function buildDashboardSynopsis({ dashboard, viewState, transientContexts, cardViewStates, inlineFilterValuesMap, dashboardInputValues, replacedCards, }: {
     dashboard: TDashboard;
     viewState: DashboardViewState;
-    interactionStates?: Record<string, InteractionState | undefined>;
+    /** Carried contexts in effect on the dashboard; see `buildCardQueryContext`. */
+    transientContexts: readonly TransientInputContext[] | undefined;
+    cardViewStates?: CardViewStateMap;
     inlineFilterValuesMap?: Record<string, TFilterValue[] | undefined>;
+    dashboardInputValues?: DashboardInputValues;
     replacedCards?: Record<string, ReplacedCardContext>;
 }): DashboardSynopsis;
-export declare function buildCardContext({ dashboard, viewState, cardId, runtimeFilterValues, interactionStates, inlineFilterValuesMap, replacedCards, }: {
+export declare function buildCardContext({ dashboard, viewState, cardId, runtimeFilterValues, dashboardInputValues, transientContexts, cardViewStates, inlineFilterValuesMap, replacedCards, }: {
     dashboard: TDashboard;
     viewState: DashboardViewState;
     cardId: string;
     runtimeFilterValues?: TFilterValue[] | undefined;
-    interactionStates?: Record<string, InteractionState | undefined>;
+    dashboardInputValues?: DashboardInputValues;
+    /** Carried contexts in effect on the dashboard; see `buildCardQueryContext`. */
+    transientContexts: readonly TransientInputContext[] | undefined;
+    cardViewStates?: CardViewStateMap;
     inlineFilterValuesMap?: Record<string, TFilterValue[] | undefined>;
     replacedCards?: Record<string, ReplacedCardContext>;
 }): AssistantCardContext;

package/dist/types/lib/hooks/chartjs/use-chart-blur.d.ts

@@ -1,6 +1,14 @@
 import { TCard } from '../../types/index.js';
 import { Chart } from 'chart.js/auto';
-export declare function useChartBlur(card: TCard): {
-    handleChartClick: (e: any, chart: Chart) => void;
+/**
+ * Source-only highlight for a chart's own selection. The caller says whether
+ * click to filter is on and which gesture the click was, so the faded marks
+ * follow the same replace and toggle rules as the selection itself.
+ */
+export declare function useChartBlur(card: TCard, { isEnabled, hasSelection }: {
+    isEnabled: boolean;
+    hasSelection: boolean;
+}): {
+    handleChartClick: (e: any, chart: Chart, intent: "replace" | "toggle") => void;
     clearBlur: (chart: Chart | null) => void;
 };